Skip to content

Programming & Debugging

Jump to bottom
Flo edited this page May 4, 2026 · 4 revisions

⚡ Flashing the bootloader

A factory new SAMD21 IC ships without any firmware. For programming, it requires a compatible SWD programmer. The adafruit bootloader is used. From V1.0 a customized bootloader is used. For a .uf2 update file of the bootloader, see releases

Compatible programmers:

  • Segger J-Link (EDU)
  • DAPLink / CMSIS-DAP

⚠️ST-Link does not work with SAMD21

For flashing:

  • Connect SDWIO, SWDCLK, GND and apply battery voltage for flashing.
  • Flash the binary with the tool of your chice
  • The blue LED should start fading after flashing.
  • After flashing the bootloader once, the firmware and bootloader can be updated by drag&drop UF2 updates.

1.27mm Pinheader as kind of a pressfit the SWD socket. Make sure to connect GND to your computer if powering externally.

🔗 Using DAPLink / CMSIS-DAP

For just flashing the bootloader binary a cheap open-ocd compatible DAPLink / CMSIS-DAP programmer is the easiest choice.
Install open-ocd according to its documentation (+add to PATH)

Bootloader flashing using as programmer

Connect the PCB and run

openocd -f interface/cmsis-dap.cfg -f target/at91samdXX.cfg -c "program bootloader-breezedude-v3.16.0-19-atmel.bin verify reset exit 0x00000000"

within the bootloader directory.

output should look like this:

openocd -f interface/cmsis-dap.cfg -f target/at91samdXX.cfg -c "program bootloader-breezedude-v3.16.0-19-atmel.bin verify reset exit 0x00000000"
Open On-Chip Debugger 0.12.0 (2025-07-10) [https://github.com/sysprogs/openocd]
Licensed under GNU GPL v2
libusb1 d52e355daa09f17ce64819122cb067b8a2ee0d4b
For bug reports, read
        http://openocd.org/doc/doxygen/bugs.html
Warn : DEPRECATED: auto-selecting transport "swd". Use 'transport select swd' to suppress this message.
Info : Using CMSIS-DAPv2 interface with VID:PID=0x0d28:0x0204, serial=00000080003400454e00000e4e574c50a5a5a5a597969908
Info : CMSIS-DAP: SWD supported
Info : CMSIS-DAP: SWO-UART supported
Info : CMSIS-DAP: Atomic commands supported
Info : CMSIS-DAP: Test domain timer supported
Info : CMSIS-DAP: FW Version = 2.1.0
Info : CMSIS-DAP: Serial# = 00000080003400454e00000e4e574c50a5a5a5a597969908
Info : CMSIS-DAP: Interface Initialised (SWD)
Info : SWCLK/TCK = 1 SWDIO/TMS = 1 TDI = 0 TDO = 0 nTRST = 0 nRESET = 1
Info : CMSIS-DAP: Interface ready
Info : clock speed 400 kHz
Info : SWD DPIDR 0x0bc11477
Info : [at91samd.cpu] Cortex-M0+ r0p1 processor detected
Info : [at91samd.cpu] target has 4 breakpoints, 2 watchpoints
Info : [at91samd.cpu] Examination succeed
Info : [at91samd.cpu] starting gdb server on 3333
Info : Listening on port 3333 for gdb connections
[at91samd.cpu] halted due to debug-request, current mode: Thread
xPSR: 0x21000000 pc: 0x00000268 msp: 0x20002de0
** Programming Started **
Info : SAMD MCU: SAMD21G18A (256KB Flash, 32KB RAM)
** Programming Finished **
** Verify Started **
** Verified OK **
** Resetting Target **
shutdown command invoked

🐞 Debugging the Code

🐛 SWD

For Debugging CMSIS-DAP is currently not supported out of the box for SAMD21. ToDo: Custom script for using open-ocd

The following should work (see PIO docs)

🖥 USB

There is a Web based Serial Debug console using the USB connection Breezedude Web Analyze. With this you can check for basic functionality and forward the WS80/WS85 UART debug messages to check the sensor output.

⚠️ From V0.7.0 and newer sleep mode with USB is supported. With this the normal operation can be monitored with USB serial outputs. When USB is not connected during startup, USB is disable to save power.



💻 UART

For full-debugging connect a TTL (3.3V) UART to Serial adapter to the TX1 pad on the bottom of the PCB. Remember to have GND connected as reference.

⚠️ Software before 2025-09 need to be debugged on the TX pin of UART sensor port (black connector).
You can use an adapter cable or solder directly to the back of the PCB.

Use a serial Terminal of your choice, like putty or hterm to view the data. This debug mode works while normal operation if DEBUG=1 is enabled in the settings file. Make sure to disconnect USB for normal operation.

📺 I²C Display

⚠️ This feature is legacy and not included by default in V1.0 builds. For on-site testing a SSD1306 OLED display can be connected to the I2C connector (blue).

❗ The display needs to be connected on boot/reset and DEBUG=1 enabled.



Clone this wiki locally