Basic Operation
When operating the cartridge without a case, please avoid touching exposed pads and pins to prevent ESD damage.
- It is not recommended to insert the cartridge with the JTAG adapter and cable installed. It is easy to hit the ceiling of the cartridge port, causing stress on the JTAG pins.
- When inserting the cartridge, carefully align the gold fingers to the contact elements in the cartridge port connector for an optimal connection. When using a case the alignment will happen automatically due to the fit of the plastic parts.
- Make sure the cartridge is firmly seated before turning on the power.
When pushing the button, replacing the microSD card, or otherwise touching the cartridge while operating, be careful not to push the PCB upwards or downwards, as this can glitch the connection of the cartridge causing temporary operational failure. When pressing down on pushbutton with the thumb, use the index finger to support the PCB from below.
- Before removing the cartridge, remove any microSD card from the card reader.
- Grasp the PCB with the thumb and forefinger from opposite sides at the widest part (next to the USB connector and micro SD card reader respectively), and gently pull outwards while rocking the PCB slightly to the left and right. Do not use the pushbutton or any other component as a grip.
The cartridge can be powered from the cartridge port (when the C64/C128 is turned on), from the USB port, or both at the same time. In order to turn the cartridge off, both power sources must be disabled (C64/C128 turned off if the cartridge is inserted, and USB cable disconnected). While the cartridge is powered, it will retain internal state even if the C64/C128 is turned off. Do not insert or remove the cartridge from the cartridge port while it is powered via USB.
The cartridge may be shipped with a protective plastic clip installed over the JTAG connector. This clip must be removed before using the JTAG, but also before installing a clock port expansion which covers the JTAG connector, such as the RR-Net.
The JTAG interface can be used to reprogram the flash in the event of bricked bootloader. It can also be used as a debugging tool. A suitable config file for OpenOCD can be found here. Note that the JTAG controller used must also be configured.
If connecting the JTAG to an FTDI based JTAG controller, the tool ecpprog can also be used to program the flash.
The bootloader is used to reprogram the on-board flash over the USB port using the standard DFU protocol. The bootloader itself can not be written using this mechanism, removing the risk of bricking the cartridge on incorrect use.
In order to enter the bootloader, the push-button must be held down while the cartridge is powered up. This means that the cartridge must first be unpowered (USB cable not connected, while either not being plugged in to a C64/C128 or the computer turned off). Then, the push-button is pressed down, and with the button still in this position power is applied to the cartridge (by turning on the C64/C128 or inserting the USB cable). This should cause the RGB LED to start cycling between different colours. The button can now be released. The cartridge will remain in bootloader mode until powered off again, or a reset command is sent using the dfu-util tool.
bootloader_led.mp4
While in bootloader mode, the main bitstream can be replaced using the dfu-util tool. To write a new bitstream, use the command
dfu-util -a 0 -D bitstream.bit
where bitstream.bit is the filename of your bitstream file. The flag -R can optionally be added to exit the bootloader and start the newly uploaded bitstream immediately after flashing.
The dfu-util process must have permission to directly access the DFU USB device. This can be arranged either by setting up appopriate udev rules, or by running dfu-util under su or sudo. An udev rules file could look for example like this:
ACTION=="add", SUBSYSTEM=="usb", ATTR{idVendor}=="1209",ATTR{idProduct}=="5a0c",MODE="0666",GROUP="plugdev"
(assuming the user running dfu-util is a member of the plugdev group).
The flash space occupied by the bootloader and the main bitstream is only a fraction of the available space in the flash chip. The remaining space can be used by the main bitstream for whatever purposes it wants (it needs to access this area itself, the boot process will not touch it). In case the bitstream requires some data to be pre-loaded into this area, it can be done using the bootloader by replacing the -a 0 flag to dfu-util with -a 1:
dfu-util -a 1 -D userdata.bin
where userdata.bin is the binary data to program into this area. As before, a -R flag may be added to immediately start the main bitstream after flashing.