Aug 2012: First draft, pre-release - About The Visual Micro Extension Framework
Debugger visualizations are controls and/or windows written in any .NET language that enable us to graphically display remote debug data from a micro-controller such as an arduino. This means that any open source .net instrument/control project that can be found on the internet can be used as a visualization. The micro extension framework is a set of easy to implement inheritable classes that enable an application to interact with the arduino debugger and also with visual studio. Visualizations are loaded with full trust and have access to a computer in the same way that other visual studio addins can access a computer.
The Visual Micro inheritance system is optional, but provides an easy way to manage a debug state server. Below is an example of a >NET form constructor requesting notification of 3 visual micro debugger events. (OnDebugInit, OnDebugStateChanged, OnDataExpressionValuesChanged)
InitializeComponent(); //standard vs component init
- this.OnDebugInit += onDebugInit; //fires when debug is started before connect to micro
- this.OnDebugStateChanged += onDebugStateChanged; //fires whenever a debug state change occurrs
- this.OnDataExpressionValuesChanged += onExpressionValuesChanged; //fires when a watched expression breakpoint is hit
- void onDebugInit(object sender, DebugInitEventArgs e)
- void onExpressionValuesChanged(object sender, ExpressionValuesChangedArgs e)
- void onDebugStateChanged(object sender, DebugStateChangedArgs e)
The Visual Micro debug upgrade is supplied with a few basic working examples such as Digital Pin Viewer, Analog Graphs and other examples, found on the internet and adapted to be intelligent visualizations. All of the example are supplied with full source, attributed to the original authors, and may be feely copied or extended.
Visualizations are therefore simply just .NET dll(s) and all that is needed to register them into Visual Micro is a MicroExtension.xml file. The xml file provides a unique name for the visualization, a caption, path to the dll and namespace.className of the control to be loaded. The file also allows "Watched" expressions "of interest" to be registered and setting of the "Startup" type.
"StartUp" types include:-
- open when watched expression is hit
- open when debug starts
- open when user demands
The captions of all open/running Visualizations will appear on the "Running Visualizations" menu of the debug button in the serial tool window. This menu item allows us to hide/show active visualizations for the current project. (Settings are retained after vs closes)
The captions of any "When User Demands" visualizations will appear on the "Other Windows" menu of the the debug button in the serial tool window. This menu allows us to enable/disable a visualization for the current project. (settings are retained after vs closes)
Visualizations can be placed in specific folders in any one of three locations. Under the vm program folder, under My Document, under a sketch folder. The latter being specific visualizations for a single sketch project.
To create a visualization we create a normal .net class project and set the COM Visible property to true (Project>Properties>Build>Assembly>Com Visible checkbox. Adding a UserControl or Form to the class project and inheriting MicroDebugDataVisualizationWindowBase or MicroDebugDataVisualizationControlBase
To gain access to these inheritable classes the project must contain a reference to Visual.Micro.Debugger.Data.Extensions" assembly that is available in the global assemblies list. Tip: Right click the project and select "Add Reference". Alternatively copy and rename one of the provided Visual Micro examples which will already be configured with the reference :)
The xml object is an optional helper, if you have experience with xml you might have a better solution.
If we copy an existing Visualization we must replace the projects "Assembly" guid with a new one. Create a new guid using Tools>Create Guid. Set the new guid against the project by right clicking the project and clicking the Advaned or Assembly button
How can we debug our visualizations
Currently, the controls shipped with visual micro are .NET3.5 format so that they work for both VS 2008 and 2010 users. If you are using VS2010 and want to debug a visualization it is recommended that you switch the .NET version (project properties) to 4.0. If you do not do this then you will not be able to use "Start>debugging" in your c# or vb projects. Instead you will have to use "Tools>Attach to process" once you have an Arduino sketch open in Visual Studio. "Start>debugging" is the recommended debug option because it will allow you to edit/change your code during an active debug session.
It gets a bit confusing because to debug your visualization you will have two debug sessions running in two different visual studio instances. One for your visualization and one for the arduino :) You should also bear in mind that if you havd a sloe machine or if you hit a breakpoint in your C#/Vb code the pc will fall behind realtime with the arduino. This is not a probleme except it might cause confusion. So after breaking into a visualization and fixing a bug, I suggest re-starting the debug session.
When you try to start>debug a class project in visual studio you may encounter a message telling you that class projects can't be debugged directly. Our extension is a Visual Studio plugin so we actually want to debug visual studio when it is running our extension.
To make the debug work correctly, right click the project and open the project properties window. Click the "Debug" tab and click the radio button called "Start external program:". Enter the full path to your visual studio program in the box. An example being "C:\Program Files (x86)\Microsoft Visual Studio 10.0\Common7\IDE\devenv.exe". On the same screen, set the "Working directory:" to the folder containing the devenv.exe, an example might be "C:\Program Files (x86)\Microsoft Visual Studio 10.0\Common7\IDE\"
Once you have set .NET4 and configured the options above you can switch the visualization project to "Debug" mode and press F5. This will start visual studio so you can open a sketch project that will use the visualization. Configure the sketch for "Full" debug and press F5 to start the arduino debugger. When the visualization opens in the arduino debugger your breakpoints should be hit in the visualization control debugger.
Important Point: When a visualization has been loaded into a tool window by an instance of visual studio, the visualization (dll) will not be unloaded/released until the Visual Studio instance exists. A hidden visual studio tool window is still open and available. You will not be able to re-compile the visualization while the assembly remains loaded into another visual studio instance
Whilst a visualization dll can not be re-loaded without re-starting visual studio it is possible to alter the settings in the MicroExtension.xml which is re-loaded each time the debugger starts. This also means that is is possible to add new extensions without re-starting visual studio, Visual Micro will auto detect new xml files each time the debugger starts.
The MicroExtension.xml file also provides the facility for "User Settings" allowing the visualization to dynamically render different graphics based upon xml properties. This means that a single visualization control can be highly customizable without the need to re-compile or re-build the visualization dll.
Below is an example of a very basic visualization. The project provides 3 cicular dial instrument controls (like speedometers). When the arduino debug starts the visualization is notified and is also provided with the xml object of the MicroExtension.xml along with simple functions to provide the xml data to the c#/vb code.
The c#/vb visualization example responds to the visual micro "OnDebugInit" event and initializes its graphical controls based upon the xml properties. This means that you can create a flexible visualization control that can be used in different ways by different people or in different projects.
In the xml example below the xml is a know visual micro structure except for "ConfigSettings". This section(s) is entirely user defined but it is hoped we find and agree a standard that we can all work with.
ConfigSettingSensor1 = MicroGetVisualizationConfigSetting("Sensor1");
ValueExpressionNameSensor1 = XmlHelper.GetAttribute(ConfigSettingSensor1, "ValueExpressionName")
Caption="Sketch Debug Example 1"