5 My guide to developing a Sigrok protocol decoder
-- WORK IN PROGRESS --
Sigrok provides a number of pages, but for me they dive too quickly into the detail without giving me any context. They say HOW to do something before you know WHAT to do! I therefore wasted a lot of time on trial-and error.
The Sigrok documents I am aware of are:
- Binaries and Distribution Packages
- How To guide (to writing a Protocol decoder)
- Protocol Decoder API
- Protocol Decoder API Queries
- Sigrok-CLI (Installation and User Guide)
The following is the introduction to this subject that I would have liked to have had before I started!
The Sigrok apps perform as logic analyzers, in conjunction with suitable hardware (not discussed here). There are two instances:
- PulseView is the graphic UI version that can analyze in near real time
- Sigrok-CLI embodies essentially the same program, but without the graphics and is designed to be run from a command line interface
For everyday use, PulseView is the attractive choice; however is has limited capabilities to debug a new development, so for development Sigrok-CLI is recommended.
- Pulseview can conveniently be installed from a binary download. Select the appropriate version for your system, install and open.
- The home screen is blank to start with. You first need to connect your Logic Analyzer hardware device, typically by a USB port on your computer.
- At the top of the home screen, click the button 'no device connected'. In the pop-up window
- select a driver from the list
- search for devices
- select your device
- click OK
- The home screen now shows blank data traces for each of the channels on your logic analyzer device. You can remove any unused channels by right clicking its name and selecting delete. You can change the name and colour of a channel by clicking on its name.
- If you press 'run' at top left you will see your first display of the analyzer channels
To provide more information about analyzed data, Sigrok provides a library of protocol decoders. To use one:
- Click the decoder icon at the top of the screen to open a window listing all available decoders.
- Double click on one that you think corresponds to your data.
- In the main window a line will be added below the data traces. Click on its name to the left of the window to assign the data channels to the decoder. Depending on the protocol, there may be other protocol-specific options.
Each invoked decoder provides one, two or three lines of 'annotations' - short pieces of text under the data traces that identify the elements of the protocol.
Your PulseView installation includes a directory called decoders, whose location depends on the host system type:
- MacOS: it is contained within the pulseview.app package as /Contents/share/libsigrokdecode/decoders *1
- Linux: it is at /usr/local/share/lisigrokdecode/decoders/
- Windows: (not known)
*1 To view the package contents right-click on the pulseview.app in Finder and select 'Show Package Contents'.
The decoders directory contains a sub-directory for each protocol: ac97, ade77xx, adf435x, adns5020, am230x, amulet_ascii, etc.
Within each of those directories, there are two important files (plus possibly a cache folder that inserted by the system):
- init.py
- pd.py
This setup follows the conventions of Python Packaging. PulseView scans the whole decoders directory when it starts up. It uses the contents of the short init.py file to provide text to the user interface.
pd.py contains the actual decoder program, which is derived from the system class sigrokdecode.
When a protocol decoder is used, PulseView calls the routine register in pd.py to collect further relevant details for the protocol such as what the channels are for, and what annotations will be provided.
With this context, you can now read further about init.py and pd.py in the How To guide (to writing a Protocol decoder).
Read about the register() and other mandatory functions for every protocol, in Protocol Decoder API
You can make a new protocol by adding a folder to the decoders folder and inserting the init.py and pd.py files. If you restart PulseView, then the new protocol should be on the list.
The above is sufficient to install a new, working Protocol Decoder into PulseView, but PulseView is not very good for debugging. If it fails to register at all the GUI says nothing. If it registers but encounters an error when running, PulseView GUI only tells you that there is an error. If you run PulseView from the command line, you can enable debugging with
sudo pulseview -l 5
but error output is still limited <to what?>.
For development of a new PD, the CLI version of the app, sigrok-cli is recommended. Like PulseView, Sigrok-CLI can most conveniently be installed from a [binary download(https://sigrok.org/wiki/Downloads#Binaries_and_distribution_packages).
You can now test the sigrok-cli app simply by typing
$ sigrok-cli -h
You should get the help file. That proves the the app is installed correctly.
My description is for Linux; it will be the same in principle for other hosts, but have different file locations.
You can in principle use the same inputs and outputs for both PulseView and Sigrok-CLI, but I find it convenient to
- Use PulseView to sample the data from the hardware, because you can see it
- Save the data from PulseView as a binary file (I tried others, but binary works best)
- Then run Sigrok-CLI with the binary file as input.
- After successfully debugging the PD in Sigrok-CLI, restart PulseView and test it there with the GUI.
My development is a many-times iteration of these steps.
For Sigrok-CLI you can put the PD anywhere you like and then point to it using the environment variable
$ export SIGROKDECODER_DIR=/home/andrewsymons/SAKIP-testenv/decoders
Note that the instructions in the How To guide are incorrect!
However, this does not seem to work for PulseView, so I decided rather to put my development PD straight into the 'production' location /usr/local/share/lisigrokdecode/decoders/ (for Linux)
- You first have to change the permissions so that you have read and write access to the decoders folder
- Within decoders, create a subfolder with the name of your protocol -- in my case sakip.
- Within that directory put the files init.py and pd.py for your new decoder (as discussed above).
This location works for both PulseView and Sigrok-CLI without further CLI parameters or environment variables.
For session, data, and any other files related to the development, I created a test environment folder within my user folder -- in my case (on Linux) /home/andrewsymons/SAKIP-testenv. SAKIP is the name of the protocol for which I am developing a decoder.
Within that folder I have
- the PulseView session data, in session-data.sr (used channels, channel names, and the assignment of channels to the PD)
- subfolder ./sample-data : for sample data files, e.g. sample-data.bin usually output from PulseView and input to Sigrok-CLI.
- subfolder ./test-results : for data output by Sigrok-CLI
- further folders for notes, previous versions and so on.
I navigate to this folder before running Sigrok-CLI, then all input and output files are relative to this location, keeping the path names short.
-
Sample some data using PulseView, then save it as a binary file into your ./sample-data folder with a suitable name, e.g. sample1.bin. By default PulseView does not add an extension but I recommend it.
-
In the terminal CLI navigate to your xxx-testenv folder. Then try the following command to check you can read the input file
$ sigrok-cli -i input-data/sample1 -I binary -O hex -l 5
The '-l' switch sets the debug level, of which 5 is the most verbose. The output is a hex listing on the terminal (more readable than binary).
- If that is successful, we can try the new decoder by adding its name to the sigrok-cli call; in my case:
$ sigrok-cli -i input-data/sample1 -I binary -P sakip -l 5
If it fails, try the same command with an established decoder, such as i2C.
- The output is sent by default to the terminal. If you want to save it, add an output file specifier to the command
$ sigrok-cli -i input-data/sample1 -I binary -P sakip -o output-data/sample1_out -l 5
The full set of sigrok-cli commands is can be listed via the CLI with $ sigrok-cli -h, or on the Sigrok-CLI page in the section 'Manpage' (which has to be expanded to view). (BTW that's 'man' for manual, not a gender bias :-) )
-- More to follow as I gain experience --