Troubleshooter for Debugging an Arduino Sketch in vMicro

This troubleshooter is for the Hardware Debugger Option in Visual Micro, and can be used to troubleshoot using the Hardware Programmer options in a similar way.

Click on the buttons after each question to work through the possible solutions, the page will advance to the next question/solution as needed.... (just press refresh to start again)

There is also an accompanying video on Youtube which runs through the common issues (also below).

Step

Step 1

Are you using the Hardware Debugger?

Yes No

Hardware Debugger Selection in Visual Micro

Step 2_1

How Far Does It Get?

Does debugging session begin fully (debug controls visible at the top of the session)?

Yes No

Step 2

Are you sure all connections made are correctly? (hints and tips appear in the output window as shown below

And do both devices show their power LEDs normally when connected to the each other and your PC?

Yes No / Unsure

(Tip: We have more information in our connection diagrams from the links on our debugger list here, just click the green check mark for the debugger and device you are using)

Debugger Hints Shown When a Debugger is Selected

Step 3

Do you see an Error Message popup (with red X) when running the Debug > Attach command?

Yes No

Debug Error when connections between debugger and target are incorrect

Is It That Exact Popup?

If it is this specific popup where:

the last paragraph matches the one shown below
and begins "Unable to start debugging, program path <<yourprogram>> is missing or invalid."

Re-Build and upload the program to your target to ensure both have the same code.
Then try attaching the debugger again.

Step 4

Enable the "vMicro > Upload > Verbose" option, to expose further logging, then try running the "Debug > Attach" command again.

Review the "Output Window > Debug" output.

Output Window > Debug Selection

Are there any unresolved properties visible in this window? (e.g. {build.openocdscript}) (shown in the light blue box above)

Looks OK Its Missing something

Review OpenOCD Log

Note: If you are using a GDBStub or the Black Magic Hardware probe, follow this section FIRST, you will obtain the log needed below from the command line.

There is an additional log file created in the Build Folder called "sketchName.ino_DebugOpenOCD.log" (see below on how to find this if unsure).

Review the logging information and click the button which applies:

I cannot see a Log File

"target voltage may be too low for reliable debugging"

"Info : VTarget = 0.000 V"

Cannot Find VID PID

LIBUSB_ERROR_ACCESS (or similar)

Its None of These Errors

Solutions

Software Debug

The Serial Debugger has its own pages here.

Never Lands on Breakpoint

Reset Target Board

If the debugger starts and connects, but you never land on your breakpoint..... stop the session, and reboot the target board using its reset button.

Try connecting the debugging session again, it should now work as expected...

That Didn't Work....

Connection Help

Further information and links to Wiring Diagrams is shown in the Output Window when a Debugger is selected. Its always worth checking the connections, and polarity of ribbon cables / connectors, as this will prevent any debugging working.

Tips:-

Cable Lengths: Try and keep cable lengths to a minimum, and use cables with solid connections

Power Note:You may still need to supply additional power to your target (via USB lead or power pins direct).

One sign things are wrong is when they both work until they are connected together, then you have a short somewhere in the connections (check VCC/GND specifically, or polarity of ribbon if using a ribbon cable)

Ribbon Cables:

When working with Ribbon cables make sure you pay attention to the polaity marking on one side, as these ribbons appear reversibl at a glance, but are not.

Example 20 Pin JTAG Ribbon cable with (D)ebugger and (T)arget marked

When working with board connections, they do not always have a housing for the tooth and notch to meet in, so check for a dot, or other markings as to which way around they should be.

Example 10 Pin SWD Ribbon cable with (D)ebugger and (T)arget marked

We have more information in our connection diagrams from the links on our debugger list here, just click the green check mark for the debugger and device you are using.

Cannot Find Log File

(If you cannot find the Build Folder, run a build, and inspect the "Output > Micro Build" Window. Find the "Build Folder" as shown below:

Locating the Build Folder in Visual Micro

Hold CTRL + Left Click on the link to open it in Windows Explorer, you should see the log file as shown below:

Finding the OpenOCD Log in Windows Explorer

Found It, Take Me Back... Still can"t find it

Check Driver Installations

Check the Output window when selecting the debugger, you may need to amend the Driver for some Debuggers (JLink, FT2232H, FT2232M etc..). Check our Documentation for more information.

This can be done using the Zadig Tool, and for Visual Micro we want to install the WinUSB Driver

Zadig Installation

If you do not need a driver, and the VID PID it is searching for does not appear to match your product, press the Help button below

Help

Conflicting USB Session

This ACCESS_ERROR means that there is already a connection to the debugger elsewhere on your machine.

Check that:-

no other Debug Session Started for the selected external debugger in Visual Micro
not using any other external tools (command line running OpenOCD/GDB, other software) to connect to the debugger
try stopping the debugging, unplug everything from your PC, and re-connect it. Then try debugging again..
stop debugging and check no orphaned "openocd.exe" processes are running in Task Manager.

I Want to Use more than one of the same model of Debugger (e.g. Jlink)

I keep having to unplug and reset everything

I keep having to kill orphaned OpenOCD / GDB Processes

Hanging on Debug Attach

If VS appears to hang at this point (a progress action like below that never finishes), try disconnecting the debugger and board from the PC, and restarting VS. Then reconnect the Debugger, then the board to the PC.

That Didn't Work....

GDB Command Line

If you are using the Black Magic Probe, or a GDBStub implementation (e.g. Uno/ESP8266), things differ slightly, follow the instructions below:- (This also applies if you wish to run all commands manually (to get a new configuration working)

Unplug the Debugger from your PC to ensure the process exposes the command lines
Try attaching the Debugger in Visual Micro again, the command line will be revealed in the "Output Window > Show Output From > Micro Build"
Re-Attach the Debugger to your PC so we can connect again
Take the MIDebuggerPath, and MIDebuggerArgs lines and copy them into Notepad
"MIDebuggerPath": "C:\\Users\\Simon\\AppData\\Local\\arduino15\\packages\\arduino\\tools\\arm-none-eabi-gcc\\7-2017q4/bin/arm-none-eabi-gdb.exe", "MIDebuggerArgs": "-nh -b 115200 -ex \"target extended-remote \\\\.\\COM62\" -ex \"monitor swdp_scan\" -ex \"attach 1\"",
Now Remove the "MiDebuggerPath": and "MiDebuggerArgs": from the text, and the trailing comma on each line, and the outer most double quotes on each line:
C:\\Users\\Simon\\AppData\\Local\\arduino15\\packages\\arduino\\tools\\arm-none-eabi-gcc\\7-2017q4/bin/arm-none-eabi-gdb.exe -nh -b 115200 -ex \"target extended-remote \\\\.\\COM62\" -ex \"monitor swdp_scan\" -ex \"attach 1\"
Now put it on a single line, and Replace \" with ", then \\ with \:
C:\Users\Simon\AppData\Local\arduino15\packages\arduino\tools\arm-none-eabi-gcc\7-2017q4/bin/arm-none-eabi-gdb.exe -nh -b 115200 -ex "target extended-remote \\.\COM62" -ex "monitor swdp_scan" -ex "attach 1"
Now paste this final command into a command prompt window, and press Enter - this should reveal more information about the problem

If this appears to be running as expected, you can press CTRL+C to break immediately, and type 'c' + ENTER to continue execution.

Does everything seem to work with the Command Line? (just not in Visual Studio)

Yes I see a problem in the Output No

VS to GDB Logging

So now we know it works manually, and not in VS, we need to capture some additional logging detail to help us diagnose further.

To Enable this additional Logging:-

Close all Command windows from previous steps
Go to your Visual Studio solution with the issue.
Open the VS Command Window (View > Other Windows > Command Window)
Type in the Command Debug.MIDebugLog /On /OutputWindow, and press Enter
Try and Attach the Debugger (or which ever action is causing issues)
You will have additional detail in the Output > Debug window
If you cannot see any clear problems, save this output to a file to log on the Forum.

If this hasn"t helped to identify your issue, click the button below...

Help

Get Additional Help

Please create a new log on the Forum GDB Board, and attach the output from the "Output > Debug" window which led you here.

Please also enable the vMicro > Compile > Show Build Properties & Verbose options and perform a build.

Both logs should be attached to the forum post in a ZIP, so we can help you as quickly as possible...

(a screenshot of your specific error, or place where it hangs may also be useful in some scenarios)