beffroi-tools/docs/flipper-link.md

13 KiB

Flipper Link: feasibility study

Status: proposed tool; no implementation or hardware validation yet. Research date: 2026-11-06. Back to future ideas.

Verdict

Yes: a computer connected to a Flipper Zero over USB can act as a bridge between web commands and device actions. A Bitfocus Companion connection module can then expose those actions to Stream Deck buttons. Saved infrared remote buttons are a strong first use case because the official firmware implements an RPC mode for loading a remote and triggering its signals.

This is feasible with official firmware for a defined set of actions. It is not a universal API for every internal function: each application must expose the required CLI command or RPC behavior. Arbitrary application internals may need an external Flipper application or firmware changes. These conclusions come from documentation and source inspection, not tests on the connected device. See the official CLI documentation and Infrared RPC implementation.

USB interfaces

The Flipper itself provides a USB serial CLI; no Wi-Fi development board is needed. Typical ports are /dev/ttyACM* on Linux, /dev/cu.usbmodemflip_* on macOS and a COM port on Windows. Prefer device identity or Linux's /dev/serial/by-id/ over a hard-coded port number. Close qFlipper and any other serial client before taking ownership. Run help to discover commands on the actual firmware. Flipper also documents browser access through Flipper Lab and Web Serial. Connection instructions.

Two automation paths are available:

Interface Suitable use Tradeoff
Text CLI Exploration and commands without an RPC equivalent Must handle prompts, echo, text changes and commands that keep running.
Protobuf RPC over USB serial Structured device, storage, GUI and supported application operations Requires framed binary messages, response correlation and session management.

start_rpc_session switches the CLI into protobuf mode. After that, the bridge must exchange binary protocol messages, not append CLI commands to the stream. The firmware uses length-delimited protobuf messages and command IDs. Prefer RPC for the main adapter; isolate any CLI fallback behind explicit session transitions. CLI reference, RPC implementation.

Flipper Devices publishes Python bindings and a flipperCmd utility with examples for device information, file listing and starting Infrared. This is useful prototype material, but its README describes it as alpha: validate and pin it before relying on it, including its protocol compatibility and license. Official Python bindings.

What could be exposed

Source availability below means there is an implementation path, not that all firmware versions, files or applications have been tested.

Capability Evidence and boundary Proposed scope
Device identity, ping and power information Defined in the system RPC schema. Initial status API; report unavailable fields honestly.
File browsing and reading Demonstrated by the official Python client. Browse configured remote directories; leave writes out of the first version.
Saved infrared buttons Infrared RPC scene handles loading, named/indexed presses and release. First useful control feature, including bounded holds.
Application launch, file load and exit Defined in the application RPC schema. Only explicitly tested applications and arguments. Launch does not imply full remote control.
Screen streaming and navigation Frames and input events are defined in the GUI RPC schema. Optional diagnostic view; menu macros are sensitive to current UI state.
Saved Sub-GHz transmission Sub-GHz RPC scene handles transmit/release and rejects restricted frequencies. Later, per-file validation; preserve firmware restrictions and surface errors.
GPIO, NFC, RFID, iButton and other utilities CLI commands exist, but their workflows and RPC coverage differ. Investigate individually after the infrared prototype.
Arbitrary FAP/app internals Generic launch and data-exchange messages do not make every app remotely controllable. Requires app cooperation; do not promise universal support.

For the last two rows, consult the CLI command list and application protocol. USB modes that replace the serial interface also require separate investigation; do not assume a persistent control connection during such applications.

Proposed architecture

flowchart LR
    S[Stream Deck] --> C[Bitfocus Companion]
    C --> M[Generic HTTP or Flipper Link module]
    M -->|HTTP requests| B[Local Flipper Link service]
    W[Web client or script] -->|HTTP requests| B
    B --> Q[Device session and action queue]
    Q <-->|USB serial: CLI or protobuf RPC| F[Flipper Zero]
    B -->|Status polling or events| M

The bridge runs on the computer physically attached to the Flipper. Companion can run there or on another reachable computer. The host must remain awake and the service running. A Wi-Fi board is unnecessary for this arrangement.

Use one service as the serial-port owner, with one serialized action queue per device. Web clients and Companion share that queue. Return explicit busy, disconnected and unsupported states rather than starting competing apps.

A direct serial Companion module is possible, but would couple USB drivers, protocol state and device ownership to Companion. A separate service also serves scripts and web clients and keeps the Companion module small. Browser-only Web Serial is useful for experimentation; a persistent service is the proposed path for unattended Companion control.

