# Proper Debugging of ATSAMD21 Processors ## Overview ![](https://cdn-learn.adafruit.com/assets/assets/000/030/766/medium800/arduino_debugging.png?1456441379) Chances are if you're programming firmware on a microcontroller you've had to do some 'fun' debugging. Button presses, interrupts, small memory spaces...it can make debugging quite a challenge! A lot of beginners lean on tried-and-true (if a little frustrating) printf statments or toggling GPIO's with LEDs on them. And don't get me wrong, those techniques work pretty well. But if you come from a software background you're probably used to really nice debugging setups, often built into the IDE Of course its a ton easier to debug software when the computer is running both software and development platform. It's a lot tougher when the processor is physically separated, with its own memory, clocks, peripherals, and its not even of the same _processor family!_ No worries though, there's a full industry set up to create programming/debug dongles and adapters! [One of our favorites is SEGGER's J-Link family](https://www.adafruit.com/?q=segger). They're not _cheap_ but they do support a vast number of chips. ![](https://cdn-learn.adafruit.com/assets/assets/000/030/764/medium800/arduino_2209-00.jpg?1456441177) Atmel also has it's own debugger chip, the [EDBG](http://www.atmel.com/webdoc/protocoldocs/ch01s01.html) (apparently its a AT32UC3A4256 programmed with Atmels proprietary firmware) This chip comes on every Arduino Zero and is used to both program and debug firmware ![](https://cdn-learn.adafruit.com/assets/assets/000/030/765/medium800/arduino_2843-04.jpg?1456441242) You may be wondering "OK so how do I actually do said debugging?" Well you've come to the right place because we're gonna show you how. In this guide we'll show how to debug the ATSAMD21 family (specifically the ATSAMD21G18) which is in the [Arduino Zero](https://www.adafruit.com/products/2843) and [Feather M0](https://www.adafruit.com/?q=feather%20m0&) family, by using the EDBG or J-Link. # Proper Debugging of ATSAMD21 Processors ## Install Software Before you begin you will need some software. Here's what we're using: ![](https://cdn-learn.adafruit.com/assets/assets/000/030/769/medium800/logo-arduino.png?1456441775) # Arduino IDE As of this writing, [1.6.7 is the latest](https://www.arduino.cc/) so we're using that. We also installed the [Arduino SAMD support](https://www.arduino.cc/en/Guide/Cores) and/or [Adafruit SAMD support (for Feather M0)](../../../../adafruit-feather-m0-basic-proto/setup) Make sure you also have drivers set up for the board you're using, and get a sketch working and uploaded to the board. That means you have the IDE and package set up, which is something you want done **before** you continue ![](https://cdn-learn.adafruit.com/assets/assets/000/030/767/medium800/arduino_segger.jpg?1456441711) # J-Link Software If you're using a J-Link, [install all software and drivers for it](https://www.segger.com/jlink-debug-probes.html) and run the J-Link commander to make sure you update the firmware, new firmware is constantly being released so best to update your 'Link! ![](https://cdn-learn.adafruit.com/assets/assets/000/030/771/medium800/arduino_Studio7__HomePage_980x352.jpg?1456441874) # Atmel Studio 7 Here's where the Mac and Linux people will be sad. This is the IDE software that can do step&memory debugging and its only for Windows. [Also you have to make an account on Atmel's site, download it from here](http://www.atmel.com/tools/atmelstudio.aspx) ![](https://cdn-learn.adafruit.com/assets/assets/000/030/770/medium800/arduino_5download.png?1456441833) Make sure you have the latest version, we used **build 790** # Proper Debugging of ATSAMD21 Processors ## Let's go! Danger: OK now that we have all that software, the rest isn't too tough! # Load an Arduino Sketch in Atmel Studio 7 Start by launching Atmel Studio 7 ![](https://cdn-learn.adafruit.com/assets/assets/000/030/772/medium800/arduino_1atmelstudio7.png?1456441975) Create a new Project ![](https://cdn-learn.adafruit.com/assets/assets/000/030/773/medium800/arduino_2newp.png?1456442003) And select **Create project from Arduino sketch** ![](https://cdn-learn.adafruit.com/assets/assets/000/030/774/medium800/arduino_3ard.png?1456442028) Navigate to your arduino sketchfolder and select the sketch. I recommend starting with the easy-to-understand **Blink** ![](https://cdn-learn.adafruit.com/assets/assets/000/030/775/medium800/arduino_4blink.png?1456442069) Also select the Arduino IDE location if necessary. For **Board** go with **Arduino/Genuino Zero (Programming Port)** and under Device, **ATSAMD21G18A** ![](https://cdn-learn.adafruit.com/assets/assets/000/030/777/medium800/arduino_6genuinozero.png?1456442143) You'll see the following, where the sketch is in a window, you can edit the code here if you like. For now just leave it as is. ![](https://cdn-learn.adafruit.com/assets/assets/000/030/778/medium800/arduino_7loaded.png?1456442204) # Set Up and Check Interface OK next up we'll attach the chip & debugger. You have two options: ## **Arduino Zero Debug port** This is super easy, just connect a USB micro B cable to your Arduino Zero ![](https://cdn-learn.adafruit.com/assets/assets/000/030/779/medium800/arduino_2843-04.jpg?1456442492) Warning: ## J-Link to SWD If you have a board without an EDBG chip on it, you can still debug, but you'll need a helper such as a J-Link. [We like using this handy adapter board](https://www.adafruit.com/products/2094) ![](https://cdn-learn.adafruit.com/assets/assets/000/030/780/medium800/arduino_2094-03.jpg?1456442602) To get the large J-Link cable do [the 'classic' 2x5 SWD cable connector](https://www.adafruit.com/products/1675) ![](https://cdn-learn.adafruit.com/assets/assets/000/030/781/medium800/arduino_2094-01.jpg?1456442632) If you are debugging a board that doesn't even have an SWD connector on it, you may need to solder to the SWD pads ![](https://cdn-learn.adafruit.com/assets/assets/000/030/782/medium800/arduino_adafruit_products_swd.jpg?1456442748) You need to connect the following to the J-Link: - **Vref / Vtarget** - Logic voltage of the chip, in this case 3.3V - **GND** to common ground - **SWDIO** to **SWDIO** - **SWCLK** to **SWCLK** I haven't found I need to connect the chip's RESET line # Identify Interface OK now you have your debugger plugged in, its good to check that it works, select **Device Programming** ![](https://cdn-learn.adafruit.com/assets/assets/000/030/783/medium800/arduino_8devprog.png?1456442893) Under **Tool** make sure you can select **EDBG** or **J-Link** ![](https://cdn-learn.adafruit.com/assets/assets/000/030/784/medium800/arduino_9edbg.png?1456442929) ![](https://cdn-learn.adafruit.com/assets/assets/000/030/785/medium800/arduino_jlinkdev.png?1456442979) Select **ATSAMD21G18A** as the device, **SWD** as the interface and hit **Apply** You can then **Read** the Device Signature. Make sure this all works before you continue! If you are asked to update the J-Link or EDBG firmware, its OK to do so now. ![](https://cdn-learn.adafruit.com/assets/assets/000/030/786/medium800/arduino_11done.png?1456443069) # Build & Start Debugging OK close out the modal programming window, we dont need it for now. **Build** the program ![](https://cdn-learn.adafruit.com/assets/assets/000/030/787/medium800/arduino_13build.png?1456443202) Add a **Break** by clicking on the first **DigitalWrite** function call, you'll see a red dot ![](https://cdn-learn.adafruit.com/assets/assets/000/030/788/medium800/arduino_addbreak.png?1456443232) Now run **Start Debugging and Break** ![](https://cdn-learn.adafruit.com/assets/assets/000/030/789/medium800/arduino_startdebug.png?1456443289) Danger: You'll get prompted to select a debugging tool ![](https://cdn-learn.adafruit.com/assets/assets/000/030/790/medium800/arduino_selecttool.png?1456443337) Go thru what you did before, selecting the programmer and processor ![](https://cdn-learn.adafruit.com/assets/assets/000/030/791/medium800/arduino_selectedbg.png?1456443359) Once done go back and re-run **Start Debugging** You'll end up in a strange code, labeled **int main(void) {** this is the main entry point to the sketch. Normally this part is never seen, it's what sets up the Arduino before you get to the **setup** section of the sketch! ![](https://cdn-learn.adafruit.com/assets/assets/000/030/792/medium800/arduino_entry.png?1456443391) Select **Continue** to skip ahead to your stopping point ![](https://cdn-learn.adafruit.com/assets/assets/000/030/793/medium800/arduino_continue.png?1456443469) Now you'll end up at that **DigitalWrite** with the red dot. Note that you stop right _before_ this gets run. Now select **Step Over** to execute that line. Since you're in step-debugging mode you'll have to **Step** each function call you want to run. If you just want to continue running the code without any delays or steps, click on **Continue** like you did before ![](https://cdn-learn.adafruit.com/assets/assets/000/030/794/medium800/arduino_stepover.png?1456443515) You can also dig deeper into a function with **Step Into** ![](https://cdn-learn.adafruit.com/assets/assets/000/030/795/medium800/arduino_stepinto.png?1456443593) This will let you go _into_ the function call, to see what goes on inside. You can then continue to step over, step in or step out (complete the function) ![](https://cdn-learn.adafruit.com/assets/assets/000/030/796/medium800/arduino_steppedin.png?1456443635) You can also see variable names below, and the entirety of memory. Since this is just a basic tutorial we wont go into the vast depths of debugging, stack traces, and memory twiddling! [There's a ton more details on the Atmel Studio documentation page](http://www.atmel.com/webdoc/atmelstudio/atmelstudio.Debug.html) # Fixing other errors Thanks to **dgube1** in the forums for running into and finding a fix for this one. [Read the post here for more details.](https://forums.adafruit.com/viewtopic.php?f=24&t=147453) If you are getting a bunch of errors when you try to build the solution, you may need to remove the "math\_helper" source files from the project. In the Solution Explorer (see below): - Remove **math\_helper.h** from **ArduinoCore/include/core** - Remove **math\_helper.c** from **ArduinoCore/src/core** And hopefully that will help. ![](https://cdn-learn.adafruit.com/assets/assets/000/072/381/medium800/arduino_compatibles_remove_math_helper_header.jpg?1551896254) # Proper Debugging of ATSAMD21 Processors ## Paths and Optimizations C and C++ compilers make your code better when they compile it! This is great, but when we are trying to debug our code we don't want anything to change it. If you try to use the debugger and you see that it doesn't move from one line to the next as you would expect, this is because you have compiler optimizations turned on. to turn them off, right click on the  **ArduinoCore** project in the  **Solution Explorer**  pane, and click  **properties**. ![](https://cdn-learn.adafruit.com/assets/assets/000/042/415/medium800/arduino_Screenshot_%283%29_LI.jpg?1496934788) Then under  **Toolchain** , go to the  **ARM/GNU C Compiler** heading and click  **Optimization**. Set  **Optimization Level** to **None (-O0)**. ![](https://cdn-learn.adafruit.com/assets/assets/000/042/416/medium800/arduino_Screenshot_%284%29_LI.jpg?1496934797) Then do the same thing under the  **ARM/GNU C++ Compiler** heading. ![](https://cdn-learn.adafruit.com/assets/assets/000/042/417/medium800/arduino_Screenshot_%285%29_LI.jpg?1496934808) Then save your project. Now, repeat the above steps to turn off compiler optimizations for the other project (whatever you have named your sketch) in the solution explorer. Danger: # Correcting Paths to Necessary Files Current versions of Arduino have changed the location of the CMSIS core files that are necessary to compile projects. We can fix these paths by going back to the  **Properties** pane (by right clicking on the project in  **Solution Explorer** and selecting  **Properties** as we did before) and under  **ARM/GNU C Compiler ** select  **Directories** and add the new path to the CMSIS core files to the Include Paths section. This can be done by clicking the green plus button, and then finding the folder by clicking the  **...** button in the window that pops up. Leave the  **Relative Path** box checked. The current location of the CMSIS core as of the writing of this guide is: **C:\Users\YourNameHere\AppData\Local\Arduino15\packages\arduino\tools\CMSIS-Atmel\1.1.0\CMSIS\Device\ATMEL** ![](https://cdn-learn.adafruit.com/assets/assets/000/042/418/medium800/arduino_Screenshot_%286%29_LI.jpg?1496935852) Then select the path you just added in the list and click the yellow up arrow icon to move it to the top of the list. ![](https://cdn-learn.adafruit.com/assets/assets/000/042/419/medium800/arduino_Screenshot_%287%29_LI.jpg?1496936001) Now repeat those same steps in the  **Directories ** pane under the  **ARM/GNU C++ Compiler ** section.  ![](https://cdn-learn.adafruit.com/assets/assets/000/042/420/medium800/arduino_Screenshot_%288%29_LI.jpg?1496936134) Do these steps for both projects in the  **Solution Explorer** pane. Danger: # Fixing Some Core Files If you try to debug your sketch now, it may warn of an "undefined referenced to `vtable for HardwareSerial'" To fix this, open the **includes/core/**** HardwareSerial.h **file under the ** ArduinoCore** project. Scroll down to the class definition around line 67 and replace the class declaration with the following code: ```auto class HardwareSerial : public Stream { public: HardwareSerial() {}; virtual ~HardwareSerial() {}; virtual void begin(unsigned long) {}; virtual void begin(unsigned long baudrate, uint16_t config) {}; virtual void end() {}; virtual int available(void) = 0; virtual int peek(void) = 0; virtual int read(void) = 0; virtual void flush(void) = 0; virtual size_t write(uint8_t) = 0; using Print::write; // pull in write(str) and write(buf, size) from Print virtual operator bool() = 0; }; ``` Your file should look like this: ![](https://cdn-learn.adafruit.com/assets/assets/000/042/421/medium800/arduino_Screenshot_%289%29_LI.jpg?1496936672) Once this is done, you should be able to compile and debug your sketch! # Proper Debugging of ATSAMD21 Processors ## Restoring Bootloader When you program in for debugging you are writing direct to the chip, this deletes the bootloader! You'll want to restore it if you ever want to go back to using the Arduino IDE. # Arduino Zero This is pretty easy. Launch the IDE, select **Arduino Zero (programming port)** from the **Tools-\>Board** menu, and **Atmel EDBG** as the **Tools-\>Programmer** Then select **Burn Bootloader** ![](https://cdn-learn.adafruit.com/assets/assets/000/030/797/medium800/arduino_bootloader.png?1456443877) It only takes a few seconds to burn in the bootloader: ![](https://cdn-learn.adafruit.com/assets/assets/000/030/798/medium800/arduino_burned.png?1456443927) # Feather M0 or Others For this, you'll need to use the Atmel Studio setup, since you're using a J-Link. Download the bootloader hex file [featherm0bootloader_160305.zip](https://learn.adafruit.com/system/assets/assets/000/031/337/original/featherm0bootloader_160305.zip?1458155274) Wire it up correctly and select **Device Programming** ![](https://cdn-learn.adafruit.com/assets/assets/000/030/801/medium800/arduino_8devprog.png?1456444036) Select **J-Link** and the **ATSMD21G18A** with **SWD**. Verify you can read the Device Signature ![](https://cdn-learn.adafruit.com/assets/assets/000/030/800/medium800/arduino_jlinkdev.png?1456443998) Unlock the Bootloader protection by going to **Fuses** and changing **BOOTPROT** to `0x07` then programming ![](https://cdn-learn.adafruit.com/assets/assets/000/052/636/medium800/arduino_compatibles_bootprot.png?1522254058) Next click on **Memories** in the left hand side ![](https://cdn-learn.adafruit.com/assets/assets/000/030/802/medium800/arduino_memories.png?1456444254) Next to the **Flash (256 KB)** section, click the triple-dots and select the bootloader file. Then click **Program** to program it in ![](https://cdn-learn.adafruit.com/assets/assets/000/030/803/medium800/arduino_bootprog.png?1456444315) ## Related Guides - [Adafruit Feather M0 Adalogger](https://learn.adafruit.com/adafruit-feather-m0-adalogger.md) - [Adafruit Feather M0 Bluefruit LE](https://learn.adafruit.com/adafruit-feather-m0-bluefruit-le.md) - [Adafruit MicroSD SPI or SDIO Card Breakout Board](https://learn.adafruit.com/adafruit-microsd-spi-sdio.md) - [Adafruit Metro M0 Express](https://learn.adafruit.com/adafruit-metro-m0-express.md) - [Wireless UNTZtrument Using BLE MIDI ](https://learn.adafruit.com/wireless-untztrument-using-ble-midi.md) - [Debugging the SAMD21 with GDB](https://learn.adafruit.com/debugging-the-samd21-with-gdb.md) - [Adafruit Metro M4 Express featuring ATSAMD51](https://learn.adafruit.com/adafruit-metro-m4-express-featuring-atsamd51.md) - [Daily Cheer Automaton](https://learn.adafruit.com/daily-cheer-automaton.md) - [Bootloading Basics](https://learn.adafruit.com/bootloader-basics.md) - [MUNNY Glowing Friend with Bluetooth Control!](https://learn.adafruit.com/munny-lamp.md) - [Guardian Shield+ Zelda Breath of the Wild](https://learn.adafruit.com/guardian-shield-zelda-breath-of-the-wild.md) - [Adafruit Metro M7 1011 with AirLift](https://learn.adafruit.com/adafruit-metro-m7-with-airlift.md) - [CRICKIT Flippy Robot](https://learn.adafruit.com/crickit-flippy-robot.md) - [Build a Bluetooth App using Swift 5](https://learn.adafruit.com/build-a-bluetooth-app-using-swift-5.md) - [Adafruit Metro M7 with microSD](https://learn.adafruit.com/adafruit-metro-m7-microsd.md) - [Introducing Adafruit Feather](https://learn.adafruit.com/adafruit-feather.md) - [Debug Header for the Feather [M0]](https://learn.adafruit.com/make-a-simple-debugging-featherwing-for-the-m0.md)