ChameleonUltra

Development

In this file you can look up how to install requirements, edit, compile and debug the firmware!

Prerequisites for compiling

install a cross-compiler

So far, the following compilers have been reported to work fine.
Download one of them and decompress it.
Remember the path where you installed it.

Always use the official versions from ARM, DO NOT install gcc-arm-none-eabi from Debian/Ubuntu.
For some unknown reasons, same gcc version from Debian creates a bootloader too large to fit in the allocated flash space.
Moreover it does not contain the gdb debugger.

install make

install nRF tools

install programmer tools

Depending on the hardware programmer you want to use, additional tools are needed.

configure the project

Editing the code

You can use Visual Studio Code to edit this project! Simply download and install it!

Compiling the code

The script produces several images in objects.

Uploading the code in DFU mode

If the bootloader and the SoftDevice are already properly installed on the Chameleon, you can reflash it directly over DFU.

To set the device in DFU mode:

The LEDs 4 & 5 should blink green when in DFU mode.

To flash only the application (safer):

nrfutil device program --firmware objects/dfu-app.zip --traits nordicDfu

To flash everything (be sure to also have a JLink or ST-Link V2 programmer if something goes wrong):

nrfutil device program --firmware objects/dfu-full.zip --traits nordicDfu

Under Linux you can use the scripts flash-dfu-app.sh and flash-dfu-full.sh, they will put the device in DFU mode and flash it.

Uploading the code with a programmer

Connect pins GND, SWC (swclk) and SWD (swdio) to your programmer.

With a JLink and nrfjprog

# application only:
nrfjprog -f nrf52 --program objects/application.hex --sectorerase --verify --reset
# full:
nrfjprog -f nrf52 --program objects/fullimage.hex --sectorerase --verify --reset

With a JLink and openocd

# application only:
openocd -f interface/jlink.cfg -f target/nrf52.cfg -c "program objects/application.hex verify reset ; shutdown"
# full:
openocd -f interface/jlink.cfg -f target/nrf52.cfg -c "program objects/fullimage.hex verify reset ; shutdown"

With a ST-Link V2 and openocd

# application only:
openocd -f interface/stlink.cfg -f target/nrf52.cfg -c "program objects/application.hex verify reset ; shutdown"
# full:
openocd -f interface/stlink.cfg -f target/nrf52.cfg -c "program objects/fullimage.hex verify reset ; shutdown"

Uploading the code over BLE

If you are adventurous it is possible to flash the device over BLE (DFU mode).

To put the device in DFU mode

Once in DFU mode, the device will announce itself over BLE as CU-xxxx where xxxx are the last 2 bytes of the Device Serial Number.

Then use the official nRF Device Firmware Update mobile application to flash one of the DFU images.

Debugging the code from VSCode

{
    "cwd": "${workspaceFolder}",
    "executable": "${workspaceRoot}/firmware/objects/bootloader.out",
    "name": "Debug with JLink",
    "request": "launch",
    "type": "cortex-debug",
    "runToEntryPoint": "main",
    "showDevDebugOutput": "none",
    "servertype": "jlink",
    "device": "nrf52",
    "interface": "swd",
    "svdFile": "${workspaceRoot}/firmware/nrf52_sdk/modules/nrfx/mdk/nrf52.svd",
}, 
{
    "cwd": "${workspaceFolder}",
    "executable": "${workspaceRoot}/firmware/objects/bootloader.out",
    "name": "Debug with STLink",
    "request": "launch",
    "type": "cortex-debug",
    "runToEntryPoint": "main",
    "showDevDebugOutput": "none",
    "servertype": "openocd",
    "device": "nrf52",
    "svdFile": "${workspaceRoot}/firmware/nrf52_sdk/modules/nrfx/mdk/nrf52.svd",
    "gdbPath": "C:/Program Files (x86)/GNU Arm Embedded Toolchain/10 2021.10/bin/arm-none-eabi-gdb.exe",
    "configFiles": [
        "interface/stlink.cfg",
        "target/nrf52.cfg"
    ]
}

{
    "cortex-debug.armToolchainPath": "C:\\UserProgram\\arm_gcc\\none\\bin",
    "cortex-debug.JLinkGDBServerPath": "C:\\Program Files\\SEGGER\\JLink\\JLinkGDBServerCL.exe",
}

Debugging the code with gdb and openocd

See first if you can execute arm-none-eabi-gdb from the installed tools.

