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 There are all kinds of stacked decoders available, but keep in mind that they're not
  56 shown in the decoder menu. Stacked decoders require a lower-level decoder first before
  57 they become stackable. Most of the time, they require either the UART, I²C or SPI decoder.
  58
  59 You can check the https://sigrok.org/wiki/Protocol_decoders[List of Protocol Decoders]
  60 to see which protocol decoders have been created already.
  61
  62 === Using Decoders on Analog Signals
  63
  64 If you're capturing data using an oscilloscope or import analog signal data from a file,
  65 you'll quickly notice that protocol decoders don't give you the option to select analog
  66 channels as inputs. That is because as of now, decoders only work on logic signals. You
  67 can however convert analog signals into logic signals by choosing a conversion setting
  68 from the signal setting popup.
  69
  70 image::pv_conversion_a2l.png[]
  71
  72 Here, A1 has been converted using a threshold (with default settings) and A2 has been
  73 converted using a Schmitt-Trigger emulation (also with default settings). Additionally,
  74 the conversion threshold display mode has been set to _Background_ in the _Views_ settings
  75 dialog. This way, you can tell how PulseView decided to change the logic signal level
  76 as you can now visually understand where the ranges for high and low are placed.
  77
  78 Aside from the default conversion threshold(s), you can choose from a few common presets
  79 or enter custom values as well. They take the form "0.0V" and "0.0V/0.0V", respectively.
  80
  81 === Exporting Annotations
  82
  83 If you want to postprocess annotations that were generated by a protocol decoder, you
  84 can do so by right-clicking into the area of the decode signal (not on the signal label
  85 on the left). You are shown several export methods to choose from, with the last one
  86 being only available if the cursor is enabled.
  87
  88 After you chose a method that suits your needs, you are prompted for a file to export
  89 the annotations to. The contents of the file very much depend on the option you chose
  90 but also on the annotation export format string that you can define in the _Decoders_
  91 menu of the settings dialog. If the default output isn't useful to you, you can
  92 customize it there.
  93
  94 === Creating a Protocol Decoder
  95
  96 Protocol decoders are written in Python and can be created using nothing more than a
  97 text editor. You, too, can write one!
  98
  99 To find out how to go about it, please see our https://sigrok.org/wiki/Protocol_decoder_HOWTO[Protocol Decoder How-To]
 100 and the https://sigrok.org/wiki/Protocol_decoder_API[Protocol Decoder API Reference].
 101
 102 If you do write one, we'd appreciate if you'd contribute to our project so that everyone
 103 can benefit from your work.
 104