add comments

README.md

@@ -99,6 +99,8 @@ identical datagrams, where each has been decoded by its own methods. If you real
 rtl_wmbus with "-r 0" or "-t 0" argument to prevent executing of run length or time2 method respectively.
 You can play with arguments and check which method performs better for you. Please note, that both methods are active by default.
 
+The advantage of the run length algorithm is that it works without IIR filter (which are needed only for clock recovery by time2 method). Therefore the run length algorithm can be applied to all RF ICs providing raw _demodulated_ signal without clock in the "transparent serial mode" like TI CC1125 (swru295e.pdf, 8.7.2) does.
+
 An additional method introduces more calculation steps, so I'm not sure if Raspberry Pi 1 will still work with that.
 
 Run length algorithm works well with a few mode C1 devices I had around me, but can still be improved with your help.

rtl_wmbus.c

@@ -90,10 +90,12 @@ static const uint8_t deglitch_filter_t1_c1[128] =
     1,1,1,1,1,1,1,1
 };
 
-
+/* 1) Force the filter to put more ones than zeros on the output.
+   2) Zeros surrounded by ones are ones and vice versa.
+*/
 static const uint8_t deglitch_filter_s1[16] = {
    // 0000 0001 0010 0011 0100 0101 0110 0111
-         0,   1,   0,   1,   1,   1,   1,   1,
+         0,   1,   0,   1,   0,   1,   1,   1,
     // 1000 1001 1010 1011 1100 1101 1110 1111
          0,   1,   1,   1,   1,   1,   1,   1
 };
@@ -479,14 +481,20 @@ static void runlength_algorithm_s1(unsigned raw_bit, unsigned rssi, struct runle
 
     const unsigned state = deglitch_filter_s1[algo->raw_bitstream & 0xFu];
 
+    // Edge detector.
     if (algo->state == state)
     {
         algo->run_length++;
     }
     else
     {
+        // Get the current bit length expressed in samples as an
+        // average of two preceeding symbols.
         const int samples_per_bit = (algo->samples_per_bit[0] + algo->samples_per_bit[1]) / 2;
-        if (samples_per_bit <= 24/2)
+
+        // Reset the state machine if the current bit length (in samples)
+        // is less than 0.5 or more than 1.5 of the ideal symbol length.
+        if (samples_per_bit <= 24/2 || samples_per_bit >= (24+24/2))
         {
             runlength_algorithm_reset_s1(algo);
             algo->state = state;
@@ -494,6 +502,8 @@ static void runlength_algorithm_s1(unsigned raw_bit, unsigned rssi, struct runle
             return;
         }
 
+        // Reset the state machine if the sequence of ones (or zeros)
+        // is less than 0.5 symbol length that we assume.
         const int half_bit_length = samples_per_bit/2;
         const int run_length = algo->run_length;
         if (run_length <= half_bit_length)
@@ -560,6 +570,7 @@ static void runlength_algorithm_t1_c1(unsigned raw_bit, unsigned rssi, struct ru
 
     const unsigned state = deglitch_filter_t1_c1[algo->raw_bitstream & 0x3Fu];
 
+    // Edge detector.
     if (algo->state == state)
     {
         algo->run_length++;