news: june 2018 - Visual Micro is now a single version with all features enabled.
this is old documentation, still applies but has been superceeded wth better docs! please click Documentation at the top of this site to learn about visual micro. Thanks!
above image is just an example, the code does not do anything useful!
Usb (serial) or network (Bridge/Console) debugging for Arduino improves productivity by allowing us to monitor the running Arduino code, variables and expressions.
Conditional or timed breakpoints can be used to trace or pause the Arduino code. The values of variables can be modified with or without pausing the Arduino micro-controller.
The debugging tool automatically combines the debug facilities of Visual Studio, a world class IDE, with simple Arduino usb/serial commands without altering any of your Arduino source code (also supports Teensy 3, Yun, Uno (all Arduino), Due, Galileo Energia, StellarPad ).
Automatic debugging for novice users is enabled after first install. This ensures that the debugger always runs for the debug>start command and also adds an example breakpoint (if no breakpoint(s) has been created).
To switch the debugger to normal mode, as described in the documentation, untick "Tools>Visual Micro>Automatic Debugging"
More info & blurb
note: Click the image for more details. The message viewer in the image above was frozen at an informative position for the purposes of the example. Yes the code in the example is rubbish and doesn't do anything useful. It's just an example :)
The image above shows a running Arduino debug session in addition to the latest feature of allowing Arduino
variables to be changed during debug. The arduino code (bad example) shown is the entire arduino program source. There is no need for serial.print() debug statements in our code.
Notice that in the image all of the variables have different values to the defined source code. This is because the variables have been modified using the "watch expressions" window without causing the Arduino to stop or recompile. The image also shows the message trace which is one of the 3 available trace windows provided by the debugger. Read about
how to modify variables on an Arduino while it is running
The text messages assigned in breakpoints are not stored on the Arduino so they can be as long as is needed without concern of excessive Arduino memory usage. Whilst the debug version of an Arduino build will result in a large program size (depends on the program code) the huge savings of SRAM, caused by the removal of serial.print() debug messages from code, can immediately solve some erratic arduino program failures.
In the lower section of the image is the break point configuration list makes it possible to see how break point messages are constructed and that they can consist of a mix of text and/or expressions. Any valid Arduino variables and expressions can be used in breakpoints messages, watch expressions and/or conditions.
Variables and expressions in breakpoints are automatically made available in the expression watch window grouped by break point. Various views of the Arduino data are provided including bin, dec, hex in addition to summary values min/max. The Min/Max values are useful to the range of values encountered.
During an active debugger session, if the debugger is configured to share a serial port with the Arduino code, serial messages omiitted by code will continue be displayed correctly in the serial monitor(s).
Improves Productivity - Works over usb, xbee, bluetooth and more
Developing small and large Arduino projects often depends on scanning the web to find the ranges of values produced by various sensors such as giro, temperature, accellerometer etc. The debug tool provides this information and also shows min and max values for every watched expression which makes it easier to see how sensors are working.
The debug tool has a huge array of options, the default settings are configured for new users allowing little or zero Arduino knowledge prior to staring a debug session.
The debug tool requires only a USB connection to work and also supports SoftwareSerial (used if the main arduino usb is being used for other purposes). A great benefit of using a simple serial transport for debug data is that it wil also work over GPRS and Radio such as XBee.
Real-time trace and/or message display - entirely replace the need for serial.print() statements
Conditional Breakpoints - Right click break point context menu
The image below shows the context menu that appears when right mouse clicking an Arduino break point in Visual Studio 2010
For the remainder of this document we will use the term "Break point" meaning break point or trace point.
Breakpoints are more effective when they are made conditional by the use of additional code such as if (x>100) or (HitCounter>10) or (TimeSinceLast>100ms) etc. Experienced pogramers will be used to this type of conditional exception reporting but in normal Arduino programming this means surrounding the textual debug messages with additional code. This means editing the Arduino program source every time the conditions or debug messages need to be modified. It's slow messy work which causes development to take much longer than it should.
Messages and Variable/Expression Watch - Replace those old arduino serial print() debug statements!
For non-arduino programs, Microsoft Visual Studio includes very easy to use and feature rich interfaces that enable programmers to set breakpoints, conditions, and many other settings. The ideal debug solution for Arduino would be to allow these standard debug features of Visual Studio to be used within an Arduino project.
The debug facility from Visual Micro does just that. It enables programmers to configure debugging of an Arduino program in the same way a windows program can be debugged. The difference is that Visual Micro interprets the debug commands into Arduino source code dynamically when a programmer decides to upload a debug version of an Arduino program to an Arduino micro-controller. This happens in the background and well away from the real code leaving the original Arduino program in a clean and untouched state.
The image below demonstrates how to create an Arduino debug trace message combined with expressions in curly braces. The expression values will also be available in the expression watch debug window.
In theory, by injecting these additional commands into Arduino code we use additional memory that a normal running Arduino program does not use. However the Visual Micro debug tool does not compile string messages onto the Arduino, instead it retains the messages on the pc and displays them in the debug trace windows at the appropriate times. This results in smaller debug versions of Arduino programs than might normally be achieved with the "old style" Arduino debug facilities.
Feed back from users about the new debugger has been excellent so far. It seems to make Arduino development much easier for both new and experienced users. The result being faster production of working code and successful completion or all types of Arduino project in vastly reduced time-scales. Less hair loss and head scratching!
Watch the Values of Variables and Expressions
As standard the debug tool is able to track complex Arduino expression values with options to see Min,Max,Hex,Binary representation of all debug data.
The expression watch window provides a number of additional options covered in detail in the wiki.
Breakpoints in the expressions watch window also provide a tool tip showing useful configuration and original source code.
The image below shows some of the options available in the Arduino expression watch window.
Hit Counters
An alternative to conditional breakpoints or code conditions is to use the "Hit Count" facility of a break point. By default we can set the number of times a break point is reached before the break point is activated. Example: Activate a break point after 200 hits or every 200 hits etc.
In Arduino terms setting the number of hits might not be so useful because the number might be in the 10's or 100's of thousands. For this reason Visual Micro provides a project property called "Hit Frequency Type" that can be changed from "Count" to "Milliseconds". This change causes all hit counts of the current project to signify a timespan in milliseconds instead of a numeric count. The result in our example would be to activate a break point after or every 200 milliseconds.
Flexibility and Considerations
The open source visualizations are also created using Microsoft Visual Studio and C#. Any .NET (windows) language can be used to create additional debugger visualizations which are easily registered so that the debug tool knows about them. Visualizations can be global for all projects or local to a specific project, can open on demand or in response to certain expressions becoming available within a debug session.
The debugger is not a full hardware debugger, for example it is only possible to watch expression values of expressions that are registered when adding a break point. Break/pause allows only to step between breakpoints and not each line of source between two breakpoints. It is however much easier to use than a hardware debugger and more flexible in terms of data visualization and conditional reporting.
The tool should not be used in dangerous situations without being fully aware of how it works and what possible problems might occur. For example a break point that pauses when a drone rolls past a given angle would cause the drone to crash. Obviously!!
A single Arduino Debug session can run for years - We can re-connect to an existing debug session at any time
One other difference between normal windows application debug and the Arduino debugger is that the Arduino might be running for a significant time such as a month or year. As an example, this means that a debug condition on a remote weather sensor might not be hit for a year. In the meantime the original source code might have altered. Windows debugging does not cater for this situation but the Arduino debug does...
The image below shows how the debugger has retained knowledge of the code that is running on the Arduino, whilst the Visual Studio source code has been altered. You can see that the Arduino is producing a random number between 0 and 2000 whilst the code has been altered to produce a random number between 0 and 4000.
Sit Back And Watch Your Program Running
The debugger currently supports two modes. Continuous operation and/or ability to break/pause at certain points in an Arduino program. Both modes allow trace, messages and variables/expression watch.
Break/pause mode allows stepping from break point to break point, unlike a hardware debugger that allows stepping through every code line. An example of break/pause might be a break point on a line or code that only executes when a button connected to an arduino is pressed (pushed). In this case, when the button is pressed Visual Studio will open the source code containing the button click (if not already open) and highlight the line of code that has been reached.
When demonstrating code to other users, or to see the code of an arduino program that is unfamiliar, well placed breakpoints can be used to clearly show the flow of an arduino program. This is achieved by switching off break/pause and switching on "Debug>Break point Manager>Jump To Trace points". ("Debug" is the little bug icon on the debugger serial window). With these settings applied, all breakpoints will not pause but the respective lines of source code will still be displayed and highlighted.
The result is the cursor will jump from code line to code line and/or source file to source file showing visually what arduino code is actually running at any moment in time. This feature is only useful with well spaced breakpoints that occur no more than a couple of times per second (depends on the speed of your computer)
Execution Speed
The default settings of the debugger are designed for new users and simple non-timing critical project debugging. This enables breakpoints to be used liberally in fast running loops although this is not recommended. We have to keep in mind that the pc can only effectively process 10 or 20 debug messages per second yet in theory the Arduino could send 1000's per second. The debugger will automatically prevent the arduino from swamping the pc should the possibility arise as a result of break point configuration/placement.
All debugger defaults can be overridden or disabled entirely by more expert users. However, if well placed conditional breakpoints are used, there should be no need.
Automated Analog, Digital and Memory Usage Visualizations
In addition to providing break point/step/trace the debugger has a range of other features, some of which cause additional debug messages to be automatically generated, such as Analog Pins Graph and Digital Pin Visualization.
This automated visualization of Arduino Analog and Digital pins can be achieved in two ways. Either by enabling "Micro Reports" in the Project properties or by adding special break point "WhenHit" watch expressions such as {@ReportDigital} and/or {@ReportAnalog}. The break point facility allows finer control over when visualization reports are generated, the automated version are generated at the start of each Arduino loop().
It is recommended that automatic reports are only used if there are no frequently exciting non-pausing breakpoints and that manual break point reports are used, when required, at all other times.
Extensible - Build/customize open source visualizations and plugins for the debugger
In addition to the standard debug trace and expression viewers the debug tool provides graphical visualizations or Analog and Digital pin values along with free memory graphs. The visualizations provided by the debugger are open source, can be altered to represent any data that is being processed on an Arduino.
Arduino Debug Visual Studio 2010 The image below shows a running debug session in Visual Studio 2010 along with, break point expression watch, open source graphical visualizations of Analog and Digital Pins + Custom Guages
View all arduino debugging tutorials. Email beta [at] visualmicro.com to obtain a free copy of the debug tool
How to try and buy + important notes
Visual Micro + and the usb debug tool is available on a 14 day (full) trial or for purchase at 19GBP ($29 approx.) single machine, 29GBP 3 machines plus there are various license options available for commercial use (includes 24 months of free upgrades). Educational establishments should contact us for free licenses.
This is not a perfect technical solution due to the principals of using the arduino core for debug purposes. The debugger can only debug code where an arduino serial command could possibly be placed. (.pde and the cpp/c files of an arduino sketch). In cpp files, only static c++ classes may be debugged.
This integrated software debugger is not the same as a full hardware debugger. It can not be relied upon for use with sensitive and dangerous projects. However it is an easier to use "real world" alternative and contains more productivity features. Requires at least one usb connection and an Arduino
Technical
With the default settings the debugger uses the main arduino upload serial/usb port for debug. If you are new to Arduino and have technical skills you might experiment with "timer0". Timer0 is used by the Arduino serial/usb port so this will prevent the debug from working correctly. In this case use timer2 or switch the debugger "RemoteTransport" to softwareSerial. To use SoftwareSerial you will need a serial/usb converter or an FTDI cable.
References and Disclaimer
The standard plugin for Visual Studio was released in 2009 and has been updated constantly during since. The plugin provides 100% compatible programming and upload to any Arduino hardware. The plugin is used by thousands of people around the world.
New users should note that any type of debugging with a micro-controller can affect the speed at which the cpu (or connected hardware) operate and should not be used, or should be used carefully, for timer critical applications. This said, there are few applications that are timer critical so in the main, debugging is widely used.
This product is provided without warranty and is used entirely at your own risk. The same applies to the Arduino programs that this plugin and debug tool produce. No liability is implied or accepted for anything!
please read the disclaimer and the terms of sale, at least 2 years of new version updates and support on a best endeavors basis, if your circumstances prevent you from buying the debugger please contact us, requests will be dealt with on a case by case basis and a response will be given as quickly as possible but might take a week or longer. The debugger will work better with some hardware than others. Please use the trial and be sure this product meets your needs before buying it. Thank you.
