Flipper Zero Firmware
Loading...
Searching...
No Matches
Expansion Module Protocol

Terms and definitions

  • Expansion Module: A third-party hardware unit meant for use with Flipper Zero by connecting it to its GPIO header.
  • Expansion Module Protocol: A serial-based, byte-oriented, synchronous communication protocol described in this document.
  • Host: Hardware unit tasked with serving requests. Used interchangeably with Flipper, Server, Host etc. throughout this document.
  • Device: Used interchangeably with Expansion Module, Module, Client, etc.
  • RPC: Remote Procedure Call, a protobuf-based communication protocol widely used by Flipper Zero companion applications.
  • Timeout Interval: Period of inactivity to be treated as a loss of connection, also denoted as Tto. Equals to 250 ms.
  • Baud Rate Switch Dead Time: Period of time after baud rate change during which no communication is allowed, also denoted Tdt. Equals to 25 ms.

Features

  • Automatic expansion module detection
  • Baud rate negotiation
  • Basic error detection
  • Request-response communication flow
  • Integration with Flipper RPC protocol

Hardware

Depending on the UART selected for communication, the following pins area available for the expansion modules to connect to:

UART Tx pin Rx pin
USART 13 14
LPUART 15 16

Frame structure

Each frame consists of a header (1 byte), contents (size depends of frame type) and checksum (1 byte) fields:

Header (1 byte) Contents (0 or more bytes) Checksum (1 byte)
Frame type Frame payload XOR checksum

Heartbeat frame

HEARTBEAT frames are used to maintain an idle connection. In the event of not receiving any frames within Tto, either side must cease all communications and be ready to initiate the connection again.

Header (1 byte) Checksum (1 byte)
0x01 XOR checksum

Note that the contents field is not present (0 bytes length).

Status frame

STATUS frames are used to report the status of a transaction. Every received frame MUST be confirmed by a matching STATUS response.

Header (1 byte) Contents (1 byte) Checksum (1 byte)
0x02 Error code XOR checksum

The Error code field SHALL have one of the following values:

Error code Meaning
0x00 OK (No error)
0x01 Unknown error
0x02 Baud rate not supported

Baud rate frame

BAUD RATE frames are used to negotiate communication speed. The initial connection SHALL always happen at 9600 baud. The first message sent by the module MUST be a BAUD RATE frame, even if a different speed is not required.

Header (1 byte) Contents (4 bytes) Checksum (1 byte)
0x03 Baud rate XOR checksum

If the requested baud rate is supported by the host, it SHALL respond with a STATUS frame with an OK error code, otherwise the error code SHALL be 0x02 (Baud rate not supported). Until the negotiation succeeds, the speed SHALL remain at 9600 baud. The module MAY send additional BAUD RATE frames with alternative speeds in case the initial request was refused. No other frames are allowed until the speed negotiation succeeds.

Control frame

CONTROL frames are used to control various aspects of the communication. As of now, the sole purpose of CONTROL frames is to start and stop the RPC session.

Header (1 byte) Contents (1 byte) Checksum (1 byte)
0x04 Command XOR checksum

The Command field SHALL have one of the followind values:

Command Meaning
0x00 Start RPC session
0x01 Stop RPC session

Data frame

DATA frames are used to transmit arbitrary data in either direction. Each DATA frame can hold up to 64 bytes. If an RPC session is curretly open, all received bytes are forwarded to it.

Header (1 byte) Contents (1 to 65 byte(s)) Checksum (1 byte)
0x05 Data XOR checksum

The Data field SHALL have the following structure:

Data size (1 byte) Data (0 to 64 bytes)
0x00 ... 0x40 Arbitrary data

Communication flow

In order for the host to be able to detect the module, the respective feature must be enabled first. This can be done via the GUI by going to Settings -> Expansion Modules and selecting the required Listen UART or programmatically by calling expansion_enable(). Likewise, disabling this feature via the same GUI or by calling expansion_disable() will result in ceasing all communications and not being able to detect any connected modules.

The communication is always initiated by the module by the means of shortly pulling the RX pin down. The host SHALL respond with a HEARTBEAT frame indicating that it is ready to receive requests. The module then MUST issue a BAUDRATE request within Tto. Failure to do so will result in the host dropping the connection and returning to its initial state.

MODULE | FLIPPER
-----------------------------+---------------------------
| (Start)
Pull down RX -->
<-- Heartbeat
Baud Rate -->
<-- Status [OK | Error]
|
(Module changes baud rate | (Flipper changes
and waits for Tdt) | baud rate)
|
Control [Start RPC] -->
<-- Status [OK | Error]
-----------------------------+--------------------------- (1)
Data [RPC Request] -->
<-- Status [OK | Error]
<-- Data [RPC Response]
Status [OK | Error] -->
-----------------------------+--------------------------- (2)
Data [RPC Request pt.1] -->
<-- Status [OK | Error]
Data [RPC Request pt.2] -->
<-- Status [OK | Error]
Data [RPC Request pt.3] -->
<-- Status [OK | Error]
<-- Data [RPC Response]
Status [OK | Error] -->
-----------------------------+--------------------------- (3)
Heartbeat -->
<-- Heartbeat
Heartbeat -->
<-- Heartbeat
-----------------------------+---------------------------
Control [Stop RPC] -->
<-- Status [OK | Error]
(Module disconnected) |
| (No activity within Tto
| return to start)
(1) The module MUST confirm all implicitly requested frames (e.g. DATA frames containing RPC responses) with a STATUS frame.
(2) RPC requests larger than 64 bytes are split into multiple frames. Every DATA frame MUST be confirmed with a STATUS frame.
(3) When the module has no data to send, it MUST send HEARTBEAT frames with a period < Tto in order to maintain the connection.
The host SHALL respond with a HEARTBEAT frame each time.

Error detection

Error detection is implemented via adding an extra checksum byte to every frame (see above).

The checksum is calculated by bitwise XOR-ing every byte in the frame (excluding the checksum byte itself), with an initial value of 0.

Error recovery behaviour

In the event of a detected error, the concerned side MUST cease all communications and reset to initial state. The other side will then experience a communication timeout and the connection will be re-established automatically.