Difference between revisions of "Zynthian Webconf debug with Visual Studio Code (VSC)"

From ZynthianWiki
Jump to navigation Jump to search
 
(34 intermediate revisions by 2 users not shown)
Line 1: Line 1:
'''Debugging Webconf with Visual Studio Code'''
+
== Debugging Webconf with Visual Studio Code ==
  
This is presented as an example of how a Visual Studio Code can be used to examine a component of the zynthian sub system as it runs using the Visual studio Code extensions, python & remote-ssh.
+
This is presented as an example of how Visual Studio Code (VSC) can be used to examine a component of the Zynthian sub system as it runs using the Visual Studio Code extensions: '''Python''' & '''Remote-SSH'''.
These are loaded using the cog dialog at the bottom of the vsc code page.
+
These are loaded using the cog dialog at the bottom of the Visual Studio Code page.
  
  
[[File:Vsc extentions detail.png|thumb|center ]]
+
[[File:Vsc_extentions_detail.png|thumb|center ]]
  
Once you have these components added you can attempt to log onto an existing Zynthian from your PC, MAC, or linux machine, just so long as it's capable of running Visual Studio Code. In my own case I have it running on a 64 bit Raspbian instance, and I had to build it from source to get it running which is a degree of proof of the overall flexibility of what is after all a Microsoft product!   
+
Once you have these components added you can attempt to log onto an existing Zynthian from your PC, MAC, or Linux machine, just so long as it's capable of running Visual Studio Code. In my own case I have it running on a 64-bit Raspbian instance and I had to build it from source to get it running which is a degree of proof of the overall flexibility of what is after all, a Microsoft product!   
  
 
I also tend to add the git-graph extension.  
 
I also tend to add the git-graph extension.  
  
[[File:Vsc git graph.png|thumb|center|Zynthian git graph]]
+
[[File:Vsc_git_graph.png|thumb|center|Zynthian git graph]]
  
'''The ssh connection'''
+
== The ssh connection ==
 +
 
 +
To configure SSH connection to the Zynthian:
 +
 
 +
* Click on the green icon at the bottom left of VSC (tooltip: Open a Remote Window) or F1 then type "Connect to host"
 +
* Select "Connect to host..."
 +
* Select "+ Add New SSH Host..."
 +
* Enter "ssh root@zynthian.local" (use the hostname or IP address of your Zynthian)
 +
* Select "/home/<username>/.ssh/config" to store this configuration in your ssh file (may differ on non *nix systems)
 +
 
 +
To connect to Zynthian:
 +
 
 +
* Click on the green icon at the bottom left of VSC (tooltip: Open a Remote Window) or F1 then type "Connect to host"
 +
* Select the entry for the previously configured host, e.g. "zynthian.local"
 +
* Enter password
  
 
The addition of the remote component adds the Remote Explorer element  
 
The addition of the remote component adds the Remote Explorer element  
[[File:Vsc remote explorer section.png|thumb|center]]
+
[[File:Vsc_remote_explorer_section.png|thumb|center]]
 +
 
 +
I already have a couple of remote Zynthians in the machine and VSC is pretty tenacious at hanging onto remote instances it knows about. But we will try to add a new machine.
 +
 
 +
I have a Zynthian called zynthian-orig.local. It's actually a genuine Zynthian product running a Pi3 and no membrane switches and some fairly simplistic interface. Indeed it has to be disassembled to change the ssd. Such were the early days.!
 +
 
 +
The fact that one can run this debug against the modern code is a sign of great overall consistancy.
 +
 
 +
[[File:Zynthian-orig.local.png|center|500px|Zynthian-orig.local]]
 +
 
 +
== Visual Studio Code Configure. ==
 +
 
 +
First we need to add the extensions.
 +
[[File:Vsc_extensions.png|thumb|center|800px]]
 +
 
 +
activated by the cog in the bottom left hand corner of the Visual Studio Code interface
 +
This will give us a command line that will attempt to log on to the server we are pursuing.. . .
 +
