document the decoder in its head comment, somewhat, at least

diff --git a/parport/nmra-decode.pl b/parport/nmra-decode.pl
index 82fc5e44c6a6cb5a229671830651100d97ec0716..e38941f547419a114713dec4d9214e022ce5fd3e 100755 (executable)
--- a/parport/nmra-decode.pl
+++ b/parport/nmra-decode.pl
@@ -2,6 +2,38 @@
 #
 # Feed this the output from readlots
 
+# Note that the interval length determination is known to be slightly
+# buggy at least under certain adverse conditions.
+
+# Output format:
+#                                      ,value during interval
+#                                     / ,classification chars
+# @<1105296455.621813     55..59     5e S-=    1  I112 
+# ^interval ends just before  \     decoded bit'  `interpretation
+#                              `computed min and maxlength
+# Classification chars
+#    S  short interval
+#    L  long interval
+#    U  interval might have been short or long but we don't know
+#   (interval is short iff actual length < 80)
+# followed by two chars which classify the measurement error etc.
+# first the min length is classified
+#    <  too short for NMRA decoder spec for interval (as classified)
+#    -  decoder must decode but power station may not produce, too short
+#    =  in spec
+#    +  decoder must decode but power station may not produce, too long
+#    >  too long for NMRA decoder spec for interval (as classified)
+# then the max length, just the same way.
+#
+# interpretations
+#      Innn                idle/preamble bit, number nnn
+#      F <bytes>...        framing bit indicates more data
+#                            <bytes> is those already received
+#      B <bytes>(<bitno>)  data bit no <bitno>
+#                            <bytes> includes byte under construction
+#      P <bytes>           packet end bit of good packet, <bytes> includes csum
+#      EP (<error msg>)    framing/decoding error
+
 use strict qw(vars refs);
 use IO::Handle;
 
@@ -51,7 +83,8 @@ sub found_bit ($) {
                $checksum ^= hex $byte;
            }
            if ($checksum) {
-               packet_decoder_error("csum $checksum, @bytes");
+               $checksum= sprintf '%02x', $checksum;
+               packet_decoder_error("csum err $checksum in @bytes");
                return;
            }
            print "P @bytes\n";
@@ -59,8 +92,8 @@ sub found_bit ($) {
            return;
        }
        $bitnum= 7;
-       push @bytes, 0;
        print "F @bytes...\n";
+       push @bytes, '00';
        return;
     }
     $b= hex $bytes[$#bytes];