X-Git-Url: https://sigrok.org/gitweb/?p=libsigrokdecode.git;a=blobdiff_plain;f=decoders%2Fonewire_link%2F__init__.py;h=cb0347170958b385212fa5960d13bda3f844d234;hp=6eaeadd047aecb68a781a34feae28f350bb5541a;hb=e7720d6c73eb981e57753c9028fa3e9019676c50;hpb=99f5f3b5ac31347795582872a5d92f3d9430c21d

diff --git a/decoders/onewire_link/__init__.py b/decoders/onewire_link/__init__.py
index 6eaeadd..cb03471 100644
--- a/decoders/onewire_link/__init__.py
+++ b/decoders/onewire_link/__init__.py
@@ -19,58 +19,73 @@
 ##
 
 '''
-1-Wire protocol decoder.
+1-Wire protocol decoder (link layer).
 
-The 1-Wire protocol enables bidirectional communication over a single wire (and
-ground) between a single master and one or multiple slaves. The protocol is
-layered, the provided parser decodes the next layers:
-- Link layer (reset, presence detection, reading/writing bits)
-- Network layer (skip, search, match device ROM addresses)
-The higher layers (transport, presentation) are not decoded, since they are
-mostly device specific and it would take a lot of code to interpret them.
+The 1-Wire protocol enables bidirectional communication over a single wire
+(and ground) between a single master and one or multiple slaves. The protocol
+is layered:
+
+ - Link layer (reset, presence detection, reading/writing bits)
+ - Network layer (skip/search/match device ROM addresses)
+ - Transport layer (transport data between 1-Wire master and device)
+
+Link layer protocol details:
 
 Sample rate:
-A high enough sample rate is required to properly detect all the elements of
-the protocol. A lower sample rate can be used if the master does not use
-overdrive communication speed. The next minimal values should be used:
-- overdrive     available:   2MHz minimum, 5MHz suggested
-- overdrive not available: 400kHz minimum, 1MHz suggested
+A sufficiently high samplerate is required to properly detect all the elements
+of the protocol. A lower samplerate can be used if the master does not use
+overdrive communication speed. The following minimal values should be used:
+
+ - overdrive available: 2MHz minimum, 5MHz suggested
+ - overdrive not available: 400kHz minimum, 1MHz suggested
 
 Probes:
 1-Wire requires a single signal, but some master implementations might have a
-separate signal use to deliver power to the bus during temperature conversion
-as an example. This power signal is currently not parsed.
-- owr (1-Wire bus)
-- pwr (1-Wire power)
+separate signal used to deliver power to the bus during temperature conversion
+as an example. This power signal is currently not used.
+
+ - owr (1-Wire signal line)
+ - pwr (optional, dedicated power supply pin)
 
 Options:
-1-Wire is an asynchronous protocol, so the decoder must know the sample rate.
-The timing for sampling bits, presence and reset is calculated by the decoder,
+1-Wire is an asynchronous protocol, so the decoder must know the samplerate.
+The timing for sampling bits, presence, and reset is calculated by the decoder,
 but in case the user wishes to use different values, it is possible to
-configure the next timing values (number of sample rate periods):
-- overdrive              (if active the decoder will be prepared for overdrive)
-- cnt_normal_bit         (time for normal mode sample bit)
-- cnt_normal_presence    (time for normal mode sample presence)
-- cnt_normal_reset       (time for normal mode reset)
-- cnt_overdrive_bit      (time for overdrive mode sample bit)
-- cnt_overdrive_presence (time for overdrive mode sample presence)
-- cnt_overdrive_reset    (time for overdrive mode reset)
-This options should be configured only on very rare cases and the user should
+configure the following timing values (number of samplerate periods):
+
+ - overdrive              (if active the decoder will be prepared for overdrive)
+ - cnt_normal_bit         (time for normal mode sample bit)
+ - cnt_normal_slot        (time for normal mode data slot)
+ - cnt_normal_presence    (time for normal mode sample presence)
+ - cnt_normal_reset       (time for normal mode reset)
+ - cnt_overdrive_bit      (time for overdrive mode sample bit)
+ - cnt_overdrive_slot     (time for overdrive mode data slot)
+ - cnt_overdrive_presence (time for overdrive mode sample presence)
+ - cnt_overdrive_reset    (time for overdrive mode reset)
+
+These options should be configured only on very rare cases and the user should
 read the decoder source code to understand them correctly.
 
+Protocol output format:
+TODO.
+
 Annotations:
-Annotations can be shown for each layer of the protocol separately:
-- link (the value of each transmitted bit is shown separately)
-- network (the ROM command, and address are shown)
-- transport (only transport layer byte transfers are shown)
-If link layer annotations are shown, possible issues with sample rate and sample
-timing are also shown.
+
+Link layer annotations show the following events:
+
+ - NOTE/WARNING/ERROR
+   Possible samplerate related timing issues are reported.
+ - Reset/presence true/false
+   The event is marked from the signal negative edge to the end of the reset
+   high period. It's also reported if there are any devices attached to the bus.
+ - Bit 0/1
+   The event is marked from the signal negative edge to the end of the data
+   slot. The value of each received bit is also provided.
 
 TODO:
-- add CRC checks for network layer
-- add transport layer code
-- review link layer code, to check for protocol correctness
-- define output protocol
+- Check for protocol correctness, if events are timed inside prescribed limits.
+- Maybe add support for interrupts, check if this feature is deprecated.
 '''
 
-from .onewire_link    import *
+from .onewire_link import *
+