[[File:Vsc remote explorer dialog.png|thumb|center|800px]]
 +
 
 +
So lets make sure that it is actually running.
 +
[[File:Zynthian-sys-security.png|thumb |center|800px]]
 +
 
 +
To access this we press on the + button against the appropriate machine. Visual Studio Code keeps and manages accurate records on the ssh connections you have made. It's handling of details down to the passwords and such and it's overall willingness to just do stuff as you would expect. 
 +
 
 +
[[File:Vsc_remote_explorer_add_new.png|thumb|center|800px]]
 +
 
 +
The -A option...?
 +
 
 +
-A Enable forwarding of the authentication agent connection.
 +
 
 +
[[File:Vsc_remote_explorer_dialog.png|thumb|center|800px]]
 +
 
 +
We enter the details for our specific zynthian machine.  Zynthian runs as root (atm). It always has done so make sure you put root in here. Many hours can be blissfully wile'd away wondering why you can see a machine you'vee loggged into as the wrong user.
 +
[[File:Vsc remote explorer zynthian-orig.png|thumb|center|800px]]
 +
 
 +
[[File:Vsc remote explorer first login.png|thumb|center|800px]]
 +
 
 +
we enter the command we will use to access the remote zynthian which is ssh....
 +
 
 +
And login using the machines root password.
 +
 
 +
[[File:Vsc-remote explorer password.png|thumb|center|800px]]
 +
 
 +
Once VSC has established a connection, it will download the appropriate python components to the zynthian to allow debugging to take place remotely. This make take some time and als o may complain about missing components, giv it some time it will get here if it possibly can....
 +
[[File:Vsc setting up remote server.png|thumb|center|800px]]
 +
 
 +
[[File:Vsc connected.png|thumb|center|800px]]
 +
 
 +
and as you can see the zynthian-orig.local machine is recognised by visual studio code.
 +
 
 +
[[File:Vsc remote explorer connect to host.png|thumb|center|800px]]
 +
 
 +
== Selecting the home directory on the Remote server ==
 +
 
 +
We have logged onto the home directory for the root user, but that isn't where zynthian-webconf runs from....
 +
We should also turn off the running instance but I've left that as a gotcha for later in this walk throu'
 +
 
 +
[[File:Vsc open a folder.png|thumb|center|800px]]
 +
 
 +
VSC will pop up a helpful file location prompt to help this populated with the defualt, we however, wnt to change this.
 +
 
 +
[[File:Vsc select folder default.png|thumb|center|800px]]
 +
 
 +
So we will be using zynthian-webconf so we need to select the appropriate folder location to run this from ... In our case /zynthian-zynthin-webconf/
 +
 
 +
[[File:Vsc select folder zynthian webconf.png|thumb|center|800px]]
 +
 
 +
And when it's done it's stuff you can see and select the python file that runs webconf and examine it....
 +
 
 +
[[File:Vsc zynthian webconf head.png|thumb|center|800px]]
 +
 
 +
== Running the Debugger ==
 +
 
 +
Once you have a specific module in focus you can run the debugger within that module. In this case zynthian_webconf.py ( The module that runs the webconf implementation). We are going to watch MIDI signals being acknowledged in the webconf display.
 +
 
 +
[[File:Vsc start debugging.png|800px|center]]
 +
 
 +
Make sure you have the python debugger extension loaded. This is done via the Cog in the lower left corner and selecting Extensions. Search on Python in the dialog and you should see a similar list to that below. It's a Microsoft component so it's efficacy is established. Select nd it will load it's self, It's pretty good at doing this but do give it some time to complete...
 +
 
 +
[[File:Vsc remote installing.png|800px|center]]
 +
 
 +
Selecting Run from Top meu will offer a set of options including debug. Press on this, and you will be offered a selection of options as below that allow choice of various environments in the python world that you may wish to be involved with. Select the top option.
 +
 
 +
[[File:Vsc debug selection.png|800px|center]]
 +
 
 +
== Turning off Running Webconf instance ==
 +
 
 +
