# FlipperDroid Bridge Protocol v0.1

Binary protocol over USB CDC serial or BT rfcomm.
All messages are framed: [MAGIC(2)][LEN(2)][CMD(1)][PAYLOAD(N)][CRC8(1)]

## Magic
0xFD 0x01 ("Flipper Droid" v01)

## Commands (Phone -> Flipper)

### System
0x01 PING                    -> expects PONG
0x02 VERSION                 -> returns firmware version, device name
0x03 CAPABILITIES            -> returns bitmask of available subsystems
0x04 STATUS                  -> returns battery, temp, uptime

### GPIO
0x10 GPIO_INIT              pin(1) mode(1)           -> OK/ERR
0x11 GPIO_WRITE             pin(1) value(1)          -> OK/ERR
0x12 GPIO_READ              pin(1)                   -> value(1)
0x13 GPIO_PWM               pin(1) freq(4) duty(1)   -> OK/ERR
0x14 GPIO_ADC_READ          pin(1)                   -> value(2)
0x15 GPIO_INTERRUPT          pin(1) edge(1) enable(1) -> OK/ERR (Flipper pushes events)

### SubGHz
0x20 SUBGHZ_SET_FREQ        freq_hz(4)               -> OK/ERR
0x21 SUBGHZ_TX              data(N)                  -> OK/ERR
0x22 SUBGHZ_RX_START        -                        -> OK/ERR (starts streaming)
0x23 SUBGHZ_RX_STOP         -                        -> OK/ERR
0x24 SUBGHZ_GET_RSSI        -                        -> rssi(2)
0x25 SUBGHZ_SET_MODULATION  mod(1) bandwidth(1)      -> OK/ERR
0x26 SUBGHZ_REPLAY          slot(1)                  -> OK/ERR (replay captured signal)

### RFID (125kHz)
0x30 RFID_READ              -                        -> uid(N) protocol(1)
0x31 RFID_EMULATE           uid(N) protocol(1)       -> OK/ERR
0x32 RFID_WRITE             uid(N) protocol(1)       -> OK/ERR

### NFC (13.56MHz)
0x40 NFC_POLL               -                        -> type(1) uid(N) atqa(2) sak(1)
0x41 NFC_READ_FULL          -                        -> dump(N)
0x42 NFC_EMULATE            data(N) type(1)          -> OK/ERR
0x43 NFC_RELAY_START        -                        -> OK/ERR (relay mode via phone network)
0x44 NFC_RELAY_STOP         -                        -> OK/ERR
0x45 NFC_RAW_EXCHANGE       data(N)                  -> response(N)

### Infrared
0x50 IR_TX                  protocol(1) addr(4) cmd(4) -> OK/ERR
0x51 IR_TX_RAW              timings(N*2)             -> OK/ERR
0x52 IR_RX_START            -                        -> OK/ERR (starts streaming)
0x53 IR_RX_STOP             -                        -> OK/ERR
0x54 IR_REPLAY              slot(1)                  -> OK/ERR

### iButton
0x60 IBUTTON_READ           -                        -> key(8) type(1)
0x61 IBUTTON_EMULATE        key(8) type(1)           -> OK/ERR
0x62 IBUTTON_WRITE          key(8) type(1)           -> OK/ERR

### BadUSB (Flipper acts as HID to another target)
0x70 BADUSB_START           -                        -> OK/ERR
0x71 BADUSB_EXEC            script(N)                -> OK/ERR
0x72 BADUSB_STOP            -                        -> OK/ERR

### CPU Share (Phone -> Flipper offload)
0x80 CPU_TASK_SUBMIT        task_id(4) code(N)       -> OK/ERR
0x81 CPU_TASK_RESULT        task_id(4)               -> status(1) result(N)
0x82 CPU_TASK_CANCEL        task_id(4)               -> OK/ERR

### File Transfer
0x90 FILE_LIST              path(N)                  -> entries(N)
0x91 FILE_READ              path(N)                  -> data(N)
0x92 FILE_WRITE             path(N) data(N)          -> OK/ERR
0x93 FILE_DELETE             path(N)                  -> OK/ERR

## Commands (Flipper -> Phone)

### Async Events
0xA0 EVENT_GPIO_IRQ         pin(1) value(1) timestamp(4)
0xA1 EVENT_SUBGHZ_RX        data(N) rssi(2) freq(4)
0xA2 EVENT_IR_RX            protocol(1) addr(4) cmd(4)
0xA3 EVENT_NFC_FIELD        type(1)
0xA4 EVENT_BUTTON           button(1) state(1)
0xA5 EVENT_CPU_REQUEST      task_id(4) workload(N)   -> phone runs it, returns result

## Responses
0xFE OK                     optional_data(N)
0xFF ERR                    error_code(1) message(N)

## Error Codes
0x01 UNKNOWN_CMD
0x02 INVALID_PARAMS
0x03 SUBSYSTEM_DISABLED
0x04 HARDWARE_ERROR
0x05 BUSY
0x06 TIMEOUT
0x07 NOT_SUPPORTED