For a proof of concept, a small Python adapter using the existing bindings is reasonable. Keep HTTP routing, action validation and the device transport separate. If adopted as a maintained repository tool, evaluate a Rust workspace crate for portable delivery, using generated protobuf types and a serial library. That choice needs a packaging/dependency review; no new dependency is selected by this study. The Companion module would remain TypeScript.

Proposed web contract

These endpoints are a design sketch, not existing commands:

Endpoint Meaning
GET /api/v1/status Bridge version, device identity, firmware/protocol version, connection and busy state.
GET /api/v1/actions Configured, supported action IDs and labels.
POST /api/v1/actions/{id}/run Run a configured action, such as one saved infrared button.
GET /api/v1/jobs/{id} Read queued/running/completed/failed/unknown execution state.
POST /api/v1/jobs/{id}/stop Request release/cancellation where the adapter supports it.

For example, configure projector-power to reference a particular .ir file and button. A POST to /api/v1/actions/projector-power/run returns HTTP 202 and a job ID. Completion means the Flipper operation completed; it does not prove that the projector received the signal or changed state.

Start with status polling. Add an event stream later if feedback latency needs it. Keep mutating actions on POST. Validate parameters and configured file paths; do not expose arbitrary shell or raw CLI execution as the public API. Bind to loopback by default, authenticate requests, and make LAN listening an explicit configuration with suitable transport protection. A browser UI should use a restricted origin policy.

Companion integration

Build a Companion connection module, which is the extension point for controlled devices and software. Companion already supplies Stream Deck support; this design does not require a separate Elgato application plugin. Companion module guide, Companion project.

  1. Validate the API with Companion's existing Generic HTTP module. It supports POST bodies and custom headers, so a button can run an action with an authorization header. Generic HTTP help.
  2. Once the API is stable, use the official TypeScript template and @companion-module/base. Select versions compatible with the installed stable Companion release; follow the template's runtime requirements. TypeScript template, module framework.
  3. Proposed configuration: bridge URL, token, device selection and timeout. Proposed actions: run saved action, stop current job and refresh status. Proposed feedback: disconnected, busy, transmitting and failed. Proposed variables: device name, firmware, current action and last error. Include ready-made infrared button presets.
  4. Test locally through Companion's developer modules folder. Public distribution is a later step following Bitfocus's module release process; it is not required for the initial local integration. Check for an existing suitable module before creating a new public one. Development workflow.

Reliability and compatibility

  • Discover the selected device again after unplug/replug or reboot. Display actionable port-permission and port-in-use errors; do not silently choose a different Flipper if multiple devices are attached.
  • Query firmware and protobuf versions on connection. Maintain a tested capability table; reject unknown operations rather than assuming that a message in the schema guarantees application support.
  • Give operations deadlines, bounded queue length and explicit cancellation. A failed stop or lost connection must report an unknown device state.
  • Bound hold duration in the bridge and release on normal cancellation. Test firmware behavior on USB loss: a host timer alone cannot guarantee stopping an action after the cable or process disappears.
  • Never automatically replay a transmission after an ambiguous timeout or reconnect. Deduplicate repeated HTTP requests with a request ID; a power toggle sent twice could undo the first action.
  • Report acknowledged execution separately from inferred target state. Neither an IR send acknowledgment nor a green button proves the appliance is on.

Validation plan and delivery stages

  1. Device discovery: record OS, firmware and protocol versions; close other clients; confirm CLI help, RPC ping and device information. No firmware change should be needed for this stage.
  2. Infrared proof: list a known remote, load it and run a selected button against a test appliance. Verify tap, hold/release, invalid file/button, application busy state and repeated runs.
  3. Local HTTP bridge: implement the minimal contract and single-device queue. Test malformed input, authentication, parallel requests, timeouts, cancellation, duplicate requests and unplug/replug. Add transport tests using recorded or synthetic responses; verify framing across partial reads.
  4. Companion proof: run the same action from Generic HTTP. Measure press-to-send latency and verify visible errors while the device is disconnected. Set a practical latency target from these measurements, not an assumed guarantee.
  5. Dedicated module: implement configuration, action discovery, feedback, variables and presets. Test module restart and lost bridge connections.
  6. Expansion and packaging: validate each additional action family and host OS independently. Document tested firmware versions, startup and USB permissions.

The go/no-go gate is reliable infrared triggering and recovery from disconnects on the actual device. USB/RPC plumbing is supported upstream; application coverage and failure recovery are the main development uncertainties. A broad promise to expose all Flipper functionality should wait for individual adapters and device tests.

Upstream dev/main links describe moving source branches. Before implementation, pin the firmware, protobuf definitions and client library revisions used for testing. This study did not open the USB device, transmit signals, install software or measure latency.