Add documentation

receiver-dump.py

@@ -13,6 +13,7 @@
 import sys
 import time
 
+TIMING_OFFSET = 0x20
 
 jitterString0x0f = [
 # 0123456789abcdef
@@ -111,21 +112,24 @@ def dump(port):
  try: 
  value = int(numString, 10)
  except ValueError:
- value = 0x20
+ continue
 
- value -= 0x20 # Remove to 0x20 offset we added in the transmitter
+ # Remove the offset we added in the transmitter to ensure the minimum
+ # pulse does not go down to zero.
+ value -= TIMING_OFFSET
 
+ # Show the jitter diagram (lower 4 bits)
  jitter = value & 0xf
  print jitterString0x0f[jitter],
  print "0x%03x" % (value, ),
 
- if value == 0:
- print "0######", 
- elif abs(oldValue - value) <= 4:
+ if abs(oldValue - value) <= 4:
+ # Same value as previous reading (+/- jitter): treat it as "good"
  largeChange = False
  oldValue = value
  print " ",
 
+ # Calculate a rolling average of the last n sync pulses
  if value > 0x880: 
  diffs.pop(0)
  diffs.append(value)
@@ -140,25 +144,42 @@ def dump(port):
  processValue(value)
 
  elif abs(oldValue - value) > 0x100:
+ # A change > 0x100 means we have gone from one payload value to the 
+ # next. We have to wait for a second reading before we can 
+ # process the new value, because we may deal with a glitch at the 
+ # same time as data changes.
+
+ # If there are two consecutive large values it means we have only
+ # one reading of the previous value, which we can not rely on since
+ # it may have been a glitch. But at least we know exactly which
+ # payload value is affected.
  if largeChange:
  print "c*****", 
  else: 
  print "c ", 
  largeChange = True
+ oldValue = value
+
+ # If the value is a sync pulse we process always as we don't care
+ # about the absolute value of the sync pulse, so a potential glitch
+ # does not matter.
  if value > 0x880:
  print " ",
  processValue(value)
- oldValue = value
 
  else:
+ # A change larger than the jitter range means we are dealing with
+ # a glitch. Since the glitch is always longer (because the glitch
+ # is caused by the program execution being interrupted by an
+ # interrupt routine), we use the smaller of the adjacent values.
  largeChange = False
  if (oldValue < value):
  value = oldValue
  print "G>>>>>",
 
  print " ",
- processValue(value)
  oldValue = value
+ processValue(value)
 
  print