Uploading, debugging, and RAM, flash operation explanation
Unfortunately there are currently problems with the OpenOCD configuration for DelugeProbe and there are known problems like hitting wrong positions, requiring multiple load retries and breakpoints being reported as exceptions. We hope those will get fixed so we leave the following guide as is:
In order to more conveniently upload code directly from your computer to the Deluge, and also perform live debugging with breakpoints etc, a special programmer device is required. There are a couple of options - DelugeProbe (affordable, DIY, and community-driven), and J-link (expensive but a less “DIY” option). These are detailed below.
Before we get on to the actual programmer devices though, here are some requirements which apply to both programmers. Perhaps the trickiest part of connecting a programmer to your Deluge PCB though is that you’ll need to solder a small pin header like this to your Deluge PCB.
Unfortunately, soldering this connector requires removing your Deluge PCB from the Deluge’s body entirely, which is quite tricky to do, and the soldering is small and fiddly - definitely not recommended for soldering beginners. There is a Markdown guide checked in to the DelugeFirmwareCommunity repository that can walk you through the process step-by-step. Or, Synthstrom or one of our repair partners could install it for you, for a fee.
In any case, a few steps are required in order to get a programmer working. It’s probably best to experiment with building and installing firmware via the SD card first, and only if it’s something you want to do a lot, then look at getting set up with one of the programmers.
Although JLink (see below) is the official debugger Renesas recommends, its cost can be well outside the reach of many would-be contributors to open-source efforts. For that reason, experienced software developer and Deluge enthusiast Aria Burrell (AKA: "litui" from our Discord), set out to find a more financially accessible tool for developers in the community to use in place of the JLink.
That customized tool and firmware is "DelugeProbe", available now for Raspberry Pi Pico, Raspberry Pi Pico W, Raspberry Pi Debug Probe, and Seeed XIAO RP2040, with support for other RP2040-based boards on the way. Instructions for modding the Deluge with debug pins, adding a debug port to the Deluge case, and building your own DelugeProbe are included in a file within the Deluge source. Other CMSIS-DAP based debuggers are also usable, though DelugeProbe contains speed and quality-of-life improvements over the original Picoprobe.
DelugeProbe source and binary images are available at https://github.com/litui/delugeprobe.
Prices start at around $3 USD for the Raspberry Pi Pico board itself with similar supported boards ranging up to around $20 USD. This makes it a far more affordable option than the J-link, even including the supplies, time, and effort to connect it.
The ideal option if cost were not an issue, is to buy a Segger J-link programmer.
There used to be an “EDU” (educational) model of the J-link which was licensed for educational purposes only and cost around $60 USD. This appears to be discontinued and unavailable at mainstream distributors, though a quick web search appears to show some places you can buy one. That model was beige in colour.
Or for a J-link without licence restrictions, prices start around $530 USD.
The cheapest option known to work is the J-Link EDU Mini, other cheap or mini variants are not tested and might not work
Check the J-link product comparison charts (copied below for your convenience) to see the features of the various models. They’ll all work (as per above), but only the more expensive models (starting at the PLUS, so not the EDU or BASE models) support “J-Flash”, which is a nice feature but not essential - see elaboration further down.
You will also need this adapter to connect the J-link to the Deluge PCB.
(Not required for DelugeProbe - just J-Link.)
Unlike many popular microcontrollers, the Renesas RZ/A1 MCU doesn’t contain any flash memory of its own. Instead, the Deluge firmware is stored on a separate flash memory IC - U5. When the Deluge boots up, its bootloader (itself also stored on the flash IC) commands the MCU to quickly load that firmware into its internal RAM, and then runs it from there. DelugeProbe and flash/RAM When using the DelugeProbe debugger, there is an option in the OpenOCD GDB Debugger settings allowing you to change whether you are intending to debug in RAM or from flash. RAM has been selected by default, but in our testing the speed difference seems negligible. DelugeProbe does not require any special utilities or more expensive models for permanent firmware installation. J-link and flash/RAM If you’re using a J-link to run and debug code, then the flash memory is bypassed entirely - the J-link puts the compiled code directly into the Deluge’s RAM, and then it’s run from there as normal. This means that after compiling and then running a firmware build via the J-link, that build will not remain installed on that Deluge after it is powered off.
Now, here’s where the more expensive J-link models (see above) have a slight advantage - they support a utility called J-Flash which allows you to write to the Deluge’s flash memory IC directly from your computer. This is a nice-to-have, but you’re unlikely to ever really use this - I (Rohan) only do for very particular testing and development cases - mostly when developing the Deluge’s bootloader, which is not open source at this stage. Otherwise it’s more convenient to just use an SD card when permanent firmware installation is required.
There’s a flag in definitions.h called ALPHA_OR_BETA_VERSION. Enabling this during development is highly recommended, as it enables various error-checks elsewhere in the codebase which are not included in release builds because they might hurt performance or seem unlikely to be a problem after alpha and beta testing.
To get some debugging text output from the Deluge, ideally you’ll be using a J-link, and can then use its RTT utility. To tell the firmware build to include this text generation and outputting, go to src/drivers/All_CPUs/uart_all_cpus/uart_all_cpus.h and set ENABLE_TEXT_OUTPUT to 1. The fact that this flag is in a file labelled “uart” will seem to make no sense because RTT output has nothing to do with UART. This is because before I realised RTT was a thing, this flag would instead send the debugging text out of the MIDI DIN port, and MIDI is UART.
When using the DelugeProbe, RTT on channel 0 is supported through USB Serial CDC. This is included in the build for DelugeProbe. You will need a terminal utility to connect to the COM port (or /dev/tty… or /dev/cu…) to observe the RTT data stream. This does not seem to work while OpenOCD is connected so make sure you’re not in debugger mode in e2 when using this.
If you’re not using a J-link or DelugeProbe and want to see the debugging text, go to the C++ compiler options, and set HAVE_RTT to 0 in Defined Symbols.
