]>
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 | 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 |