ProtoPirate v3.2 for Flipper Zero, with three protocols added on top of upstream plus a working Timing Tuner.
🌏 中文说明 / 免责声明：README.zh-CN.md
This is a modified fork, not upstream. Upstream ProtoPirate is maintained by The Pirates' Plunder (main repo: https://protopirate.net/ProtoPirate/ProtoPirate). Everything below marked fork addition is not their work. For the original app, protocol catalog, Discord and credits go upstream.
Read this before you clone, build or flash anything in this repository. 克隆、编译或烧录前请先读这一段。
- Technical research and education only. This repository exists to document and study the physical layer of automotive remote keyless entry (RKE) systems: modulation, frame structure, encoding, CRC and rolling-code behaviour. It is an amateur radio / security-research artefact. 本仓库仅供技术研究与学习:用于记录和分析汽车遥控钥匙(RKE)的物理层—— 调制方式、帧结构、编码、CRC 与滚动码行为。
- No legal responsibility is accepted. The maintainer of this fork accepts no liability whatsoever for any direct or indirect consequence of using, modifying, compiling, flashing or distributing anything here — including but not limited to damage to vehicles, immobiliser lockout, key desynchronisation, property loss, data loss, or any civil or criminal liability arising in any jurisdiction. You use it entirely at your own risk. 本 fork 不承担任何法律责任:对因使用、修改、编译、烧录或传播本仓库内容所导致的 任何直接或间接后果——包括但不限于车辆损坏、防盗系统锁死、钥匙失同步、财产损失、 数据丢失,以及在任何司法管辖区产生的民事或刑事责任——概不负责,使用风险自负。
- Lawful targets only. Use it exclusively on hardware you own, or on hardware you hold explicit written authorisation to test. Opening, replaying to, or interfering with a vehicle you do not own or are not authorised to test is illegal in most jurisdictions and is not a supported or intended use of this project. 仅限合法目标:只能用于自有设备,或你持有明确书面授权可测试的设备。 对非自有、未获授权的车辆进行开锁、重放或干扰,在绝大多数司法管辖区均属违法, 不属于本项目的支持范围或预期用途。
- Rolling codes are not broken here. Nothing in this repository defeats a rolling-code or challenge-response system. A captured frame is valid once; replaying it does not open a car a second time. Vehicles with smart-key / challenge-response entry (e.g. Range Rover L405/L460/L494, Evoque, Velar) are explicitly not coverable by this toolset. 本项目没有攻破滚动码:捕获帧只生效一次,重放无法二次开锁。智能钥匙/双向认证车型 (如 L405/L460/L494、Evoque、Velar)明确不在覆盖范围内。
- The author / upstream are not responsible for your actions. This is a security-research tool published openly, in the same spirit as the upstream project. Responsibility for how it is used rests with the user alone.
- No warranty. Provided "as is", without warranty of any kind. Some protocols in this fork are explicitly marked unverified against real hardware — see Verification status below. 无任何担保:按"现状"提供。本 fork 中部分协议已明确标注未经真机验证, 详见下方 Verification status。
Upstream's own position is the same: the app "is intended for educational and
security purposes only, and has no signal transmission enabled by default".
This fork does ship a TX-enabled build — install proto_pirate_rxonly.fap if you
want the upstream guarantee that it physically cannot transmit.
Upstream ProtoPirate is the work of The Pirates' Plunder. This repository is a modified copy; the original authors listed below are not responsible for the fork's additions (Nissan V0, Land Rover V1, Soueast V5, the Timing Tuner patch or the build tooling).
上游 ProtoPirate 由 The Pirates' Plunder 开发,本仓库只是其修改副本。 下列原作者不对本 fork 新增的内容(三个协议、Timing Tuner 补丁、构建工具链)负责。
- Upstream main repository / 上游主仓库: https://protopirate.net/ProtoPirate/ProtoPirate
- Upstream project notice / 上游项目公告: https://protopirate.net/ProtoPirate
- Community / 社区 (Discord): https://discord.gg/thepirates
RocketGod · MMX · Leeroy · gullradriel · Skorp (Weather App reuse) · Vadim's Radio Driver
L0rdDiakon · YougZ · RocketGod · MMX · DoobTheGoober · Skorp · Slackware · Trikk · Wootini · Li0ard · Leeroy · Ash
DoobTheGoober · MMX · NeedNotApply · RocketGod · Slackware · Trikk · Li0ard
| Addition | Files | Status |
|---|---|---|
| Nissan V0 — Nissan / Infiniti RKE | protocols/nissan_v0.{c,h}, protocols/plugins/nissan_v0_plugin* |
adaptive te, decode + encode |
| Land Rover V1 — Lucas 10AS era (Defender TD5, Freelander 1, Discovery 1/2, RR P38/Classic) | protocols/landrover_v1.{c,h} |
era-inferred, unverified against a real vehicle |
| Soueast V5 — 东南 V5 菱致, pre-2015 | protocols/soueast_v5.{c,h} |
public EV1527 fixed-code spec, decode + encode |
| Range Rover routing aliases | protocols/protocol_items.c |
routes Rover-branded signals into the right registry |
| Timing Tuner made usable | scenes/protopirate_scene_timing_tuner.c |
decoupled from decode — see below |
| PC-side capture analyzer + self-tests | tools/nissan_capture_analyze.py, tools/selftest_generate.py |
ratio-agnostic, validated on synthetic ground truth |
| TX / RX-only build split | defines.h, tools/build-both.{ps1,sh} |
see Two builds |
| File | Size | SHA256 | Transmission |
|---|---|---|---|
proto_pirate.fap |
515,152 B | 95e363c04a66737d1d84fb36f7393d548bec8167826bc1eb838ca99fb3d82491 |
TX enabled (26 TX markers + emulate scene) |
proto_pirate_rxonly.fap |
309,204 B | e030381c76e2b2740ffccfede7cdd224e169f337b30a60420fe9c986ba9c4614 |
no TX path at all |
Both install to the same place, so install only one.
⚠ Before troubleshooting "it reads the signal but nothing happens"
Check which build you installed.
proto_pirate_rxonly.faphasENABLE_EMULATE_FEATUREundefined, soufbtnever compiles aprotopirate_tx_*plugin nor the emulate scene. Verified by scanning the packed.fap: 0 TX plugin markers. It can receive and decode, and it cannot transmit at all — pressing Send/Emulate does nothing.If you want to replay, install
proto_pirate.fap.
Requirements: ufbt on PATH
(pip install ufbt), Python 3.8+.
# quick build, default TX-enabled variant
ufbt
# both variants at once (RX-only then full, artifacts into build-out/)
bash tools/build-both.sh # Linux / macOS / WSL
pwsh tools/build-both.ps1 # Windows PowerShell
ufbt launch # build + flash to a connected Flippertools/build-both.* toggles ENABLE_EMULATE_FEATURE in defines.h and leaves it
back in the TX-enabled default state when it finishes. CI builds both variants on
every push; see the Actions tab for downloadable artifacts.
The build also emits the protocol plugins (dist/protopirate_*_plugin.fal).
They belong in the same folder on the Flipper as the main .fap.
Copy proto_pirate.fap (or the RX-only one) plus every
dist/protopirate_*_plugin.fal to:
SD Card/apps/Sub-GHz/proto_pirate/
The Sub-GHz keystore files under keystore/ are runtime assets loaded from the
SD card, not compiled into the app. Copy them to the card as well:
SD Card/apps_assets/proto_pirate/keystore/
Without them the Kia V3/V4/V5/V6 encoder paths that need a keystore entry
(KIA_KEY1, KIA_KEY4, the AES keystore pair) will refuse to encode.
Open ProtoPirate → Receiver and press the fob.
| What you see | Meaning |
|---|---|
| A protocol name appears in the list | It decoded. The problem is on the transmit side. |
| RSSI moves but the list stays empty | It did not decode. |
RSSI activity alone is weak evidence — RSSI moves for any strong signal, including noise and the car's own systems. A decode is the real signal.
Almost certainly a rolling code. A captured frame is valid once, and replaying it does not open the car a second time. This is inherent to the system, not a bug in the app or in the build. Nothing in this toolchain changes that.
The preset decides which registry gets loaded, which decides which protocols are even available:
| Preset family | Registry loaded | Land Rover entries reachable |
|---|---|---|
AM650, AM270 |
AM registry | Land Rover V1 (classic / P38 era) |
FM238, FM476, FSK presets |
FM registries | Land Rover V0 → Honda V2 (Ford era) |
preset name containing F4 |
FM F4 registry | Land Rover V0 → Honda V2 |
Try both. If your car is FSK and the Flipper sits on AM650 it will never
decode, no matter which protocols were added. Open
Receiver → Config → Preset and cycle through AM650, AM270, FM476, FM238.
ProtoPirate → Timing Tuner → press OK ("Analyse")
The stock scene could only show timings after a protocol had already decoded, which made it useless for exactly this case. That is patched:
- The raw pulse train is buffered continuously while listening.
- OK / "Analyse" now computes statistics from whatever has been captured, matched or not.
- With no protocol reference it derives the short/long split adaptively from the capture instead of the old hardcoded 400 / 100–1200 window (which silently discarded anything outside it).
- Scroll with Up/Down. OK again restarts the capture.
Read these lines:
| Line | What it tells you |
|---|---|
Short Avg |
the fob's base time te, in µs |
Long Avg |
the wide pulse |
Ratio: x.xx : 1 |
which chip family — ~2:1 is complementary PWM (Nissan / Land Rover), ~3:1 is EV1527-family fixed code (Soueast) |
Short Jitter / Long Jitter |
if these are huge, the signal is noisy or you were on the wrong modulation |
If the counters stay at 0 samples, the radio is not seeing a decodable pulse train at all — that points at the wrong frequency or the wrong modulation, not a missing protocol.
The on-device numbers are a guide. For the full picture, capture raw and analyse on a PC:
- Flipper: Sub-GHz → Read Raw, press the fob several times, save the
.sub. -
python tools/nissan_capture_analyze.py your_capture.sub
This reports frequency, preset (AM vs FSK), measured te, the wide/narrow
ratio, the repeat period, the recovered payload, and whether it is static
(replayable) or rolling (not replayable).
| Protocol | Coverage | Basis |
|---|---|---|
Nissan V0 |
Nissan / Infiniti RKE, 315 / 433.92 MHz, AM/OOK | reverse-engineered family; adaptive te |
Land Rover V1 |
Lucas 10AS era: Defender TD5, Freelander 1, Discovery 1-2, RR P38/Classic | era-inferred, unverified; adaptive te, band 280–900 µs |
Land Rover V0 |
Ford era: L322, RR Sport L320, Freelander 2, Discovery 3-4 | upstream, maps to Honda V2 (FM/FSK) |
Soueast V5 |
东南 V5 菱致, pre-2015 | public EV1527 spec, 24-bit fixed code, 1:3 ratio |
| — | L405 / L460 / L494 / Evoque / Velar | smart key; not coverable |
No immobiliser chip (无芯片), no PIN (免密码), manual in-car learn. That is a
fixed/learning-code system: the code never changes, so a captured frame replays
indefinitely and there is no counter to desynchronise the original with.
In-car learn procedure (cross-confirmed by two key-matching sources):
- Driver door open. Within 5 s turn ignition OFF→ON three times, leave at ON. Indicators stay lit → learn mode.
- Press any button on the first remote. Indicators flash 3× → learned.
- Press any button on the second remote. Indicators flash 3× → learned.
- Optionally a third, then the system exits automatically.
- Every step must complete within 10 s.
⚠ Learning the first remote erases every previously learned remote (at most three are stored). To keep your original working, enter learn mode once and press the original AND the new remote in that same session.
Paste the analyzer's #define block into the matching protocol header, then run
tools/build-both.sh (or pwsh tools/build-both.ps1).
The analyzer is ratio-agnostic. Validated against synthetic captures with known ground truth:
| Case | Detected te | Wide ratio | Period | Recovered payload |
|---|---|---|---|---|
| 1:2 PWM | 250 | 2.00× | 81 | 0x1234567890ABCDEF bit-exact |
| 1:3 EV1527 | 400 | 3.00× | 25 | 0x0ABCDEF bit-exact |
Regenerate those fixtures with python tools/selftest_generate.py.
ufbtclean rebuild of both variants,-Werrorclean.- Full build: 26 TX markers, emulate scene present.
- RX-only build: 0 TX markers, no emulate scene.
- Timing Tuner patch present in both (
Analyse,Ratio:strings in the packed plugin; size 18,032 → 18,860 B). soueast_v5_protocol/landrover_v1_protocoland their decoder symbols present inprotopirate_am_plugin.fal.
Not verified: decode of any real vehicle. Use steps 1–5 above.
ProtoPirate is an experimental rolling-code analysis toolkit. It supports
decoding for multiple automotive key-fob families (Kia, Ford, Subaru, Suzuki,
VW, and more), with the goal of being a drop-in Flipper app (.fap) that is
free, open source, and usable on any Flipper Zero firmware.
The app is intended for educational and security purposes only, and upstream
ships with no signal transmission enabled by default. This fork does ship a
TX-enabled build — install proto_pirate_rxonly.fap instead if you want the
upstream guarantee that it physically cannot desynchronise a rolling-code fob.
| Protocol | Decoder | Encoder | Signal Encoding | Modulation | Encryption | CRC | Frequency |
|---|---|---|---|---|---|---|---|
| Chrysler V0 | ✅ | ✅ | PWM | AM650 | Rolling Code | Checksum | 315.00 / 433.92 |
| Fiat V0 | ✅ | ✅ | Manchester | AM650 | Rolling Code (static emu only) | ❌ | 315.00 / 433.92 |
| Fiat V1 | ✅ | ✅ | Manchester | AM650 | HITAG2 | XOR8 | 315.00 / 433.92 |
| Fiat V2 | ✅ | ❌ | Manchester | AM650 | Rolling Code | ❌ | 315.00 / 433.92 |
| Ford V0 | ✅ | ✅ | Manchester | AM650 | Rolling Code | ✅ + Checksum | 315.00 / 433.92 |
| Ford V3 | ✅ | ❌ | Manchester | AM650 | Rolling Code | ❌ | 434.25 |
| Honda V1 | ✅ | ✅ | Manchester | AM650 | Rolling Code | CRC4 | 315.00 / 433.92 |
| Kia V1 | ✅ | ✅ | Manchester | AM650 | Rolling Code | CRC4 | 315.00 / 433.92 |
| Mazda V0 | ✅ | ✅ | Manchester | AM650 | Rolling Code | Checksum | 315.00 / 433.92 |
| Porsche Touareg | ✅ | ❌ | PWM | AM650 | Rolling Code | ❌ | 315.00 / 433.92 |
| PSA (Peugeot/Citroen) | ✅ | ✅ | Manchester | AM650 | XTEA/XOR | CRC8 | 315.00 / 433.92 |
| Renault V0 | ✅ | ✅ | Manchester | AM650 | Rolling Code / Replay | Type/IC | 315.00 / 433.92 |
| StarLine | ✅ | ✅ | PWM | AM650 | KeeLoq | ❌ | 315.00 / 433.92 |
| Subaru | ✅ | ✅ | PPM | AM650 | Rolling Code | ❌ | 315.00 / 433.92 |
| VAG (VW/Audi/Seat/Skoda) | ✅ | ✅ | Manchester | AM650 | AUT64/XTEA | ❌ | 434.42 |
| Protocol | Decoder | Encoder | Signal Encoding | Modulation | Encryption | CRC | Frequency |
|---|---|---|---|---|---|---|---|
| Ford V1 | ✅ | ✅ | Manchester | F4 | Rolling Code | CRC16 | 315.00 / 433.92 |
| Ford V2 | ✅ | ✅ | Manchester | F4 | Rolling Code (simple replay) | ❌ | 434.25 |
| Ford V3 | ✅ | ❌ | Manchester | F4 | Rolling Code | ❌ | 434.25 |
| Honda Static | ✅ | ✅ | PWM | Honda1 | Static Code | Checksum | 315.00 / 433.92 |
| Kia V0 / Suzuki V0 / Honda V0 | ✅ | ✅ | PWM | FM476 | Rolling Code | CRC8 | 315.00 / 433.92 |
| Kia V2 | ✅ | ✅ | Manchester | FM476 | Rolling Code | CRC4 | 315.00 / 433.92 |
| Kia V3 / V4 | ✅ | ✅ | PWM | FM476 | KeeLoq | CRC4 (BF) | 315.00 / 433.92 |
| Kia V5 | ✅ | ✅ | PWM | FM476 | Rolling Code | ✅ | 315.00 / 433.92 |
| Kia V6 | ✅ | ✅ | Manchester | FM476 | AES128 | CRC8 | 315.00 / 433.92 |
| Kia V7 | ✅ | ✅ | Manchester | FM476 | Rolling Code | CRC8 | 315.00 / 433.92 |
| Honda V2 | ✅ | ✅ | PWM | F4 | Rolling Code | Check+Tail | 315.00 / 433.92 |
| Mazda V0 | ✅ | ✅ | Manchester | FM (F2?) | Rolling Code | Checksum | 315.00 / 433.92 |
| Mitsubishi V0 | ✅ | ❌ | PWM | FM476 | Rolling Code | ❌ | 315.00 / 433.92 |
| PSA (Peugeot/Citroen) | ✅ | ✅ | Manchester | FM (F3?) | XTEA/XOR | CRC8 | 315.00 / 433.92 |
| Scher-Khan | ✅ | ❌ | PWM | FM | Magic Code | ❌ | 315.00 / 433.92 |
- 📡 Protocol Receiver — real-time capture and decoding with an animated radar display, frequency hopping supported.
- 📂 Sub Decode — load and analyse existing
.subfiles from/ext/subghz/. - ⏱️ Timing Tuner — compare real fob timing against protocol definitions (patched in this fork, see Step 4 above).
Upstream ProtoPirate is built by The Pirates' Plunder. See the Credits — 原作者与致谢 section near the top of this file for the full author list and upstream links.
GPL-3.0 — see LICENSE. This fork is distributed under the same
terms as upstream.
Because this is a modified version of a GPL-3.0 program, the modifications above
are licensed under GPL-3.0 as well, the original copyright notices are retained,
and this repository is clearly marked as a modified copy rather than the
original. The complete corresponding source for everything shipped as a binary
is in this repository, and tools/build-both.sh rebuilds both released .fap
variants from this tree.
Intended use: security research on hardware you own or are explicitly authorised to test. Rolling-code replay does not open a car whose fob you do not already have, and the RX-only build cannot transmit at all. See the full Disclaimer & intended use section at the top of this file — this fork is provided as-is, with no warranty and no accepted liability.