Skip to content

Commit

Permalink
Core RPC docs fixes
Browse files Browse the repository at this point in the history
Co-authored-by: Cem Aksoylar <[email protected]>
  • Loading branch information
petejohanson and caksoylar authored Jul 15, 2024
1 parent 539f9d4 commit 9878336
Showing 1 changed file with 4 additions and 4 deletions.
8 changes: 4 additions & 4 deletions docs/docs/development/studio-rpc-protocol.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,15 +8,15 @@ ZMK Studio is still in active development, and the below information is for deve

## Overview

The ZMK Studio UI communicates with ZMK devices using a custom RPC protocol developed to be robust, reliable, while remaining simple and easy te extend with future enhancements.
The ZMK Studio UI communicates with ZMK devices using a custom RPC protocol developed to be robust, reliable, while remaining simple and easy to extend with future enhancements.

The protocol consist of [protocol buffer](https://protobuf.dev/programming-guides/proto3/) messages which are encoded/decoded using message framing, and the transmitted using an underlying transport. Two transports are currently implemented, a BLE transport using a custom GATT service, and a serial port transport, which usually is used with CDC ADM devices over USB.
The protocol consists of [protocol buffer](https://protobuf.dev/programming-guides/proto3/) messages which are encoded/decoded using message framing, and then transmitted using an underlying transport. Two transports are currently implemented: a BLE transport using a custom GATT service and a serial port transport, which usually is used with CDC ADM devices over USB.

## Protobuf Messages

The messages for ZMK Studio are defined in a dedicated [zmk-studio-messages](https://github.com/zmkfirmware/zmk-studio-messages) repository. Fundamentally, the [`Request`](https://github.com/zmkfirmware/zmk-studio-messages/blob/main/proto/zmk/studio.proto#L11) message is used to send any requests from the Studio client to the ZMK device, and the [`Response`](https://github.com/zmkfirmware/zmk-studio-messages/blob/main/proto/zmk/studio.proto#L21) messages are sent from the ZMK device to the Studio client.

Responses can either be [`RequestResponses`](https://github.com/zmkfirmware/zmk-studio-messages/blob/main/proto/zmk/studio.proto#L28) that are are sent in response to an incoming `Request`, or a [`Notification`](https://github.com/zmkfirmware/zmk-studio-messages/blob/main/proto/zmk/studio.proto#L38) which is sent at any point from the ZMK device to the Studio client to inform the client about state changes on the device, e.g. device is unlocked.
Responses can either be [`RequestResponses`](https://github.com/zmkfirmware/zmk-studio-messages/blob/main/proto/zmk/studio.proto#L28) that are sent in response to an incoming `Request` or a [`Notification`](https://github.com/zmkfirmware/zmk-studio-messages/blob/main/proto/zmk/studio.proto#L38) which is sent at any point from the ZMK device to the Studio client to inform the client about state changes on the device, e.g. that the device is unlocked.

## Message Framing

Expand All @@ -28,7 +28,7 @@ The following special bytes are used for the framing protocol:
- Escape Byte (Esc): `0xAC`
- End of Frame (EoF): `0xAD`

A message consists of a SoF byte, the payload, escaped as needed, followed by an EoF byte. Within the payload, and of the special encoding bytes will be escaped by being prefixed with an Esc byte.
A message consists of a SoF byte, the payload, escaped as needed, followed by an EoF byte. Within the payload, any of the special encoding bytes will be escaped by being prefixed with an Esc byte.

### Example Encoding (Simple)

Expand Down

0 comments on commit 9878336

Please sign in to comment.