Ethernet tools (mega65_ftp and etherload)

Owned by Gurce Isikyildiz
Last updated: Sept 08, 2023 by Robert Steffens

 

The MEGA65 can use ethernet for SD card access and starting programs remotely by using the tools mega65_ftp and etherload. The tools are command-line applications, so you should be familiar with using these kinds of programs in a terminal. This guide also assumes that you know how to install a new core into one of the slots 1-7.

Set Up

  • The PC/Mac and your MEGA65 need to be connected to the same ethernet network.

  • You need to know one free IP address within your network that will be specified to be used by your MEGA65.

  • You need to have a recent development core installed and booted up in any of slots 1-7.
    !! Do NOT install development cores into slot 0 !!

    • Development cores available here:

    • Any mega65-core from development branch dated September 07, 2023 or later should work.

    • Select the correct file for your MEGA65 model. Batch 1 and 2 owners need to install the mega65r3 core.

    • Please be aware that these cores are still experimental and not official stable releases!

  • Download the latest version of the development branch mega65-tools to your PC, which you can find on Filehost:

  • You need to put the file ETHLOAD.M65 into the root folder of your SD card.

    • You can download it here:

    • It can also be found within the development core’s .7z file you downloaded above, in the sdcard-files/ folder

  • Configure a valid MAC address for the ethernet port of your MEGA65. This can be done in the configuration menu available when pressing ALT during power on and then selecting 1.

    • Make sure you set a valid MAC address different to 00:00:00:00:00:00.

    • If in doubt, config can create a valid random MAC address when pressing the R key.

    • Be aware the MAC address is saved to your SD card, so you may need re-configure this if creating a new SD card.

  • The DIP switch #2 on your MEGA65 mainboard needs to be set to ON:

     

  • Finally, do a power-cycle of the MEGA65 and make sure you boot into the correct development core you installed. Then, press Shift-£ to enable ethernet remote control. This is a security measure to only allow remote access to your MEGA65 if explicitly activated by the user via this key combination. The power LED will start blinking green/yellow to indicate your MEGA65 can be used with mega65_ftp or etherload. Remote control needs to be re-enabled after a reset or power-off.

You should avoid to activate remote control if your MEGA65 is operated in a public or unknown network, as it allows others in your network to remote control your MEGA65 and have access to your SD card.

IP Addresses

For the following examples, we will assume your PC/Mac network interface to be configured as 192.168.1.1/24 (IP address 192.168.1.1 with subnet mask 255.255.255.0). If the IP address range of your network is different (which in many cases will just be a different third decimal number), please adjust the IP addresses given in the examples below accordingly.

If your PC/Mac uses the IP address 192.168.1.1, then you need to assign an IP address to you MEGA65 in the same subnet (eg. 192.168.1.2 - 192.168.1.254). It is important to make sure the IP address you select is not already in use within your network.

The tools mega65_ftp and etherload both use an initial special network packet to initiate the connection to the MEGA65 which is sent via the so called “broadcast” address of your network. This is usually the IP address of your PC/Mac having the last number replaced with .255 (eg. 192.168.1.255). The tools will automatically determine the correct broadcast address to use depending on the IP address you specify to be used by the MEGA65.

‘mega65_ftp’ over ethernet usage

The mega65_ftp tool is a command-line application allowing to upload and download files to/from the SD card of the MEGA65.

Make sure the remote access to the MEGA65 is activated first via Shift-£. The power LED needs to be blinking green/yellow!

In order to use mega65_ftp via network, provide the IP address to be used by the MEGA65 as argument to the -i parameter:

mega65_ftp -i 192.168.1.2

You can now transfer files via put and get commands. Enter help to get a list of available commands.

Commands can also be provided directly on the command-line instead of typing them in interactively. This is useful when using mega65_ftp in scripts to automatically perform a specific upload or download task:

mega65_ftp -i 192.168.1.2 -c "put myimage.d81" -c "quit"

This will upload the file myimage.d81 from the current PC/Mac directory to the SD card.

‘etherload’ usage

The etherload tool is used to upload programs directly into the RAM of the MEGA65 and execute them there. This is especially useful for a cross-development environment.

Again, please make sure the remote access to the MEGA65 is activated first via Shift-£ - the power LED needs to be blinking green/yellow!

Starting programs remotely

The simplest way of using etherload is to provide a prg file as argument and use the -r parameter to run it:

etherload -i 192.168.1.2 -r <file.prg>

The tool will determine which mode the program needs to run in (C64 or MEGA65 mode) and will do an automatic reset to the respective mode before starting the program.

The etherload program will need to do a reset first to make sure the system is in the right state. This is a fundamental difference to the m65 tool which can do a reset before RUN but does not require it. The m65 tool does not support ethernet functionality, though.

If your program requires a MOUNT command first to have a D81 mounted from SD card, you can specify this via the -m parameter:

etherload -i 192.168.1.2 -m MYIMAGE.D81 -r <file.prg>

