Building CircuitPython Firmware

First, you must be able to build the firmware on your local machine. If you have not already done this, the Building CircuitPython Learn Guide will get you up and running.

For any meaningful debugging results, you'll need to include DEBUG=1 in your make command. For example: make clean BOARD=itsybitsy_m0_express; make BOARD=itsybitsy_m0_express DEBUG=1

Non-Express boards may complain that the resulting compilation will not fit on the board; there are a couple workarounds, so contact one of the CircuitPython helpers on Discord or in the Adafruit CircuitPython forum.

Segger J-Link

You'll need a debugging adapater to allow the computer to communicate with the target board. I, and by extension this guide, use a Segger J-Link debugger and their J-Link software and drivers. I'm sure you could use almost any SWD compliant debugger, but that will not be covered in this guide.

The Segger J-Link Pro, Basic, EDU, and EDUmini are all compatible (choose your version according to Segger's license terms & budget). Additionally, you'll need to be able to connect your SAMD board to the J-Link. This is easiest using one (or both) of the following Adafruit breakouts and a 2x5 ribbon cable:

• JTAG (2x10 2.54mm) to SWD (2x5 1.27mm) Cable Adapter Board
  (For use with J-Link Pro/Basic/EDU with the 2x10 connector)
• SWD (2x5 1.27mm) Cable Breakout Board
  (For use with any 2x5 connection and a breadboard)
• 10-pin 2x5 Socket-Socket 1.27mm IDC (SWD) Cable - 150mm long
  (None of the debuggers come with a 2x5 cable)

Refer to your target board's pinout to locate the SWDIO & SWCLK pins.

Atmel Studio 7

Lastly, you'll need Atmel Studio 7 ("AS7"). As luck would have it, Microchip provides it for FREE (at time of writing). Download is available from Microchip's website.

Understand this before moving forward: Atmel Studio can be buggy. You may experience "Not Responding" occurrences and crashes. Nothing new for us Windows users, right? Having said that, I haven't had any experiences of lost or corrupted data. While rarely needed, each board I have debugged has always been recoverable by re-programming when things got screwy. We'll cover that in the guide, as well.

Which brings me to one more thing I will suggest you have before starting: a local copy of the bootloader binary (*.bin) for the board you are debugging. They can be found in the uf2-samd GitHub release page.

If you've made it this far, you're ready for the joys of debugging! So, lets open Atmel Studio and get ready to debug.