manual/decoders.txt

   1 == Decoders
   2
   3 Protocol decoders are one of the key elements of PulseView's functionality. They take
   4 input data that you acquired and process it in a way that results in a (hopefully) much
   5 easier to understand representation of that same data.
   6
   7 In its simplest form, a protocol decoder (PD) converts a group of 1-bit signals into a
   8 stream of n-bit events. This is exactly what the parallel PD does: it takes for example
   9 8 logic channels and treats them like an 8-bit parallel bus, emitting annotations that
  10 show the current state of the bus at any point in time.
  11
  12 === Basic Operation
  13
  14 Another one of the protocol decoders available to you is the I²C decoder. It takes the
  15 two I²C signals SCL and SDA (serial clock / serial data) and shows you the details of
  16 the I²C communication without the need to evaluate the signal bit by bit yourself.
  17
  18 As an example, let's have look at one of the sample .sr files we keep around for
  19 validation of the PD code base: https://sigrok.org/gitweb/?p=sigrok-dumps.git;a=blob_plain;f=i2c/rtc_dallas_ds1307/rtc_ds1307_200khz.sr;hb=HEAD[rtc_ds1307_200khz.sr].
  20 It contains the capture of an I²C master interacting with a https://www.maximintegrated.com/en/products/digital/real-time-clocks/DS1307.html[Dallas DS1307 I²C Real-Time Clock]
  21 where the master repeatedly sets and queries the time of day. After loading and using
  22 "zoom-to-fit", it looks similar to this:
  23
  24 image::pv_decoders_1.png[]
  25
  26 Adding the I²C decoder by clicking on ➊ and selecting I²C from the list adds
  27 a new decode signal to the view. PulseView tries to match existing signals to the signals
  28 that the newly added protocol decoder needs to function, which is what happened here -
  29 SCL and SDA have been automatically assigned and the PD has decoded the communication with
  30 the default parameters. If you need to change the signal assignment or change the decoding
  31 parameters, you can click on ➋ to do so.
  32
  33 When you zoom in, you now see that PulseView has decoded the I²C messages and displays
  34 these annotations as part of the decode signal (note that we have zoomed in so far that
  35 PulseView shows you the individual samples):
  36
  37 image::pv_decoders_2.png[]
  38
  39 This is already very useful, and a massive improvement over counting out pulses on an
  40 oscilloscope screen. However, sigrok allows us to go one step further with the use of
  41 so-called stacked decoders.
  42
  43 === Decoder Stacking
  44
  45 To add a stacked decoder we open the settings of the decode signal, go to the _Stack
  46 Decoder_ menu ➊, and select the DS1307 decoder:
  47
  48 image::pv_decoders_3.png[]
  49
  50 With the stacked decoder added, we can now see that PulseView has decoded the meaning
  51 of the I²C commands, so that we don't need to bother searching the reference manual.
  52 In this view, we can see that the I²C packet was a command to read the date and time,
  53 which was then reported to be "10.03.2013 23:35:30".
  54
  55 In this example, we added the I²C and DS1307 decoders separately. However, when opening
  56 the decoder selector window, you can also double-click on the DS1307 decoder and PulseView
  57 will try to auto-resolve the dependencies needed to use this decoder. In case there are
  58 ambiguities (e.g. when several different protocol decoders offer 'uart' output), it will
  59 ask you to choose which one to use.
  60
  61 For a list of available and planned protocol decoders, you can https://sigrok.org/wiki/Protocol_decoders[check the wiki].
  62
  63 === Using Decoders on Analog Signals
  64
  65 If you're capturing data using an oscilloscope or import analog signal data from a file,
  66 you'll quickly notice that protocol decoders don't give you the option to select analog
  67 channels as inputs. That is because as of now, decoders only work on logic signals. You
  68 can however convert analog signals into logic signals by choosing a conversion setting
  69 from the signal setting popup.
  70
  71 image::pv_conversion_a2l.png[]
  72
  73 Here, A1 has been converted using a threshold (with default settings) and A2 has been
  74 converted using a Schmitt-Trigger emulation (also with default settings). Additionally,
  75 the conversion threshold display mode has been set to _Background_ in the _Views_ settings
  76 dialog. This way, you can tell how PulseView decided to change the logic signal level
  77 as you can now visually understand where the ranges for high and low are placed.
  78
  79 Aside from the default conversion threshold(s), you can choose from a few common presets
  80 or enter custom values as well. They take the form "0.0V" and "0.0V/0.0V", respectively.
  81
  82 === Per-row Settings and Actions
  83
  84 Sometimes, you don't want to see all protocol decoder rows or all of the annotation classes
  85 available in a row. To do so, simply click on the arrow or label of the row you want to
  86 customize.
  87
  88 image::pv_class_selectors.png[]
  89
  90 From that menu, you can either show/hide the entire row or choose the annotation classes
  91 you want to see. Everything is visible by default but if you want to focus on specific
  92 protocol messages or status annotations like warnings or errors, this should help.
  93
  94 Also, if you are examining really long traces, disabling annotations for the most-often
  95 occuring class (e.g. bit annotations for SPI) then drawing performance will increase, too.
  96
  97 === Binary Decoder Output
  98
  99 While all protocol decoders create visible annotations, some of them also create binary
 100 output data which isn't immediately visible at the moment. However, you can examine it
 101 by opening the Binary Decoder Output View as shown below.
 102
 103 image::pv_binary_decoder_output_view.png[]
 104
 105 Once opened, you need to select a decoder with binary output for it to show anything -
 106 among which are I2C, I2S, EEPROM24xx, SPI and UART. Having acquired some I2S data and
 107 using the I2S protocol decoder lets you have the sound data as raw .wav file data, for
 108 example:
 109
 110 image::pv_binary_decoder_output_view_i2s.png[]
 111
 112 Using the save icon at the top then lets you save this data either as a binary file
 113 (in this case creating a valid .wav file) or various types of hex dumps. If you want to
 114 only save a certain part of the binary data, simply select that part before saving.
 115
 116 You may have noticed that the bytes are grouped by color somehow. The meaning behind
 117 this is that every chunk of bytes emitted by the protocol decoder receives one color,
 118 the next chunk another color and so on. As there are currently three colors, the cycle
 119 repeats. This makes it easier to visually organize the data that you see - in the case
 120 of the I2S decoder, the header has one color because it's sent out in one go and
 121 following that, every sample for left/right consists of 4 bytes with the same color
 122 since they're sent out one by one.
 123
 124 === Troubleshooting
 125
 126 In case a protocol decoder doesn't provide the expected result, there are several things
 127 you can check.
 128
 129 The first check you should perform is whether the time unit in the ruler
 130 is given as "sa". This is short for "samples" and means that the device didn't provide
 131 a sample rate and so PulseView has no way of showing a time scale in seconds or
 132 fractions thereof. While some decoders can run without timing information, or only
 133 optionally make use of it, others may not be able to interpret the input data since
 134 timing information may be an essential part of that protocol.
 135
 136 Another issue to remain aware of is that decoders need enough samples per protocol step
 137 to reliably interpret the information. In typical cases the minimum sample rate should
 138 be 4-5 times the rate of the fastest activity in the protocol (e.g. its clock signal).
 139
 140 If a protocol decoder runs but shows you annotations that don't seem to make any sense,
 141 it's worth double-checking the decoder settings. One common source of error is the
 142 baud rate. For example, the CAN protocol decoder doesn't know what baud rate
 143 is used on the bus that you captured, so it could be that a different baud rate is used
 144 than the one you set. If this is still not the reason for the malfunction, it's worth
 145 checking whether any of the signals have been captured inverted. Again using the CAN
 146 bus as an example, the decoder will decode the signal just fine if it's inverted but
 147 it'll show data even when the signal looks "idle".
 148
 149 When a protocol decoder stops execution because of an unmet constraint (required input
 150 not connected, essential parameter not specified) or a bug in the decoder itself, you
 151 will be presented a static red message in the protocol decoder's display area.
 152 In that case, you can check the log output in the settings menu. There you'll find the
 153 Python error description which you can use to either adjust the configuration,
 154 debug the decoder (and let us know of the fix) or create a bug report so that we can
 155 fix it.
 156
 157 Further helpful knowledge and explanations on logic analyzers can be found in our
 158 https://sigrok.org/wiki/FAQ#Where_can_I_learn_more_about_logic_analyzers.3F["Learn about logic analyzers" FAQ item].
 159
 160 === Exporting Annotations
 161
 162 If you want to postprocess annotations that were generated by a protocol decoder, you
 163 can do so by right-clicking into the area of the decode signal (not on the signal label
 164 on the left). You are shown several export methods to choose from, with the last one
 165 being only available if the cursor is enabled.
 166
 167 image::pv_ann_export_menu.png[]
 168
 169 After you chose a method that suits your needs, you are prompted for a file to export
 170 the annotations to. The contents of the file very much depend on the option you chose
 171 but also on the annotation export format string that you can define in the _Decoders_
 172 menu of the settings dialog. If the default output isn't useful to you, you can
 173 customize it there.
 174
 175 image::pv_ann_export_format.png[]
 176
 177 For example, the string "%s %d: %1" will generate this type of output for the DS1307
 178 RTC clock protocol decoder: "253-471 DS1307: Read date/time: Sunday, 10.03.2013 23:35:30"
 179
 180 === Creating a Protocol Decoder
 181
 182 Protocol decoders are written in Python and can be created using nothing more than a
 183 text editor. You, too, can write one!
 184
 185 To find out how to go about it, please see our https://sigrok.org/wiki/Protocol_decoder_HOWTO[Protocol Decoder How-To]
 186 and the https://sigrok.org/wiki/Protocol_decoder_API[Protocol Decoder API Reference].
 187
 188 If you do write one, we'd appreciate if you'd contribute to our project so that everyone
 189 can benefit from your work.
 190