Ethernet tools (mega65_ftp and etherload)

Introduction

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, else you can download the GUI-tool M65Connect from Filehost. This guide also assumes that you know how to install a new core into one of the slots 1-7.

Set up

Before you start make sure:

  • The PC/Mac and your MEGA65 need to be connected to the same ethernet network (this includes a direct cable connection between them or a connection through one or more switches).

  • IPv6 needs to be enabled on the network interface on your PC/Mac (this is default but you may have changed it)

  • If you have a MEGA65 (R6) produced/delivered in 2024, you can directly skip to section Test Ethernet Connection below, as your MEGA65 is already configured correctly and has the needed core pre-installed.

Hardware configuration

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

This step is not necessary for MEGA65 (R6) produced in 2024 and delivered from batch #3.
DIP switch 2 is already ON for these devices.

 

  1. Unplug any cables attached to the MEGA65 (power, video, etc.)

  2. Turn the MEGA65 to the back side and open the housing by removing the three lower screws:

    backside_mega65_4tgZpx.png
  3. Locate the DIP switch on the right side of the mainboard:

    image-20230425-112225.png
  4. Use a small screwdriver or a pen to set DIP switch #2 to ON position. Be aware the DIP switch is up-side-down.

  5. Close the housing, put back the three screws and plug all cables.


Download recent core

This step is not necessary for MEGA65 (R6) produced in 2024 and delivered from batch #3.
The core installed on those already supports ethernet remote control.

You need to update your MEGA65 to release version 0.96. Have a look into the User's Guide chapter 5 (“Upgrading the MEGA65”) for details on how to get the latest released core and ROM installed.

Set up MAC address

Configure a valid MAC address for the ethernet port of your MEGA65.

  1. Press the ALT key during power on and then press key 1 to start the Configuration Tool.

  2. Use the Cursor Right key to head to the NETWORK section.

  3. Make sure the MAC address is not 00:00:00:00:00:00. If in doubt what MAC address to enter, press the R key to let the Configuration Tool create a valid random MAC address for you.

  4. Use Cursor Right key again to head to DONE section.

  5. Head to SAVE AS DEFAULTS AND EXIT with Cursor Down key.

  6. Head to OK with Cursor Down key and press RETURN key to save the current settings..

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 MAC address is automatically reset to a new random MAC address if you re-format the SD card or use the MEGA65 Onboarding utility.


Test ethernet connection

After all you want to check your ethernet connection is properly working. MEGA65 (R6) owners with units produced/delivered in 2024 can directly go to step 3. as their default core in slot 1 will by default work.

  1. If you
    - have a MEGA65 (R6) produced/delivered in 2024; or
    - installed the 0.96 core in slot 1,
    you can just power on your MEGA65 as usual and proceed with step 4.

  2. Hold key NO SCROLL while powering on the MEGA65.

  3. Select the core slot you have previously installed by pressing the correct key Number or using the Cursor keys and RETURN key. The MEGA65 now boots with the selected core.

  4. Press the keys SHIFT and £ (pound) to enable the 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. By pressing the key combination a special char is printed which you can ignore.
    If you have done everything right 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.

Working with mega65_ftp and etherload

Download MEGA65 Tools

This step is not necessary if you plan to work with M65Connect.

  1. Download the latest version of the development branch mega65-tools to your PC, which you can find on Filehost and contains the required CLI tools etherload and mega65_ftp:

  2. Extract the package and copy the OS related CLI tools. On macOS, please make sure to not put the binaries in your Downloads or Documents folder (or in any sub-folder of those), as they won’t function correctly due to additional security restrictions macOS applies to executables placed there.

  3. Copy the required files etherload(.exe/.osx) and mega65_ftp(.exe/.osx) where you want to have them.


IPv6

The MEGA65 will communicate via a link-local IPv6 address that it automatically generates from its MAC address (EUI-64). In order for your PC/Mac to communicate with the MEGA65, you need to enable IPv6 support on your network interface that is connected to the MEGA65. All modern operating systems have IPv6 enabled by default. Unless you manually disabled it, everything should work.


How to use mega65_ftp

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

In order to use mega65_ftp via ethernet, just provide the -e parameter:

mega65_ftp -e

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 -e -c "put myimage.d81" -c "quit"

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


How to use etherload

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.


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 -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.

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 -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 -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.

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 -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 -b 20000 --halt gfx.dat etherload -b 8000 --halt music.dat etherload -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.

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 -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 -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 -R 920384.ROM -r <file.prg>


Speeding up start-up time

Etherload and mega65_ftp can start faster if you directly provide the IPv6 address and interface identifier where the MEGA65 is connected to. This is because then the auto-discovery will be skipped, saving up to one second during startup.

You can trigger auto-discovery manually via etherload to find out which IP address and interface identifier to use:

etherload --discover MEGA65 found at fe80::d5ff:fe16:0%eth0

You can then us the string provided for your next launch of etherload or mega65_ftp:

etherload -i fe80::d5ff:fe16:0%eth0 -r <file.prg>

 


Troubleshooting

I installed a development core as required, but pressing keys SHIFT and £ (pound) has no effect. The power LED does not start blinking.

Please check whether the core is up-to-date and 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.

Using a WIFI bridge might cause connection problems. If you try to connect to the MEGA65 over a network there might be several reasons (firewall, settings, etc.) etherload can’t find the MEGA65.
To locate the problem connect the PC to the MEGA65 using a LAN cable and see if it’s working that way.

Another reason why the power LED is not blinking by pressing the keys SHIFT and £ (pound) may be you forgot to set DIP switch #2 to ON or you may have set another switch than 2 to ON. Be aware the DIP switch is up-side-down.

(macOS specific) The power LED is blinking green/yellow, and both MEGA65 and Mac are in the same Ethernet network, but still the tools claim they can’t detect the MEGA65.

This can happen if you placed etherload or mega65_ftp in your Downloads or Documents folder (or in a sub-folder of those). There are additional security measures in place for those folders that will prevent etherload or mega65_ftp from receiving the network packets sent by the MEGA65. Please copy the binaries to another location and start them from there.

 

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.

Triggering etherload or mega65_ftp takes longer than expected (>1 sec). How can I speed this up?

The ETHLOAD.M65 program needs to be found on the SD card when any of those programs is started. If a lot of files already existed in the root folder before ETHLOAD.M65 was copied there, it could be the system needs a long time to find it. If you want to speed this up, you may want to prepare a fresh new SD card with MEGA65 fdisk, and make sure the ETHLOAD.M65 file is copied to it during that process. That way, the start of etherload and mega65_ftp will be much faster. You can still copy a lot of other files after that to the SD card and still keep the fast startup of etherload/mega65_ftp, as ETHLOAD.M65 will still be one of the earliest entries in the FAT32 structure of the root folder.