X-Git-Url: https://sigrok.org/gitweb/?p=pulseview.git;a=blobdiff_plain;f=manual%2Fdecoders.txt;h=d50a6983e02457ec686e8d4e105ac55cd3c378c3;hp=aef3034b2f88cccf65b286ececde727b34258de9;hb=7f030756dbd3a893265bf2fc790a349e1babfc4d;hpb=1894027b98640702a5229c4168c586df5f83a3af

diff --git a/manual/decoders.txt b/manual/decoders.txt
index aef3034b..d50a6983 100644
--- a/manual/decoders.txt
+++ b/manual/decoders.txt
@@ -50,14 +50,15 @@ image::pv_decoders_3.png[]
 With the stacked decoder added, we can now see that PulseView has decoded the meaning
 of the I²C commands, so that we don't need to bother searching the reference manual.
 In this view, we can see that the I²C packet was a command to read the date and time,
-which was then reported to be 10.03.2013 23:35:30. 
+which was then reported to be 10.03.2013 23:35:30.
 
-There are all kinds of stacked decoders available, but keep in mind that they're not
-shown in the decoder menu. Stacked decoders require a lower-level decoder first before
-they become stackable. Most of the time, they require either the UART, I²C or SPI decoder.
+In this example, we added the I²C and DS1307 decoders separately. However, when opening
+the decoder selector window, you can also double-click on the DS1307 decoder and PulseView
+will try to auto-resolve the dependencies needed to use this decoder. In case there are
+ambiguities (e.g. when several different protocol decoders offer 'uart' output), it will
+ask you to choose which one to use.
 
-You can check the https://sigrok.org/wiki/Protocol_decoders[List of Protocol Decoders]
-to see which protocol decoders have been created already.
+For a list of available and planned protocol decoders, you can https://sigrok.org/wiki/Protocol_decoders[check the wiki].
 
 === Using Decoders on Analog Signals
 
@@ -78,6 +79,42 @@ as you can now visually understand where the ranges for high and low are placed.
 Aside from the default conversion threshold(s), you can choose from a few common presets
 or enter custom values as well. They take the form "0.0V" and "0.0V/0.0V", respectively.
 
+=== Troubleshooting
+
+In case a protocol decoder doesn't provide the expected result, there are several things
+you can check.
+
+The first check you should perform is whether the time unit in the ruler
+is given as "sa". This is short for "samples" and means that the device didn't provide
+a sample rate and so PulseView has no way of showing a time scale in seconds or
+fractions thereof. While some decoders can run without timing information, or only
+optionally make use of the time scale, others may not be able to interpret the
+input data since timing information is an essential part of the very protocol.
+
+Another issue to remain aware of is that decoders need enough samples per protocol step
+to reliably interpret the information. In typical cases the minimum sample rate should
+be four to five times the rate of the fastest activity in the protocol.
+
+If a protocol decoder runs but shows you annotations that don't seem to make any sense,
+it's worth double-checking the decoder settings. One common source of error is the
+baud rate. For example, the CAN protocol decoder doesn't know what baud rate
+is used on the bus that you captured, so it could be that a different baud rate is used
+than the one you set. Also, if this is still not the reason for the malfunction, it's
+worth checking whether any of the signals have been captured inverted. Again using the
+CAN bus as an example, the decoder will decode the signal just fine if it's inverted but
+it'll show data even when the signal looks "idle".
+
+When a protocol decoder stops execution because of an unmet constraint (required input
+not connected, essential parameter not specified) or a bug in the decoder itself, you
+will be presented a static red message in the protocol decoder's display area.
+In that case, you check the log output in the settings menu. There you'll find the Python
+error description which you can use to either adjust the configuration,
+or debug the decoder (and let us know of the fix) or you can copy that information and
+file a bug report so that we can fix it.
+
+Further helpful knowledge and explanations on logic analyzers can be found in our
+https://sigrok.org/wiki/FAQ#Where_can_I_learn_more_about_logic_analyzers.3F["Learn about logic analyzers" FAQ item].
+
 === Exporting Annotations
 
 If you want to postprocess annotations that were generated by a protocol decoder, you