flipper-rpc – Serial RPC Control for the Flipper Zero

Finally! A Rust library to control a Flipper Zero through RPC commands.

flipper-rpc is a Rust library for sending and receiving RPC messages to and from a Flipper Zero over a serial connection.

✨ Features

• tokio-tracing compatible
• Automatic Flipper detection
• Full flipperzero-protobuf support
• Serial-based RPC interface
• Full filesystem support
• Ergonomic, user-friendly API so you don't have to use raw protobuf messages.

🚧 Tentative

• Bluetooth support (maybe 🤞)

🧪 Planned

Nothing for now... Add an issue if you want something cool added!

Features

📦 Installation

[!IMPORTANT] Please decide on features, and don't just use the full feature since you are lazy. Actually read the table above and enable what you need as it will significantly decrease compile time.

Run this command

cargo add flipper-rpc --features <FEATURES>

Or add this to your Cargo.toml:

[dependencies]
flipper-rpc = { features = [], version = "0.9.0" } # Replace with the latest version from crates.io

🚀 Usage

Playing an alert

let ports = list_flipper_ports()?;
let port = &ports[0].port_name;

let mut cli = SerialRpcTransport::new(port.to_string())?;

let response = cli.send_and_receive(Request::SystemPlayAudiovisualAlert)?;

📚 Flipper Zero RPC Protocol Documentation

After far too much searching for usable documentation on this API (and finding nothing), I decided to write my own. Enjoy!

[!NOTE] Read the source code for information about actual communication, the following information is only for serial transport (BLE COMING SOON)

🔌 Connecting

1. Make a serial connection. Use your preferred serial library. This crate uses serialport, which is simple and only requires the port path and a baud rate.

2. Baud rate... Apparently doesn't matter Serial over USB (CDC-ACM) abstracts baud rate away, it must be reasonable and capable by the hardware and software.

3. Drain the buffer. Keep reading until you see the shell prompt string ">: ". This clears old buffer content, since reads begin from the buffer start — not your last write.

4. Enter RPC mode. Write the string: start_rpc_session\r

   Note: \r\n does not work here. I do not know why.

5. Drain again. Read until you receive \n, which indicates that the Flipper has accepted the command.

📤 Sending RPC Commands

1. Encode the request using protobuf.
2. Prefix the message with its length (encoded as a Varint, not a regular byte).

🔢 Varint is a variable-length integer encoding. The Flipper expects this as the first byte(s) of your message.

Example: Sending PingRequest with [1, 2, 3, 4]

Raw request bytes:

[8, 42, 6, 10, 4, 1, 2, 3, 4]

• 8 is the Varint-encoded length of the rest of the message.

📥 Receiving RPC Responses

1. Read the length prefix The length is a Varint and can be up to 10 bytes.

   • Slow way: Read byte-by-byte until the MSB is 1.
   • Fast way: See my optimized logic in src/transport/serial/rpc.rs, read_raw(...) as it is too long to mention here.

2. Read and decode Once the length is known, read that many bytes, then decode with your protobuf deserializer.

Example response for the ping

[8, 50, 6, 10, 4, 1, 2, 3, 4]

🤔 Why This Exists

This crate was built to support another project I'm working on: 👉 flippy – a CLI tool for updating firmware and databases on the Flipper Zero from remote sources.

Since there was no existing way to speak RPC to the Flipper in Rust, I split that functionality into this standalone library.

💫 Shameless plug: If you find this useful, give it a star ⭐ — I'd appreciate it!

Credits

This project would not be possible without two amazing repos:

• flipwire. Gave amazing examples in source code that helped me implement the codec even better.
• flipperzero_protobuf_py More source-code examples, although in python, this library demonstrates the serial API very well and exactly how to use it and handle it properly.