We run the debugger,
 +
 
 +
[[File:Vsc address already in use with stop.png|thumb|center|800px]]
 +
 
 +
Error!!
 +
 
 +
but there is already a process running that has grabbed the port 80. It's the zynthian-webconf instance that is started by the raspberry pi when it starts up by systemd and this will need to be stopped to allow us to run our own instance....
 +
 
 +
So we use the terminal to generate a command line prompt and shout at systemd to turn of the running instance
 +
 
 +
 
 +
<big>systemctl stop zynthian-webconf</big>
 +
 
 +
[[File:Vsc stop webconf systemd.png|thumb|center|800px]]
 +
 
 +
And look it's no longer running!!!
 +
 
 +
[[File:Zynthian dead webconf.png|thumb|center|800px]]
 +
 
 +
== Running the debugger in anger ... ==
 +
 
 +
So leaving with the zynthian-webconf.py module highlighted start the debugger as before.
 +
 
 +
And then go and open the lib/midi_log_handler.py page once the web server is running and highlight the line 132 by pressing to the left of the line number
 +
a red circle should appear. . .
 +
[[File:Vsc debug line 132.png|thumb|center|800px]]
 +
 
 +
Then select the midi log page within webconf and play some midi . . . .
  
I already have a couple of remote zynthians in the machine and VSC is pretty tenacious at hanging onto remote instances it knows about. But we will try to add a new machine.
+
[[File:Zynthian-orig running midi.png|thumb|center|800px]]
  
I have a zynthian called zynthian-orig.local. It's actually a genuine zynthian product running a Pi3 and no membrane switches and some fairly simplistic interface. Indeed it has to be disassembled to change the ssd. Such were the early days.!
+
The program will halt on the debug line 132, and you should be able to operate the debugger transport controls and all the nice debug tools that will display and set values.
 +
The following shows it after step over has been pressed twice. . .  
  
[[File:Zynthian-orig.local.png|frame|center|Zynthian-orig.local]]
+
[[File:Vsc debug stepover.png|thumb|center|800px]]

Latest revision as of 16:01, 15 February 2022

1 Debugging Webconf with Visual Studio Code

This is presented as an example of how Visual Studio Code (VSC) can be used to examine a component of the Zynthian sub system as it runs using the Visual Studio Code extensions: Python & Remote-SSH. These are loaded using the cog dialog at the bottom of the Visual Studio Code page.


Vsc extentions detail.png

Once you have these components added you can attempt to log onto an existing Zynthian from your PC, MAC, or Linux machine, just so long as it's capable of running Visual Studio Code. In my own case I have it running on a 64-bit Raspbian instance and I had to build it from source to get it running which is a degree of proof of the overall flexibility of what is after all, a Microsoft product!

I also tend to add the git-graph extension.

Zynthian git graph

2 The ssh connection

To configure SSH connection to the Zynthian:

  • Click on the green icon at the bottom left of VSC (tooltip: Open a Remote Window) or F1 then type "Connect to host"
  • Select "Connect to host..."
  • Select "+ Add New SSH Host..."
  • Enter "ssh root@zynthian.local" (use the hostname or IP address of your Zynthian)
  • Select "/home/<username>/.ssh/config" to store this configuration in your ssh file (may differ on non *nix systems)

To connect to Zynthian:

  • Click on the green icon at the bottom left of VSC (tooltip: Open a Remote Window) or F1 then type "Connect to host"
  • Select the entry for the previously configured host, e.g. "zynthian.local"
  • Enter password

The addition of the remote component adds the Remote Explorer element

Vsc remote explorer section.png

I already have a couple of remote Zynthians in the machine and VSC is pretty tenacious at hanging onto remote instances it knows about. But we will try to add a new machine.

I have a Zynthian called zynthian-orig.local. It's actually a genuine Zynthian product running a Pi3 and no membrane switches and some fairly simplistic interface. Indeed it has to be disassembled to change the ssd. Such were the early days.!

The fact that one can run this debug against the modern code is a sign of great overall consistancy.