In case Python 3.8 is not available anymore on your distro, to install a local copy you can do

wget https://www.python.org/ftp/python/3.8.17/Python-3.8.17.tgz
tar zxvf Python-3.8.17.tgz
cd Python-3.8.17
./configure --prefix=$HOME/opt/python-3.8.17 --enable-shared
make
rm -rf ~/opt/python-3.8.17
make install

Connect openocd to the device with a JLink or a ST-Link V2

openocd -f interface/jlink.cfg -f target/nrf52.cfg

openocd -f interface/stlink.cfg -f target/nrf52.cfg

Then run gdb as follows

PYTHONHOME=~/opt/python-3.8.17/ arm-gnu-toolchain-12.2.rel1-x86_64-arm-none-eabi/bin/arm-none-eabi-gdb

and tell gdb to connect to openocd

target extended-remote localhost:3333

You can reflash a ST-Link V2 to use it as a BlackMagicProbe, to get support for RTT and see NRF_LOG messages. Some clones have only 64kb, this is too short. Even 128kb is too small when enabling RTT, but we can comment parts of the BMP source code.

git clone --recursive git@github.com:blackmagic-debug/stlink-tool.git
( cd stlink-tool && make )

Then put the stlink-tool binary in your path.

Get BMP full sources

Comment out all probes except Nordic nrf51 in src/target/cortexm.c big switch for probes. It should remain

    switch (t->designer_code) {
    case JEP106_MANUFACTURER_NORDIC:
        PROBE(nrf51_probe);
        break;
    }

make -j PROBE_HOST=stlink ST_BOOTLOADER=1 ENABLE_RTT=1

Then flash the ST_Link V2

stlink-tool src/blackmagic.bin

See src/platforms/stlink/README.md for more details. Unplug/plug.
Every time you plug the ST-Link, you have to run stlink-tool to enable BMP.
Under linux, it is convenient to install udev rules to get aliases /dev/ttyBmpGdb and /dev/ttyBmpTarg.

Note that using a native ST-Link V2 with BlackMagicProbe “hosted” will not allow to see NRF_LOG messages.

Debugging the code with gdb and BMP with RTT to monitor NRF_LOG

Assuming you have a BlackMagicProbe with RTT support made out of a ST-Link V2.

RTT usage: https://black-magic.org/usage/rtt.html

stlink-tool
sleep 1
screen /dev/ttyBmpTarg

In another terminal

$ arm-none-eabi-gdb
(gdb) target extended-remote /dev/ttyBmpGdb
(gdb) monitor swdp_scan
 1      Nordic nRF52 M4
 2      Nordic nRF52 Access Port.
(gdb) attach 1
(gdb) monitor rtt

We are now able to use gdb and see the NRF_LOG messages on the other terminal.

cf https://embeddedexplorer.com/nrf52-nrf-log-tutorial/

JLinkExe -if SWD -device nrf52 -speed 4000 -autoconnect 1

in a second terminal:

JLinkRTTClient

For Windows add these lines to the tasks.json:

        {
            "label": "logs",
            "type": "shell",
            "command": "C:\\WINDOWS\\System32\\cmd.exe",
            "args": ["/K", "C:\\Program Files\\SEGGER\\JLink\\JLinkRTTClient.exe"],
            "options": {
                "cwd": "C:\\Program Files\\SEGGER\\JLink"
            },
            "problemMatcher": []
        },
        {
            "label": "logger server",
            "type": "shell",
            "command": "C:\\WINDOWS\\System32\\cmd.exe",
            "args": ["/K", "C:\\Program Files\\SEGGER\\JLink\\JLink.Exe", "-if",  "SWD",  "-device",  "nrf52",  "-speed",  "4000", "-autoconnect", "1"],
            "options": {
                "cwd": "C:\\Program Files\\SEGGER\\JLink"
            },
            "problemMatcher": []
        },

Using SWO pin as UART to monitor NRF_LOG

One can set NRF_LOG_UART_ON_SWO_ENABLED := 1 in Makefile.defs to activate this functionality. When activated, NRF_LOG will be available if one connects a UART bridge to the SWO pin which will work as a UART TX pin. UART works at 115200 bauds. E.g. one can use a FTDI dongle and screen /dev/ttyUSB0 115200. Contrary to RTT that needs to be activated by a JTAG probe, UART logs are immediately available.

Limitations:

Resources

This site is open source. Improve this page.