Voxellence
commented
2 years ago How to debug NatLink macros
NOTE: If you feel that these instructions are overly verbose, please forgive me. I personally would rather give you too much information than not enough. A major pet peeve of mine is the massive amount of technical instructional material on the internet which fails to give sufficient information. I have often found instructions claiming to show how to do something, which only left me scratching my head and attempting to find more information, sometimes in vain. This leads to frustration and wasted time, especially when you read something that entices you to go down a rabbit hole, only to find yourself on a dead end street. So with that in mind, I'm going to explain what I believe you need to know in as much detail as I possibly can, even if it overlaps with other parts of NatLink's documentation. I'm even going to throw in a little bit of enthusiastic NatLink salesmanship, even though I know you're likely already a NatLink user.
Don't worry if you don't think of yourself as a computer programmer or don't know anything about Python. It's pretty easy to get started, and Python is even easier to use than Visual Basic. So if you ever learned how to use "Advanced Scripting", you can learn this just as easily. In fact, when Joel Gould created NatLink, he did so because he believed it would make writing macros faster and easier, and that people would enjoy writing their macros in Python. He even conducted a survey to find out what people would think!
Install Visual Studio Code (VS Code)
First download and install Visual Studio Code, which is free. You can get it from here:
https://code.visualstudio.com/Download
If you're wondering why Microsoft Visual Studio Code, well, one reason is because according to PYPL it's the second most popular integrated development environment (IDE) in existence today, with Microsoft Visual Studio being in the number one spot (yes, their names are nearly identical, which seems to me a horrible decision, but oh well). Look here to see the rankings for yourself:
https://pypl.github.io/IDE.html
You'll probably also be encouraged to know that Python is ranked as the number one programming language. Apparently Joel Gould made a really smart decision all those years ago.
Both of the Microsoft IDEs use the same Python debugger which is called debugpy, but unlike Visual Studio Code, Visual Studio is not free. Well, actually there is a product called Visual Studio Community Edition which has most of the capabilities of the Professional version, but nevertheless, we're going to stick with Visual Studio Code for our purposes here. Python developers and Web developers alike seem to really love VS Code, and you will too when you find out what it can do for your NatLink and Dragonfly development experience!
Python versions
If you've managed to get the latest version of NatLink installed, then you know that it requires a 32-bit version of Python 3. The original NatLink was designed to use Python 2, which stopped development at version 2.7 as you may know. At the time of writing this, I have installed the 32-bit version of Python 3.9, and I'd recommend that you do the same, but NatLink will likely support other versions in the future.
Fortunately, NatLink is usually smart enough to automatically use the correct version of Python on your computer as long as you have a compatible version installed. If you have any trouble with NatLink finding Python though, please refer to the NatLink documentation.
Open Visual Studio Code
Method 1
-
From a PowerShell command line navigate to the directory where you put your NatLink macros (known in the NatLink documentation as the UserDirectory).
-
Run this command in PowerShell to open your user directory in VS Code...
code . &What do the individual components of that command mean?
codeis the name of the VS Code executable.
.represents the current directory.
&allows you to run VS Code as a "job" in PowerShell.
If you do not use the&, PowerShell will hang until you exit VS Code.
Method 2
-
Open VS Code from the Windows Start Menu.
-
From the VS Code
Filemenu chooseOpen Folder...and navigate in the resulting dialog box to your user directory to open it in VS Code.
Open one of your NatLink or Dragonfly macros
NOTE: I will be referring to areas of the VS Code user interface by the names given to them by Microsoft in order to help you understand what I'm talking about. Please refer to this page to see an image which depicts these areas:
https://code.visualstudio.com/docs/getstarted/userinterface
If you already have one or more macros in your user directory, you can open one of them in VS Code by first navigating to the Explorer tab of the Side Bar. Do this by clicking the icon situated at the very top of the vertical row of icons in the Activity Bar which is located at either the far right or the far left side of your VS Code window. Once you have activated the Explorer tab of the Side Bar, you will see all the files in your user directory listed. Simply click on the macro file of your choice in that list and it will automatically open as a new tab in the VS Code editor.
If you notice that you're not seeing any syntax highlighting for your Python code, it's because you need to install the Python extension for VS Code. Even if you don't have any macros yet, you're still going to need the Python extension.
Hover your mouse over the Activity Bar, moving up and down until you see a pop-up that says "Extensions". Click that icon (which looks like four squares) and then type the word "Python" into the search box near the top of the Side Bar. A list of several extensions will appear, but you'll want to click the very first one which is the Microsoft Python extension, and then click the "Install" button which will appear somewhere in the middle of the VS Code window above where the description of the Python extension is located.
Now go back to your macro file (which should still be opened) by clicking its tab up near the top underneath the menu bar. The text of your macro should now show up with syntax highlighting and colors to make the Python code easier to read and understand. Naturally we don't need to talk about how to write a NatLink or Dragonfly macro here, so if you don't have any macros yet, please copy one or more of the example macros to your user directory and use that as a starting point.
Run Dragon NaturallySpeaking and test NatLink
At this point go ahead and open Dragon NaturallySpeaking (if you haven't already) and activate your microphone. Then speak into your microphone the command words required to run your macro, just to make sure that NatLink is working. Your macro should work just the same as it ever did. The only difference is that now you can edit the code of your macro in the VS Code editor.
A new way of debugging
Under the old paradigm of creating macros by trial and error, probably the main debugging tool you've had in the past was to put print statements into your macro code which would then cause messages to be sent to the Messages from NatLink window when you speak your command. From there you could hopefully figure out what went wrong by looking at those messages, spotting an error in the code, making a correction to the code, speaking the command again, and then looking at the messages in the Messages from NatLink window again.
I seem to recall that there are actually other debugging tools which have been created for debugging NatLink, but those tools, to my understanding, are designed to be used when Dragon is not running. Nevertheless, it's probably worth taking a look at those tools, as they may still be very valuable for solving certain kinds of problems. I must confess my own ignorance about them at this time, so I can't speak to what situations those tools might help with.
Anyway, what we're wanting to do now is to turn your old "black-and-white" process of trial and error into a world of "full color" by enabling live debugging within VS Code, where you could set a breakpoint (a place where you want execution to stop) in the debugger, speak your command, and watch the line of code where the breakpoint is located light up with execution halted at that exact place in your code. From there you could step through your code one line at a time, examine the current values of variables, etc., which would bring you a whole new world of understanding, similar to what you have with the "MyCommands Editor" in the world of Advanced Scripting, only better.
Not only would you be able to step through your own code, but you could even step into natlinkcore code as well, which would give you deep insights into how NatLink actually works. But how do we make that happen? Well, you're about to find out. Yes, I know that I'm being a bit of a dork here, but I am truly excited about this!
Install the debugger
Just as VS Code doesn't come with the Python extension pre-installed, it also does not come with the Python debugger either. Therefore, you'll need to explicitly install the debugger yourself. Just as stated on this Microsoft page...
https://learn.microsoft.com/en-us/visualstudio/python/debugging-python-code-on-remote-linux-machine
...you can install debugpy from a PowerShell command prompt with this command...
pip3 install debugpy
Refer to Microsoft's documentation or support for further guidance if you have trouble with this.
The Secret Sauce
Really there isn't much to getting the debugger to trigger as a result of your utterances once you know how. It's like when you learn the secret to how a magic trick is done; it's usually a bit anti-climactic once you find out. The good news about knowing how to do this though is that it's easy, and that's pretty exciting indeed!
There are three things that you will need to do:
-
Configure VS Code for attaching to a "remote process".
-
Attach the debugger to the Dragon process (which isn't actually remote).
-
Insert a
breakpoint()line into your macro file at the point where you want the debugger to stop execution.
That's really pretty much all there is to it. I'll explain each step in detail below.
NOTE: The reason I'm going the "remote process" route is because, for certain technical reasons, attaching by process ID won't work. Maybe in the future it will work, but for now we can do it the way that's described here.
1. Configure VS Code
In order to create a configuration in VS Code which will allow us to attach the debugger to Dragon's in-memory instance of Python, click on the "play" button which is overlaid with a picture of a "bug" in its lower left corner. You will find this button among the several icons situated vertically one on top of the other in the VS Code Activity Bar at either the right or left edge of your VS Code window. When you hover your mouse over it, you will see a tooltip pop up which says "Run and Debug".
After you have clicked the button you should see a label that says "RUN AND DEBUG" at the top of the VS Code Side Bar. This Run and Debug tab of the Side Bar is broken up into two sections which are each collapsible by clicking an arrow icon in the left margin of the Side Bar. Those two sections are named RUN and BREAKPOINTS. Within the RUN section you will first see a button labeled "Run and Debug". Below the button you will see, "To customize Run and Debug create a launch.json file."
Click on the create a launch.json file hyperlink and a tab entitled Select a debug configuration will appear. From the list of configuration types, click on the one that says, "Remote Attach Attach to a remote debug server". Now you will be given an opportunity to input an IP address. Just leave the default which is "localhost" and press the \<Enter> key on your keyboard. Now you will be given an opportunity to input a port number. Just leave the default which is 5678 and press \<Enter> again, unless you have some reason to change the port number such as a conflict.
Now you will see that a new "launch.json" file has been created for you in your user directory and opened in its own VS Code editor tab. The only thing you might want to change in this new debug configuration is the "justMyCode" option. If you want to be able to step into natlinkcore code, then change true to false next to "justMyCode". Having done that, you can click the X on the "launch.json" file tab in VS Code to close this configuration file.
If you now look back over at the Run and Debug tab of the Side Bar, you will see that the BREAKPOINTS section is still there at the bottom, but the RUN section has been replaced by three different sections named VARIABLES, WATCH, and CALL STACK from the top down respectively. This indicates that VS Code knows that a debug configuration has been created, and it is now presenting you with areas within which to view and manage the various aspects of a debugging session. Refer to the VS Code documentation for detailed information as to what is the purpose of each of these sections.
2. Attach the debugger to Dragon
Before I make a recommendation of some code that you can use to attach the debugger to Dragon, I should mention that there is some code which has been committed to the NatLink repository which you can call that performs a similar task. As far as I can tell, that code has the intention of allowing you to configure a port number and executable file path by storing them in an environment variable. I have been unable to find any related code that reads or writes to an environment variable, but I'm sure that someone will correct me if I've overlooked something. It seems to me though that just writing these values into your own Python file is much simpler than using environment variables.
Create some code
With that in mind, what I recommend is that you create a file in your user directory named debug_natlink.py, and then put the code below into that file. It's essentially just three lines of code and two additional lines which output status messages, all inside a very basic function definition. Very simple.
from debugpy import configure, listen, wait_for_client
def debugger_listen_and_wait():
print("Waiting for client...")
configure(python=r"C:\Program Files (x86)\Python39-32\python.exe")
listen(5678)
wait_for_client()
print("Client attached.")Then at the top of one of your macro files (it doesn't matter which one), place the following import statement and function call:
from debug_natlink import debugger_listen_and_wait
debugger_listen_and_wait()Python executable path
The path to your Python executable is hard-coded above, so if the path to your 32-bit Python installation is different, then you'll need to modify the above code to match the location of your own Python installation.
On the other hand, if you put the path to your 32-bit Python installation into your Windows Path environment variable, then you may not even need to specify the full path in the code above. Personally, I prefer to be explicit because that tends to create less confusion for me. Your mileage may vary.
Port number
The port number is also hard-coded above, so if you inputted any port number other than the default when creating your "launch.json" file, then you'll want to put that same port number in the code above.
Restart Dragon
Exit Dragon and restart it from the Windows Start Menu. When Dragon first loads and your debug_natlink.py macro automatically runs, you'll see a "Waiting for client..." message appear in the "Messages from NatLink" window (see below), immediately after which your configuration code will run. Finally, if the instance of Python embedded in Dragon is found, execution will halt at the line of code which calls debugpy's wait_for_client() function. When this happens, you'll know that the debugger is waiting for you to attach Dragon (the client) to it.
Tell VS Code to attach to Dragon
a. Click the "Run and Debug" button in the VS Code Activity Bar.
b. Click on the downward facing arrow at the right side of the drop-down control situated directly to the right of the "RUN AND DEBUG" label at the top of the Side Bar and make sure that the "Python: Remote Attach" configuration is selected. (It's possible that you may have other configurations in your "launch.json" file which will show up in the drop-down as a debug option, so it's important to be certain that the right one is selected.)
c. Here's the moment of truth. Press the triangular green 'play' button which is directly to the left of the drop-down. This will cause Dragon's in-memory instance of Python to be attached to the VS Code debugger (debugpy).
Confirm that the connection was successful
After you press the 'play' button in VS Code and the connection is made, your debug_natlink.py file will resume execution at the last line of code...
print("Client attached.") ...and you should see this message appear in the Messages from NatLink window.
3. Insert a breakpoint() line into your macro code
Now that the debugger is attached to Dragon, the next step is for you to make sure that you have a code-style breakpoint at the desired location in the macro which you wish to debug. It can be the same macro which you inserted the debug configuration into, or it can be one of your other macros. Only one of your macros needs to have the debug configuration call in it, but you can actually insert breakpoint lines into any of your macro files and debug them. A code-style breakpoint simply looks exactly like the code shown below, except that it should be indented appropriately for the context in which it is located, as required by Python...
breakpoint()
In my experience, the method of creating a breakpoint in VS Code, where you click in the margin of your code file and then see a red dot appear, does not work in the context of debugging NatLink. If you are able to make that kind of breakpoint work, then that's a bonus, but I personally would recommend just using code-style breakpoints.
Speak your command
Having done the three steps described above, you're ready to experience the thrill of live debugging. Speak the command defined in your Python macro and, if all is well, you will see code execution halt on or directly below your breakpoint!
Enjoy the debugging process
At this point you can step through your code, examine and even modify the values of variables, evaluate expressions in the Watch Window, view the Call Stack, etc. Refer to VS Code's documentation as well as the documentation for debugpy for more information.
Happy debugging!
quintijn
dougransom
GregoryShields
LexiconCode
I've finally managed to put together some documentation on how to use Visual Studio Code to perform live debugging of NatLink and Dragonfly macros, where you speak a command and then execution automatically stops in your code at the location of a breakpoint defined by you. I realize that this is a fairly lengthy bit of text, but I feel that it is better to be thorough than to leave out information which may be necessary.
If anyone (@quintijn?) has any advice on exactly how I should proceed with adding my documentation to the NatLink repository, please chime in. I do not want to aggravate anyone or step on anyone's toes.