5 steps to setup and use a debugger with the Photon

I recently got my Programmer Shield and I had trouble finding instructions on how to use it as an actual debugger.

I wrote a step-by-step article on how to install the software, start the debugger and get to the bottom of an issue like a crash (SOS / red led flashing).

5 steps to setup and use a debugger with the Particle Photon

I added separate steps for Windows in this next post

Debugging Particle on Windows

Let me know if you have comments or if something doesn’t work on Mac OSX and Windows.


I’ve been pondering the ability to build a single .elf that is a simple reflection of the 3 parts that are built by default.

I know there’s a non-modular/monolithic build option, but my fear is that there will be a class of bugs that appear only in the modular build.

I’m thinking of some extra step where the 3 elf files are smashed together into a single version that is suitable for gdb, so you can follow the code flow wherever it leads without switching. Perhaps some arm-none-eabi-objcopy magic may be enough.

That and a program-ocd target in the makefiles might improve the debug workflow - I’m getting tired of manually having to invoke dfu mode as part of the modify-build-test-debug cycle.


Nice guide :smiley:

1 Like

This is excellent @jvanier thanks for putting this out there! BTW there are OSX instructions on the Programmer Shield repo: https://github.com/spark/shields/tree/master/photon-shields/programmer-shield

One blog auto formatting issue I found was ./configure --enable-ftdi was changed to ./configure - enable-ftdi on your blog.

1 Like

I'll include a link and mention the driver editing business on OSX.

Having a make target for a GDB script would be nice. Here's what I'm doing right now.

Load all symbols in the same GDB session:

  • Extract the address of each module .text section
  • Load each ELF into GDB with add-symbol-file, passing the address above (for some reason GDB doesn't use the address in the ELF file as a default and forces you to find that address on your own)

Here's my script to load GDB with this configuration.

Set breakpoints

When setting breakpoints, multiple symbols will often match because of the dynalib structure. Set a breakpoint as normal then disable the ones you don't want.

For example, break setup

(gdb) break setup
Breakpoint 1 at 0x806ed2c: setup. (3 locations)

Find out the one you need with info break

(gdb) info break
Num     Type           Disp Enb Address    What
1       breakpoint     keep y   <MULTIPLE> 
1.1                         y     0x0806ed2c in system_part2_init at src/module_system_part2.c:96
1.2                         y     0x0806ed2d <setup+4294967295>
1.3                         y     0x080a02f0 in setup() at src/application.cpp:40

Disable all except the one in application.cpp

(gdb) disable 1.1 1.2


(gdb) continue
Program received signal SIGINT, Interrupt.
setup () at src/application.cpp:40
40	{
(gdb) list
38	/* This function is called once at start up ----------------------------------*/
39	void setup()
40	{
41	    //Setup the Tinker application here
42	    //Register all the Tinker functions
43	    Particle.function("digitalread", tinkerDigitalRead);
44	    Particle.function("digitalwrite", tinkerDigitalWrite);

@jvanier, fantastic topic! Being on windows and compiling locally has required a mix of selecting the right tools (minGW, plain it seems) and having a correctly configured PATH. The instructions for building openOCD on Windows are less than ideal (ie. near useless IMO). If you or anyone else has built openOCD on windows and can share their steps, it would be great.

1 Like

hi BDub:
I can’t find the file from this path on my mac.

Is there any other way I can fix it?

You won’t see it in Finder until you right-click and select Show Package Contents

If you use Terminal you can just cd Contents

1 Like

yes, I did. I have reached the last level of the path and the AppleUSBFTDI.kext isn’t there. I wonder if I kill the file accidently or other reason.

I don’t remember having to install this, but maybe you can get your drivers back by installing FTDI drivers for Mac? https://learn.sparkfun.com/tutorials/how-to-install-ftdi-drivers/mac

EDIT: Actually if you don’t have those drivers you might be better off because those are the Apple USB FTDI drivers that you want to unload anyway so they don’t conflict with the FTDI driver. Have you tried connecting your Programmer Shield yet?

1 Like

IC, I am currently connecting my Mac to debugger shield with photon attaching it. Let me try it again.

I have some issues that I don’t know how to solve. What does “Error: Target not examined yet” mean? (I plug in the usb core to the shield and type in
openocd -f interface/ftdi/particle-ftdi.cfg -f target/stm32f2x.cfg -c “program bootloader.elf verify reset exit”)

I have followed this guide on my Ubuntu system. The firmware loads, openocd runs and connects to the board, gdb works and seems to display correctly. The issue I am having is that I can reset the target, set the first breakpoint to setup() as shown in the guide and then issue the continue command but the program (Tinker) never stops at the breakpoint. If I halt the program do some single stepping it seems to be down in the src/system_setup.cpp, WiFiSetupConsole::loop() at line 205 super::loop()

The blue LED blinks when the device is running.

What do I need to do to start stepping through the user ap so I can learn how this works for debugging?

Make sure you are recompiling and flashing the system firmware and your application as one big executable instead of 3 modules (system 1, system 2, user app). Otherwise GDB tends to get confused with the symbol addresses.

make clean all program-dfu PARTICLE_DEVELOP=1 PLATFORM=photon USE_SWD_JTAG=y MODULAR=n APPDIR=~/Programming/MyApp

Thank you for your response. I found the problem a few nights ago but had not gotten around to posting it. The issue was that the device needed to be able to connect to my access point. Once I enabled that it worked just fine.

Actually I am trying to get the whole thing working in eclipse with the openocd plugin. I am getting close but not quite there yet. When I have it all configured right I will post the whole process of setting it up. If someone else has already done it then that would be great to know. Where I am right now is I am missing something in the configuration and getting some build errors in eclipse, these cropped up just recently as I was able to cleanly build the Photon prior to my last changes. The issue I was having at that point was that the first breakpoint was getting set incorrectly. I think I fixed that but broke something else and now it won’t build properly (no code changes, just the simple tinker ap).

Eureka! Tonight I was able to get the programmer shield & photon working with Eclipse, this will make development so much better now that code, compile, build, make and I can do full symbolic debugging, breakpoints and single stepping all within the Eclipse IDE. I am cleaning up my notes and will post how it’s done if anyone is interested.


Great to hear! I’m interested for sure. Now that I’m a Particle employee I’d like to make an official debugger guide so any notes you have will help.

1 Like

congrats! since when?

Great - let me clean up the documentation and I will post it on Google docs and post the link.
Congrats on the new job - hope you have a great ride. BTW, I have 40 years in the business and I am very impressed with the quality of the hardware - the manufacturing and fab board are excellent.