Showing Text and Watching Expressions When a Breakpoint is Hit

Non-VS2015 Logos
This version of the documentation page applies to Visual Studio prior to VS2015 and to all versions of Atmel Studio.
Read documentation page for Visual Studio 2015 here.

You can specify, which information from your program (values of variables etc.) shall be transmitted to Visual Micro when the breakpoint is hit. This can be a fixed text as well as values of variables or expressions. You can also change a variable's values on your PC and then can continue execution with the new variable value.

All this can be achieved with breakpoints that have a "When Hit" action.

Note Icon Note

After making changes to your breakpoint as shown here, you must recompile and upload your sketch in order for the changes to get become effective.

How to Create a Breakpoint With a "When Hit" Action

Read on the general Breakpoints documentation page on how to set breakpoints.

To create a "When Hit" action for your breakpoint, right click the Breakpoint Indicator marker of an existing breakpoint at the left of your code and choose "When Hit...":

Hit Count Breakpoint Context Menu

The "When Hit" function is a very powerful tool of Visual Micro. It lets you show the values of variables and lets you change their values while your sketch is halted in a breakpoint.

After you selected "When Hit..." from the breakpoint context menu, this window will appear:

When Hit Window

In the text field, you can enter a message that will be shown when the breakpoint is hit. The message will appear in the Output Window:

If you put the following in the "When Hit" text field: "Hello from my board!",...

When Hit "Hello" text

... then the Output Window will show the following when the breakpoint is hit:

Hello Message in Output Window 

Warning 16 Note:

Please notice, that the "Continue Execution" box is checked by default:

When Hit Continue Execution Checkbox

This means that the code does not halt at this point anymore (=breakpoint), but only show a message in the output window (=tracepoint).
If you want the breakpoint to halt your code as before, make sure that this box is unchecked.

Showing variable values

You can not only print static text in your message, but also the current values of variables.
Put the name of the desired variable in curly braces inside your text, like in this example:

When Hit Variable Example

The Output Window will show the following when the breakpoint is hit:

Variable Message in Output Window

The message shows the actual value of the "hum" variable every time the breakpoint is hit.

You can mix text and variables as you like, and you can also insert more two or more variables in the "When Hit" text. See below for more information about the "When Hit" message string.

If you have an Expression Window open, then the variable value is also reported there. See below.

More on "When Hit" strings

Showing more than one variable

You can insert two or more variables in the "When Hit" string:


"Position is {position} and temperature is {currTemp}"

Changing display format

You can specify how your variables are displayed by adding a format specifier to the message string.


"Position is {position,HEX}" will show the variable in hexadecimal.
You can find a complete listing of available formats in the description of the Serial.print() function in the Arduino library reference.

Showing expressions

Instead of variables, you can show expressions, like in this "When Hit" message string:


"Humidity is {humidity*22.1}"

Expressions can also include function calls:

"Humidity is {getHumidityFromSensor()}"

"Time elapsed is {millis()-startTime} milliseconds"

"Valve {valveNo} is {valvePos == V_SHUT ? "shut" : "open"}"

Tracking and Changing Variable Values Using the Expression Window

You will notice that there is an "Expression Window" while your debugging session is running. If this window is missing, make it visible by clicking the Serial Monitor button in the Visual Micro toolbar:

VM Toolbar Serial Monitor Button

The Expression Window shows the actual values of all the variables mentioned in the message strings. Every time a breakpoint is hit, the respective values will be updated in the Expression Window.

 Expression Window

In the above example, we have two breakpoints:

Breakpoint 1 is located in Blink.ino, line 25 and contains this message string: "Humidity is {humidity}, counter is {counter=?}" (We will take a closer look at that "=?" after "counter" later). This lets the values of "humidity" and "counter" appear in the Expression Window.

Breakpoint 2 is located in Blink.ino, line 35 and contains this message string: "valve position is {position}". This lets the value of "position" appear in the Expression Window.

Values shown in red have changed since the last breakpoint hit.

Changing variables

If you put a "=?" behind a variable name, then you will not only see the value in the Expression Window, but you will also be able to change the variable's value if your sketch is halted in a breakpoint.

In the above example, the variable "counter" is defined like this: "{counter=?}". In the Expression Window these variables are shown with a yellow background.

To change the value, click into the yellow cell and enter a new value. If you press [F5] to continue execution on your board, the changed variable value (in this case a "counter" value of 3) will be used.

Note IconNote:

In order to be able to change a variable, it must be part of the "When Hit" text of the current breakpoint, even though the grid cell always appears in yellow.

Showing the function name

You will notice that the "When Hit" window's text mentions "special keywords" like $FUNCTION or $CALLER. Of these keywords, Visual Micro supports $FUNCTION. If you use this keyword in your message string, it will be replaced by the function's name where the breakpoint is placed.


If you enter this message string: "Hello from the $FUNCTION function", then you will get this string in the Output Window:

Function Name in Output Window

The $FUNCTION placeholder was replaced by the name of the function where the breakpoint resides. Please note that this placeholder does not require curly brackets like variable placeholders.

Analog, Digital and Performance Reporting

Visual Micro can report the current status of the analog and digital inputs/outputs of your board as well as the devices connected to the I2C bus of your CPU.

If you put the following keywords into the "When Hit" field of your breakpoint, Visual Micro will open diagram windows when you sketch is started that show these values in real time.

Updates the status of the digital I/O lines of your board and opens the "Report Digitals" diagram window
Updates the status of the analog I/O lines of your board and opens the "Report Analogs" diagram window
Updates the diagram showing the amount of free memory and opens the "Report Free Memory" diagram window
Updates the list of connected I2C devices and sends a list of connected I2C devices to the Output Window

Changing the Expression Window's Columns

The "Min" and "Max" columns of the expression window show the minimum and maximum value the variable had over time.
If you right click on the grid header, a context menu appears where you can show/hide various columns of the table:

   Expression Window Header Context Menu

Note IconNote:

The Time column does not show the time when the last breakpoint was hit, but the last time the variable's value has changed.