protocol work

2026-02-18 21:24:34 -05:00
parent 05078ba961
commit 8ef3b98634
5 changed files with 127 additions and 393 deletions
@@ -1,20 +1,94 @@
-# Scripts
+# KAT scripts

-## analyze_sub_vag.py
+## demod_sub_to_bits.py

-Analyzes a Flipper `.sub` file against the VAG decoder logic in `src/protocols/vag.rs` to see why a signal does not decode as VAG (or even appear as Unknown).
+Demodulate Flipper SubGhz RAW `.sub` files into a stream of `1` and `0` bits using duration-based on-off keying (OOK). The script parses level+duration pulses, classifies each as **short** or **long** against configurable timing, then outputs bits according to the chosen encoding.
+
+### Input format
+
+The script reads Flipper-style `.sub` files:
+
+- **RAW_Data:** space-separated signed integers (one per pulse).
+- **Positive value** = HIGH level, **negative** = LOW; **magnitude** = duration in microseconds.
+- Optional **Frequency:** line (Hz). If missing, 433 920 000 is assumed.
+
+Same convention as KAT’s `.sub` import and ProtoPirate’s raw file reader.
+
+### Encoding modes
+
+| Mode         | Description |
+|-------------|-------------|
+| **pwm**     | One bit per pulse: short duration → `0`, long duration → `1`. Unmatched durations are skipped. Default. |
+| **manchester** | Short/long pulses fed into a Manchester state machine (Ford V0–style). Outputs decoded data bits. Long gaps reset state. |
+| **raw**     | No duration decoding: one character per pulse, `1` = HIGH, `0` = LOW. |
+
+### Timing parameters
+
+Pulses are classified using nominal short/long durations and a tolerance:
+
+- **--te-short** — Nominal short duration (µs). Default: 250.
+- **--te-long**  — Nominal long duration (µs). Default: 500.
+- **--te-delta** — Tolerance (µs): a pulse is “short” if `|duration - te_short| ≤ te_delta`, “long” if `|duration - te_long| ≤ te_delta`. Default: 100.
+
+Examples:
+
+- Ford V0–style: `--te-short 250 --te-long 500 --te-delta 100`
+- VAG/VW 500 µs: `--te-short 500 --te-long 1000 --te-delta 120`
+
+### Usage

-**Usage:**
 ```bash
-python scripts/analyze_sub_vag.py path/to/file.sub
-python scripts/analyze_sub_vag.py "IMPORTS/VOLKSWAGEN AUDI/Test_55_unlock_and_55_lock_suran.sub"
+# PWM decode (short→0, long→1), default 250/500 µs
+python3 scripts/demod_sub_to_bits.py path/to/file.sub
+
+# PWM with VAG-like timing
+python3 scripts/demod_sub_to_bits.py path/to/file.sub --te-short 500 --te-long 1000 --te-delta 120
+
+# Manchester decode (e.g. Ford)
+python3 scripts/demod_sub_to_bits.py path/to/file.sub --encoding manchester --te-short 250 --te-long 500
+
+# Wrap output to 80 characters per line
+python3 scripts/demod_sub_to_bits.py path/to/file.sub --encoding pwm --wrap 80
+
+# Only decode HIGH pulses (or --pulse-level low)
+python3 scripts/demod_sub_to_bits.py path/to/file.sub --encoding pwm --pulse-level high
+
+# Raw level stream (no duration decoding)
+python3 scripts/demod_sub_to_bits.py path/to/file.sub --encoding raw
+
+# Print level:duration for each pulse (no bits)
+python3 scripts/demod_sub_to_bits.py path/to/file.sub --with-durations
 ```

-**What it does:**
- Parses the .sub file (Frequency + RAW_Data: positive = HIGH, negative = LOW, duration in µs).
- Checks whether the file frequency is within VAG’s supported range (433.92 / 434.42 MHz, 2% tolerance as in KAT).
- Simulates the VAG decoder’s **Reset** step: the first HIGH pulse must be 300±79 µs (Type 1/2) or 500±79 µs (Type 3/4). Reports the first few pulses and why they pass or fail.
- Scans the full stream for the first HIGH pulse that matches 300±79 or 500±79 (VAG-like preamble), for both normal and inverted polarity.
+### Options summary

-**Why a file might not show up at all:**  
-KAT only creates a capture (including “Unknown”) when some decoder returns a result. The VAG decoder only leaves the Reset state when it sees a HIGH pulse of 300±79 or 500±79 µs. If the stream starts with other data (e.g. 133 µs HIGH), the decoder never leaves Reset and never emits a decode, so no capture is created for that stream.
+| Option | Default | Description |
+|--------|---------|-------------|
+| `--encoding` | pwm | `raw`, `pwm`, or `manchester` |
+| `--te-short` | 250 | Nominal short pulse (µs) |
+| `--te-long` | 500 | Nominal long pulse (µs) |
+| `--te-delta` | 100 | Timing tolerance (µs) |
+| `--pulse-level` | both | For PWM: `high`, `low`, or `both` |
+| `--gap-us` | 10000 | Manchester: gap (µs) that resets state |
+| `--wrap` | 0 | Wrap bit string every N characters (0 = no wrap) |
+| `--with-durations` | off | Print `level:duration` instead of bits |
+
+### Output
+
+- Decoded bit string is printed to **stdout** (e.g. `1011001...` or wrapped lines).
+- A single comment line (pulse count, frequency, encoding, timing) is printed to **stderr**.
+
+### Requirements
+
+- Python 3.9+ (for `list[tuple[...]]` type hints; can be relaxed if needed).
+- No extra dependencies; uses only the standard library.
+
+### Inspecting raw pulses (e.g. for VAG)
+
+To see the first pulses of a `.sub` file (level and duration in µs) without decoding:
+
+```bash
+python3 scripts/demod_sub_to_bits.py path/to/file.sub --encoding raw --with-durations
+```
+
+VAG Type 3/4 expects: first pulse **HIGH** ~500 µs, then LOW ~500 µs, repeated (preamble); after ≥41 such pairs, HIGH ~1000 µs then LOW ~500 µs (sync), then 3×750 µs, then data. If the first pulse is LOW or durations are outside 500±79/80, the decoder will not lock.