]>
Commit | Line | Data |
---|---|---|
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 | === Troubleshooting | |
83 | ||
84 | In case a protocol decoder doesn't provide the expected result, there are several things | |
85 | you can check. | |
86 | ||
87 | The first check you should perform is whether the time unit in the ruler | |
88 | is given as "sa". This is short for "samples" and means that the device didn't provide | |
89 | a sample rate and so PulseView has no way of showing a time scale in seconds or | |
90 | fractions thereof. While some decoders can run without timing information, or only | |
91 | optionally make use of the time scale, others may not be able to interpret the | |
92 | input data since timing information is an essential part of the very protocol. | |
93 | ||
94 | Another issue to remain aware of is that decoders need enough samples per protocol step | |
95 | to reliably interpret the information. In typical cases the minimum sample rate should | |
96 | be four to five times the rate of the fastest activity in the protocol. | |
97 | ||
98 | If a protocol decoder runs but shows you annotations that don't seem to make any sense, | |
99 | it's worth double-checking the decoder settings. One common source of error is the | |
100 | baud rate. For example, the CAN protocol decoder doesn't know what baud rate | |
101 | is used on the bus that you captured, so it could be that a different baud rate is used | |
102 | than the one you set. Also, if this is still not the reason for the malfunction, it's | |
103 | worth checking whether any of the signals have been captured inverted. Again using the | |
104 | CAN bus as an example, the decoder will decode the signal just fine if it's inverted but | |
105 | it'll show data even when the signal looks "idle". | |
106 | ||
107 | When a protocol decoder stops execution because of an unmet constraint (required input | |
108 | not connected, essential parameter not specified) or a bug in the decoder itself, you | |
109 | will be presented a static red message in the protocol decoder's display area. | |
110 | In that case, you check the log output in the settings menu. There you'll find the Python | |
111 | error description which you can use to either adjust the configuration, | |
112 | or debug the decoder (and let us know of the fix) or you can copy that information and | |
113 | file a bug report so that we can fix it. | |
114 | ||
115 | Further helpful knowledge and explanations on logic analyzers can be found in our | |
116 | https://sigrok.org/wiki/FAQ#Where_can_I_learn_more_about_logic_analyzers.3F["Learn about logic analyzers" FAQ item]. | |
117 | ||
118 | === Exporting Annotations | |
119 | ||
120 | If you want to postprocess annotations that were generated by a protocol decoder, you | |
121 | can do so by right-clicking into the area of the decode signal (not on the signal label | |
122 | on the left). You are shown several export methods to choose from, with the last one | |
123 | being only available if the cursor is enabled. | |
124 | ||
125 | After you chose a method that suits your needs, you are prompted for a file to export | |
126 | the annotations to. The contents of the file very much depend on the option you chose | |
127 | but also on the annotation export format string that you can define in the _Decoders_ | |
128 | menu of the settings dialog. If the default output isn't useful to you, you can | |
129 | customize it there. | |
130 | ||
131 | === Creating a Protocol Decoder | |
132 | ||
133 | Protocol decoders are written in Python and can be created using nothing more than a | |
134 | text editor. You, too, can write one! | |
135 | ||
136 | To find out how to go about it, please see our https://sigrok.org/wiki/Protocol_decoder_HOWTO[Protocol Decoder How-To] | |
137 | and the https://sigrok.org/wiki/Protocol_decoder_API[Protocol Decoder API Reference]. | |
138 | ||
139 | If you do write one, we'd appreciate if you'd contribute to our project so that everyone | |
140 | can benefit from your work. | |
141 |