Please make sure the D81 image file is already on the SD card before running this command (for example, by uploading it first via mega65_ftp).

Starting machine language programs

The above commands work well for programs that provide BASIC code allowing them to be executed via RUN. If you want to start a machine language program, you need to provide its starting address in hexadecimal notation:

etherload -i 192.168.1.2 -j 8000 <file.prg>

In this case, the machine will not be reset first and etherload will do a JMP to the provided address. The started program needs to configure relevant I/O registers as needed.

When using the -j parameter, etherload will jump to the address with a cleared memory mapping, having only I/O mapped at $D000. Also, interrupts will be disabled when jumping to your address. This implies that the start address needs to be located in BANK 0. You will need to provide a complete initialisation routine in your program to setup the VIC-IV according to your needs.

The -j parameter will be especially useful for game developers as they will initialise the machine state (incl. VIC-IV parameters) anyway.

The target address will be determined by the first two bytes in the provided file. If the file does not have its loading address in the first two bytes, it can be provided via the -b parameter:

etherload -i 192.168.1.2 -b 8000 -j 8000 <file.prg>

The loading address and the jump address can of course be different addresses.

Uploading multiple memory segments

Sometimes it is useful to upload several data files to different specific locations before uploading and starting the program. Think of developing a game that needs to load asset data files on startup: Instead of loading the files each time you start a new revision of your game during development, you can temporarily disable your loading routine and instead use etherload to upload the data directly into memory.

Let’s assume we have two files gfx.dat and music.dat that we want to load at addresses $20000 and $8000 before we start the main program. This can be done by calling etherload several times, but using the parameter --halt for every invocation except the last one. This will instruct etherload to not jump to any address when done but instead wait for further etherload executions to continue loading data.

etherload -i 192.168.1.2 -b 20000 --halt gfx.dat etherload -i 192.168.1.2 -b 8000 --halt music.dat etherload -i 192.168.1.2 -j 2016 game.prg

This will load the game asset files first and then will load the file game.prg and jump to address $2016 to execute it.

Note that game.prg might be a game with a BASIC header to start it, but we are not using the -r parameter but instead -j to start it (using the address that the BASIC header would have called in its SYS command). This is done for a reason as -r will restore the ROM at $20000-$3ffff first to be able to do a reset. This would overwrite our gfx.dat bytes we put at $20000. Using -j instead will ensure we have full control over the complete memory. That way you can preload any bytes in chip ram or attic ram prior to starting your code.

If you want to skip bytes of a file when loading it to memory, you can also use the --offset parameter. This one will skip the provided number of bytes (in hexadecimal notation) when loading the file. Let’s assume we have the program game.prg with a start address of $2001, and we only want to load it from address $2100 (which may be its entry point), then we need to skip the first 255 bytes for loading.

etherload -i 192.168.1.2 -j 2100 --offset ff game.prg

Using custom ROM files

If you have a specific ROM file on your PC/Mac that you want to run, you can use the -R parameter:

etherload -i 192.168.1.2 -R 920384.ROM

This will load the ROM file “920384.ROM” from your PC/Mac, upload it to the memory of the MEGA65, and reset into that new ROM. As this upload and reset is amazingly fast, you can use this to quickly test different revisions of the ROM without having to upload them to SD card and doing a full reset on your MEGA65.

If you want to start a program together with a specific ROM revision, you can combine the -R parameter with a program file to execute:

etherload -i 192.168.1.2 -R 920384.ROM -r <file.prg>

 

Troubleshooting

I installed a development core as required, but pressing Shift-£ has no effect. The power LED does not start blinking.

Please check whether the correct core is actually running. Note that if you exit from configuration, the core from slot 0 is started and not the default core in slot 1! You may need to power-cycle after exiting configuration.
Another reason why Shift-£ is not working may be you forgot to set DIP switch #2 to ON.

When starting mega65_ftp or etherload, I can see the MEGA65 reacts, but then it just hangs without continuing.

This can happen if you forgot to put ETHLOAD.M65 into the root of your SD card. It can also be the ETHLOAD.M65 is outdated. Please try to flash the latest core and put the ETHLOAD.M65 file provided with that core archive on your SD card.

When starting mega65_ftp, it freezes on a screen like this:

Kibo described this in the following discord thread as an ARP issue.

  • If you have recently changed to a new SD-card, assure that the mac address for it is set to the same one as used in your old SD-card.

 

When starting mega65_ftp, it freezes on a screen like this:

This was a bug in older cores (tx packet overwriting colour ram). To resolve:

  • On your core 1 slot, assure you are running a mega65-core from development branch dated September 07, 2023 or later

  • Despite having this newer core in slot 1, you might also accidentally find yourself booting to an older slot 0 core

  • For example, if you had just entered the m65-config menu on boot-up (which is in core0), once you exit this, the system continues to boot to slot 0 (which might be an older core with the issue).

  • NOTE: The git-hash of your core is shown in the bottom-right of the MEGA65 Ethernet File Transfer Helper program (as in the screenshot above), in-case you need to confirm what you have.