Self-made Hardware Bringup¶
This guide is intended to help you bring up a LUNA board you’ve built yourself. If you’ve received your board from Great Scott Gadgets, it should already be set up, and you shouldn’t need to follow these steps.
- A LUNA board with a populated Debug Controller microprocessor. This is the SAMD microcontroller located in the Debug section at the bottom of the board.
- A programmer capable of uploading firmware via SWD. Examples include the Black Magic Probe; the Segger J-Link, and many OpenOCD compatible boards.
- A toolchain capable of building binaries for Cortex-M0 processors,
such as the GNU Arm
toolchain. If you’re using Linux or macOS, you’ll likely want to
fetch this using a package manager; a suitable toolchain may be
called something like
- A DFU programming utility, such as dfu-util.
The high-level process for bringing up your board is as follows:
- Compile and upload the Saturn-V bootloader, which allows Debug Controller to program itself.
- Compile and upload the Apollo Debug Controller firmware, which allows FPGA configuration & flashing; and provides debug interfaces for working with the FPGA.
- Install the
lunatools, and run through the self-test procedures to validate that your board is working.
The “recovery mode (RVM)” bootloader for LUNA boards is named Saturn-V; as it’s the first stage in “getting to LUNA”. The bootloader is located in [in its own repository](https://github.com/greatscottgadgets/saturn-v).
You can clone the bootloader using git:
$ git clone https://github.com/greatscottgadgets/saturn-v
Build the DFU bootloader by invoking
make. An example invocation
for modern LUNA hardware might look like:
$ cd saturn-v $ make
If you’re building a board that predates r0.3 hardware, you’ll need to specify the board you’re building for:
$ cd saturn-v $ make BOARD=luna_d21
The build should yield two useful build products:
bootloader.bin; your SWD programmer will likely consume one of these
Next, connect your SWD programmer to the header labeled
upload bootloader image. If you’re using the Black Magic Probe, this
might look like:
$ arm-none-eabi-gdb -nx --batch \ -ex 'target extended-remote /dev/ttyACM0' \ -ex 'monitor swdp_scan' \ -ex 'attach 1' \ -ex 'load' \ -ex 'kill' \ bootloader.elf
If your programmer works best with
.bin files, be sure to upload the
bootloader.bin to the start of flash (address
Once the bootloader is installed, you should see LED
rapidly. This is the indication that your board is in Recovery Mode
(RVM), and can be programmed via DFU.
You can verify that the board is DFU-programmable by running
$ dfu-util --list
If your device shows up as a LUNA board, congratulations! You’re ready to move on to the next step.
Optional: Bootloader Locking¶
Optionally, you can reversibly lock the bootloader region of the Debug Controller, preventing you from accidentally overwriting the bootloader. This is most useful for users developing code for the Debug Controller.
If you choose to lock the bootloader, you should lock the first
of flash. Note that currently, the bootloader lock feature of Black
Magic Probe devices always locks
8KiB of flash; and thus cannot be
used for LUNA.
The next bringup step is to upload the Apollo Debug Controller firmware, which will provide an easy way to interface with the board’s FPGA and any gateware running on it. The Apollo source is located [in its own repository](https://github.com/greatscottgadgets/apollo).
You can clone the bootloader using git:
$ git clone https://github.com/greatscottgadgets/apollo
You can build and run the firmware in one step by invoking
order to ensure your firmware matches the hardware it’s running on,
you’ll need to provide the hardware revision using the
BOARD_REVISION_MINOR make variables.
The board’s hardware revision is printed on its silkscreen in a
r(MAJOR).(MINOR) format. Board
r0.2 would have a
BOARD_REVISION_MAJOR=0 and a
BOARD_REVISION_MINOR=2. If your
board’s revision ends in a
+, do not include it in the revision
An example invocation for a
r0.2 board might be:
$ make BOARD_REVISION_MAJOR=0 BOARD_REVISION_MINOR=2 dfu
Once programming is complete, only LED
E should be blinking;
indicating that the Apollo firmware is idle.
The final step of bringup is to validate the functionality of your hardware. This is most easily accomplished by running LUNA’s interactive self-test applet.
Before you can run the applet, you’ll need to have a working
development environment. See [[Setting up the development environment]]
to get your environment set up.
Next, we can check to make sure your LUNA board is recognized by the
LUNA toolchain. Running the
apollo info command will list any
$ apollo info Detected a LUNA device! Hardware: LUNA r0.2 Serial number: <snip>
Once you’ve validated connectivity, you’re ready to try running the
interactive-test applet. From the root of the repository:
$ python3 applets/interactive-test.py
Issue: some of the build files weren’t found;
make produces a message like “
no rule to make target “.
Chances are, your clone of LUNA is was pulled down without its
submodules. You can pull down the relevant submodules using
$ git submodule update --init --recursive
Issue: the ``apollo info`` command doesn’t see a connected board.
On Linux, this can be caused by a permissions issue. Check first for the
presence of your device using
lsusb; if you see a device with the
1d50:615c, your board is present – and you likely have a
permissions issue. You’ll likely need to install permission-granting