mudhorn/meshtastic
1
0
Fork 0
mirror of https://github.com/meshtastic/meshtastic.git synced 2024-11-10 07:34:11 -08:00
Code Issues Actions 1 Packages Projects Releases Wiki Activity

caps and dots

Browse source
This commit is contained in:
pdxlocations 2023-08-19 23:16:25 -07:00
parent 06b851c88c
commit 38af1db9a5
1 changed files with 19 additions and 19 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

38
docs/development/device/client-api.mdx
View file

@ -18,14 +18,14 @@ This protocol is **almost** identical when it is deployed over BLE, Serial/USB,
- The stream going towards the radio is only a series of ToRadio packets (with the extra 4 byte headers)
- The stream going towards the PC is a stream of FromRadio packets (with the 4 byte headers), or if the receiver state machine does not see valid header bytes it can (optionally) print those bytes as the debug console from the radio. This allows the device to emit regular serial debugging messages (which can be understood by a terminal program) but also switch to a more structured set of protobufs once it sees that the PC client has sent a protobuf towards it.
The 4 byte header is constructed to both provide framing and to not look line 'normal' 7 bit ASCII.
The 4 byte header is constructed to both provide framing and to not look like 'normal' 7 bit ASCII.
- Byte 0: START1 (0x94)
- Byte 1: START2 (0xc3)
- Byte 2: MSB of protobuf length
- Byte 3: LSB of protobuf length
The receiver will validate length and if >512 it will assume the packet is corrupted and return to looking for START1. While looking for START1 any other characters are printed as "debug output". For small example implementation of this reader see the python implementation.
The receiver will validate length and if >512 it will assume the packet is corrupted and return to looking for START1. While looking for START1 any other characters are printed as "debug output". For a small example implementation of this reader see the python implementation.
## Bluetooth (MeshBluetoothService)
@ -35,8 +35,8 @@ For a reference implementation of a client that uses this service see [RadioInte
Typical flow when a phone connects to the device should be the following (if you want to watch this flow from the python app just run `meshtastic --debug --info` - the flow over BLE is identical):
- There are only three relevant endpoints (and they have built in BLE documentation - so use a BLE tool of your choice to watch them): FromRadio, FromNum (sends notifies when new data is available in FromRadio) and ToRadio
- SetMTU size to 512
- There are only three relevant endpoints (and they have built in BLE documentation - so use a BLE tool of your choice to watch them): FromRadio, FromNum (sends notifies when new data is available in FromRadio) and ToRadio.
- SetMTU size to 512.
- Write a ToRadio.startConfig protobuf to the "ToRadio" endpoint - this tells the radio you are a new connection and you need the entire NodeDB sent down.
- Read repeatedly from the "FromRadio" endpoint. Each time you read you will get back a FromRadio protobuf (see Meshtastic-protobuf). Keep reading from this endpoint until you get back and empty buffer.
- See below for the expected sequence for your initial download.
@ -45,13 +45,13 @@ Typical flow when a phone connects to the device should be the following (if you
Expected sequence for initial download:
- After your send startConfig, you will receive a series of FromRadio packets. The sequence of these packets will be as follows (but you are best not counting on this, instead just update your model for whatever packet you receive - based on looking at the type)
- Read a RadioConfig from "radio" - used to get the channel and radio settings
- Read a User from "user" - to get the username for this node
- Read a MyNodeInfo from "mynode" to get information about this local device
- Read a series of NodeInfo packets to build the phone's copy of the current NodeDB for the mesh
- Read a endConfig packet that indicates that the entire state you need has been sent
- Read a series of MeshPackets until it returns empty to get any messages that arrived for this node while the phone was away
- After your send startConfig, you will receive a series of FromRadio packets. The sequence of these packets will be as follows (but you are best not counting on this, instead just update your model for whatever packet you receive - based on looking at the type).
- Read a RadioConfig from "radio" - used to get the channel and radio settings.
- Read a User from "user" - to get the username for this node.
- Read a MyNodeInfo from "mynode" to get information about this local device.
- Read a series of NodeInfo packets to build the phone's copy of the current NodeDB for the mesh.
- Read an endConfig packet that indicates the entire state you need has been sent.
- Read a series of MeshPackets until it returns empty to get any messages that arrived for this node while the phone was away.
For definitions (and documentation) on FromRadio, ToRadio, MyNodeInfo, NodeInfo and User protocol buffers see [mesh.proto](https://github.com/meshtastic/protobufs/blob/master/meshtastic/mesh.proto)
@ -86,12 +86,12 @@ Note: that if the phone ever sees this number decrease, it means the ESP32 has r
Re: Queue management,
not all messages are kept in the fromradio queue (filtered based on SubPacket):
- only the most recent Position and User messages for a particular node are kept
- all Data SubPackets are kept
- No WantNodeNum / DenyNodeNum messages are kept
- A variable keepAllPackets, if set to true will suppress this behavior and instead keep everything for forwarding to the phone (for debugging)
- Only the most recent Position and User messages for a particular node are kept.
- All Data SubPackets are kept.
- No WantNodeNum / DenyNodeNum messages are kept.
- A variable keepAllPackets, if set to true will suppress this behavior and instead keep everything for forwarding to the phone (for debugging).
### A note on MTU sizes
### A Note on MTU Sizes
This device will work with any MTU size, but it is highly recommended that you call your phone's "setMTU function to increase MTU to 512 bytes" as soon as you connect to a service. This will dramatically improve performance when reading/writing packets.
@ -99,7 +99,7 @@ This device will work with any MTU size, but it is highly recommended that you c
On connect, you should send a want_config_id protobuf to the device. This will cause the device to send its node DB and radio config via the fromradio endpoint. After sending the full DB, the radio will send a want_config_id to indicate it is done sending the configuration.
### Other Bluetooth services
### Other Bluetooth Services
This document focuses on the core device protocol, but it is worth noting that the following other Bluetooth services are also
provided by the device.
@ -125,8 +125,8 @@ Characteristics
#### DeviceInformationService
Implements the standard BLE contract for this service (has software version, hardware model, serial number, etc...)
Implements the standard BLE contract for this service (has software version, hardware model, serial number, etc...).
#### BatteryLevelService
Implements the standard BLE contract service, provides battery level in a way that most client devices should automatically understand (i.e. it should show in the Bluetooth devices screen automatically)
Implements the standard BLE contract service, provides battery level in a way that most client devices should automatically understand (i.e. it should show in the Bluetooth devices screen automatically).