KAT/scripts/README.md

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

# 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:

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.