iohc-flipper: Instructions file for Claude Code

CLAUDE.md — iohc-flipper

Context for future Claude Code sessions in this project. Read once at session start. Cross-reference with PROGRESS.md for the full historical trail.

What this is

A Flipper Zero FAP that speaks io-homecontrol (868 MHz, Velux + Somfy + others). User-driven RE / interop research on hardware the user owns. Phase 6 is achieved as of 2026-05-14: cross-vendor pairing + control works in software, no external programmer needed.

Hard constraints (from the user's brief)

These override defaults. Read first.

1. Don't auto-advance phases. Each phase ends with the user physically verifying on hardware. Wait for explicit go-ahead before starting the next phase.
2. For any change to ISR or register-init code, explain the timing budget and worst-case execution path before writing the code. CC1101 SPI timing is fragile; we burned a day on a chip-ready-wait omission.
3. For every protocol decision cite the source. Captured frames, official docs, or upstream RE projects. Never guess byte semantics.
4. Don't guess. Capture first, then reason.
5. First action of every session: read PROGRESS.md. It carries the full context window of decisions and gotchas from prior sessions.

Code map

iohc_flipper/src/
├── iohc_app.c           # Entry, view dispatcher, consumer thread, callbacks
├── radio/
│   └── radio_cc1101.c   # SPI driver, register init, RX/TX state machine
├── phy/
│   └── phy_rx.c         # FIFO drain → frame assembly with sync alignment
├── iohc/
│   ├── frame_parse.c    # Bytes → IohcParsedFrame (Ctrl/dst/src/cmd/payload/seq/MAC/CRC)
│   ├── frame_build.c    # Build 1W frame + UART-wrap + bit-pack for FIFO
│   ├── crc.c            # CRC-16/KERMIT
│   ├── hmac_1w.c        # AES-128-ECB based HMAC for 1W suffix
│   ├── aes.c            # AES-128 primitives (CBC/ECB/CFB)
│   └── key_encrypt.c    # iohc_wrap_install_key (cmd 0x30 enc_key field)
├── state/
│   ├── identity.c       # Global Flipper identity (src+key+seq) on SD
│   ├── device_book.c    # Per-shutter identities, binary format v2 + JSON export
│   └── tx_runner.c      # High-level send_button / send_pair, vendor-mapped man_id
├── ui/
│   ├── view_main_menu.c
│   ├── view_sniffer.c       # Live raw frame display
│   ├── view_capture.c       # SRC-indexed capture (vendor only trusted on cmd 0x00)
│   ├── view_device_list.c   # Saved shutters with [S]/[V]/[?] prefix
│   ├── view_device_actions.c
│   └── view_identity.c
└── log/
    └── log.c            # Per-session CSV + raw .bin write