]>
Commit | Line | Data |
---|---|---|
1894027b SA |
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, | |
b82e8832 | 53 | which was then reported to be "10.03.2013 23:35:30". |
1894027b | 54 | |
7f030756 SA |
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. | |
1894027b | 60 | |
7f030756 | 61 | For a list of available and planned protocol decoders, you can https://sigrok.org/wiki/Protocol_decoders[check the wiki]. |
1894027b SA |
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 | ||
b82e8832 SA |
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 | ||
a0241dc5 SA |
124 | === Troubleshooting |
125 | ||
126 | In case a protocol decoder doesn't provide the expected result, there are several things | |
460051d9 GS |
127 | you can check. |
128 | ||
129 | The first check you should perform is whether the time unit in the ruler | |
a0241dc5 SA |
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 | |
460051d9 | 132 | fractions thereof. While some decoders can run without timing information, or only |
b82e8832 SA |
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. | |
460051d9 GS |
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 | |
b82e8832 | 138 | be 4-5 times the rate of the fastest activity in the protocol (e.g. its clock signal). |
a0241dc5 SA |
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 | |
460051d9 | 142 | baud rate. For example, the CAN protocol decoder doesn't know what baud rate |
a0241dc5 | 143 | is used on the bus that you captured, so it could be that a different baud rate is used |
b82e8832 SA |
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 | |
a0241dc5 SA |
147 | it'll show data even when the signal looks "idle". |
148 | ||
460051d9 GS |
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 | |
a0241dc5 | 151 | will be presented a static red message in the protocol decoder's display area. |
b82e8832 SA |
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. | |
a0241dc5 | 156 | |
1e6d5996 SA |
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]. | |
ee6096a8 | 159 | |
1894027b SA |
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 | ||
b82e8832 SA |
167 | image::pv_ann_export_menu.png[] |
168 | ||
1894027b SA |
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 | ||
b82e8832 SA |
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 | ||
1894027b SA |
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 |