KaraZajac
95 lines
3.9 KiB
Markdown
95 lines
3.9 KiB
Markdown
# KAT scripts
|
||
|
||
## demod_sub_to_bits.py
|
||
|
||
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
|
||
|
||
```bash
|
||
# 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
|
||
```
|
||
|
||
### Options summary
|
||
|
||
| 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.
|