Zynthian-orig.local

3 Visual Studio Code Configure.

First we need to add the extensions.

Vsc extensions.png

activated by the cog in the bottom left hand corner of the Visual Studio Code interface This will give us a command line that will attempt to log on to the server we are pursuing.. . .

Vsc remote explorer dialog.png

So lets make sure that it is actually running.

Zynthian-sys-security.png

To access this we press on the + button against the appropriate machine. Visual Studio Code keeps and manages accurate records on the ssh connections you have made. It's handling of details down to the passwords and such and it's overall willingness to just do stuff as you would expect.

Vsc remote explorer add new.png

The -A option...?

-A Enable forwarding of the authentication agent connection.

Vsc remote explorer dialog.png

We enter the details for our specific zynthian machine. Zynthian runs as root (atm). It always has done so make sure you put root in here. Many hours can be blissfully wile'd away wondering why you can see a machine you'vee loggged into as the wrong user.

Vsc remote explorer zynthian-orig.png
Vsc remote explorer first login.png

we enter the command we will use to access the remote zynthian which is ssh....

And login using the machines root password.

Vsc-remote explorer password.png

Once VSC has established a connection, it will download the appropriate python components to the zynthian to allow debugging to take place remotely. This make take some time and als o may complain about missing components, giv it some time it will get here if it possibly can....

Vsc setting up remote server.png
Vsc connected.png

and as you can see the zynthian-orig.local machine is recognised by visual studio code.

Vsc remote explorer connect to host.png

4 Selecting the home directory on the Remote server

We have logged onto the home directory for the root user, but that isn't where zynthian-webconf runs from.... We should also turn off the running instance but I've left that as a gotcha for later in this walk throu'

Vsc open a folder.png

VSC will pop up a helpful file location prompt to help this populated with the defualt, we however, wnt to change this.

Vsc select folder default.png

So we will be using zynthian-webconf so we need to select the appropriate folder location to run this from ... In our case /zynthian-zynthin-webconf/

Vsc select folder zynthian webconf.png

And when it's done it's stuff you can see and select the python file that runs webconf and examine it....

Vsc zynthian webconf head.png

5 Running the Debugger

Once you have a specific module in focus you can run the debugger within that module. In this case zynthian_webconf.py ( The module that runs the webconf implementation). We are going to watch MIDI signals being acknowledged in the webconf display.

Vsc start debugging.png

Make sure you have the python debugger extension loaded. This is done via the Cog in the lower left corner and selecting Extensions. Search on Python in the dialog and you should see a similar list to that below. It's a Microsoft component so it's efficacy is established. Select nd it will load it's self, It's pretty good at doing this but do give it some time to complete...

Vsc remote installing.png

Selecting Run from Top meu will offer a set of options including debug. Press on this, and you will be offered a selection of options as below that allow choice of various environments in the python world that you may wish to be involved with. Select the top option.

Vsc debug selection.png

6 Turning off Running Webconf instance

We run the debugger,

Vsc address already in use with stop.png

Error!!

but there is already a process running that has grabbed the port 80. It's the zynthian-webconf instance that is started by the raspberry pi when it starts up by systemd and this will need to be stopped to allow us to run our own instance....

So we use the terminal to generate a command line prompt and shout at systemd to turn of the running instance


systemctl stop zynthian-webconf

Vsc stop webconf systemd.png

And look it's no longer running!!!

Zynthian dead webconf.png

7 Running the debugger in anger ...

So leaving with the zynthian-webconf.py module highlighted start the debugger as before.

And then go and open the lib/midi_log_handler.py page once the web server is running and highlight the line 132 by pressing to the left of the line number a red circle should appear. . .

Vsc debug line 132.png

Then select the midi log page within webconf and play some midi . . . .

Zynthian-orig running midi.png

The program will halt on the debug line 132, and you should be able to operate the debugger transport controls and all the nice debug tools that will display and set values. The following shows it after step over has been pressed twice. . .

Vsc debug stepover.png