From fb70399a65e4a82476990679184605cccd72311a Mon Sep 17 00:00:00 2001
From: Dominik Bay <eimann@etherkiller.de>
Date: Thu, 16 Apr 2026 07:35:03 +0200
Subject: [PATCH] [parser] --harder: explicit accuracy hint and expanded help
 text

Without --harder the BCH gate on downlink bursts is strict enough that
a large fraction of otherwise-decodable LCW traffic falls through to
RAW. Users who don't know about --harder end up with RAW buckets that
look like a real parser gap rather than a missing flag.

Changes:

- Rewrite the --harder argparse help text with concrete impact
  ("move 15-25%% of RAW into IRI/IBC/IIU/etc.") instead of the generic
  "try harder to parse input".
- Track RAW output count in stats and, at the end of a --stats run,
  print a one-line stderr NOTE when --harder is off, no line filter is
  set, and RAW fraction is at least 15% over 1000+ output frames.
- Expand the --harder section in README.md with the same detail plus
  a note that stats comparisons across captures only make sense when
  both sides use the same flag.

No behaviour change for existing pipelines; the hint is strictly
additive on stderr at run end.
---
 README.md         |  4 +++-
 iridium-parser.py | 20 +++++++++++++++++++-
 2 files changed, 22 insertions(+), 2 deletions(-)

diff --git a/README.md b/README.md
index 4ed48af..42144b0 100644
--- a/README.md
+++ b/README.md
@@ -91,7 +91,9 @@ Enable error correction in the uniq word. Increases processing time.
 
 ##### --harder
 
-Try to decode packets with correctable bit errors at the beginning. Significantly increases processing time.
+Relax the BCH gate so bursts with 1-2 correctable bit errors in the header get decoded instead of falling through to `RAW`. In practice this recovers a large fraction of downlink LCW traffic: on typical multi-hour captures 15-25% of the RAW bucket moves into `IRI`, `IBC`, `IIU`, `IME`, `ITL`, `IRA`, and `LW` (individual channels can see 3x more hits than without `--harder`). Stats comparisons between captures are only meaningful when both sides use the same setting.
+
+Significantly increases processing time. The parser prints a one-line hint on stderr at the end of the run when `--harder` is off and the RAW fraction looks inflated.
 
 ##### --disable-freqclass
 
diff --git a/iridium-parser.py b/iridium-parser.py
index 3550907..e2d1b4c 100755
--- a/iridium-parser.py
+++ b/iridium-parser.py
@@ -50,7 +50,7 @@ def __call__(self, parser, ns, values, option):
 parser.add_argument("--uw-ec",             action="store_true", dest='uwec',
                     help="enable error correction on unique word")
 parser.add_argument("--harder",            action="store_true",
-                    help="try harder to parse input")
+                    help="relax BCH gate - recover bursts with correctable bit errors (otherwise lost to RAW). Slower, but can move 15-25%% of RAW into IRI/IBC/IIU/etc.")
 parser.add_argument("--disable-freqclass", action="store_false", dest='freqclass',
                     help="turn frequency classificiation off")
 parser.add_argument("-s", "--satclass",    action="store_true", dest='dosatclass',
@@ -337,6 +337,10 @@ def perline(q):
         return
     if args.do_stats:
         stats["out"]+=1
+        # bursts that never upgraded to a known msgtype print as "RAW:"; track
+        # them so we can hint at --harder when the fraction looks inflated.
+        if type(q).__name__ == 'Message':
+            stats["raw"]+=1
     if args.output == "err":
         if q.error:
             selected.append(q)
@@ -408,6 +412,7 @@ def bitdiff(a, b):
     stats['start']=time.time()
     stats['in']=0
     stats['out']=0
+    stats['raw']=0
     stats['stop']= Event()
     sthread = Thread(target = stats_thread, args = [stats], daemon= True, name= 'stats')
     sthread.start()
@@ -423,6 +428,19 @@ def bitdiff(a, b):
     stats['stop'].set()
     sthread.join()
 
+    # Accuracy hint: many bursts that end up as RAW are actually decodable
+    # DL frames that hit the strict BCH gate with 1-2 bit errors. --harder
+    # relaxes that gate and recovers them as IRI/IBC/IIU/etc. Only hint on
+    # unfiltered runs where the signal is clear, and only once per run.
+    if (not args.harder
+            and args.linefilter['type'] == 'All'
+            and stats['out'] >= 1000
+            and stats['raw'] / stats['out'] >= 0.15):
+        raw_pct = 100.0 * stats['raw'] / stats['out']
+        print("NOTE: %.0f%% of output frames are RAW. Try --harder to recover "
+              "LCW-shaped bursts (expect 15-25%% of RAW to move into IRI/IBC/"
+              "IIU/etc.)." % raw_pct, file=sys.stderr)
+
 if args.output=='zmq':
     socket.close()
     context.term()