mudhorn/meshtastic
1
0
Fork 0
mirror of https://github.com/meshtastic/meshtastic.git synced 2024-12-25 13:44:12 -08:00
Code Issues Actions 1 Packages Projects Releases Wiki Activity

Merge branch 'master' into settingsfix

Browse source
This commit is contained in:
Lennart Buhl 2022-10-06 15:24:42 +02:00 committed by GitHub
parent 23ff3e0e01 9cd0723cfb
commit 5566eccc90
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
2 changed files with 40 additions and 24 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

62
docs/developers/Firmware/http-api.mdx
View file

@ -5,7 +5,7 @@ sidebar_label: HTTP API
---
:::info
This is a mini-spec on a HTTP API which can be used by browser based clients to do operations with devices.
This is a mini-spec on a HTTP API which can be used by browser based clients to interact with Meshtastic devices.
:::
## Why protobufs
@ -17,47 +17,63 @@ This is a mini-spec on a HTTP API which can be used by browser based clients to
## Request headers
- Content-Type: application/x-protobuf
- Cookie: session=ABAD1D (this header is added automatically by the browser client, not implemented yet)
- `Content-Type: application/x-protobuf`
- Indicates protobuf content (Meshtatic protobufs)
## Response headers
- Content-Type: application/x-protobuf (indicates meshtatics protobufs)
- X-Protobuf-Schema: <URI to the .proto schema file> (not required but recommended for documentation/reflection purposes)
(not implemented) All clients (if their request did not include a session cookie) will be assigned a random and unique session key. The cookie will not be set if the client already has one. Example response:
- Set-Cookie: session=ABAD1D;path=/
(FIXME - check how this relates to XSS attacks)
- `Content-Type: application/x-protobuf`
- Indicates protobuf content (Meshtatic protobufs)
- `X-Protobuf-Schema: <URI to the .proto schema file>`
- Not required but recommended for documentation/reflection purposes
## Endpoints
Two endpoints are specified:
### PUT /api/v1/toradio
### /api/v1/toradio
A PUT to this endpoint will be expected to contain a series of ToRadio protobuf payloads. For the initial implementation only one ToRadio message per PUT is supported, but future optimizations to improve throughput might add support for multiple ToRadios in a single PUT.
Allows `PUT` and `OPTION` requests.
#### PUT
A `PUT` request to this endpoint will be expected to contain a series of ToRadio protobuf payloads.
The protobufs will be sent in binary as the body for the request.
A request with OPTIONS to this endpoint will return status 204 and just the headers.
For the initial implementation, only one ToRadio message per request is supported, but future optimizations to improve throughput might add support for multiple ToRadios in a single request.
### GET /api/v1/fromradio?chunked=false|true&all=true|false
#### OPTIONS
A GET from this endpoint will return a series of FromRadio protobufs.
An `OPTIONS`request to this endpoint will return a response status code `204` and headers only.
- chunked=false|true (not implemented)
- If the query parameter "chunked" is false (or unset), the GET will simply return all the protobufs which can currently be delivered for this clients session (this would allow the client to poll by doing a series of GETs). This is the only option that is supported in the initial release.
- Eventually if chunked=true, the response will be a [stream of chunks](https://en.wikipedia.org/wiki/Chunked_transfer_encoding) that the server will keep open as long as the client wants. This will allow efficient streaming of new FromRadio protobufs as they are generated by the radio.
- all=true|false
- If this query is false (or unset), the GET will return just one protobuf. If set to true, will return all the available protobufs.
### /api/v1/fromradio
Allows `GET` requests.
#### GET
A `GET` request from this endpoint will return a series of FromRadio protobufs.
The protobufs will be sent in binary as the body for the request.
**Parameters**
##### **/api/v1/fromradio?all**
- `all=false` (unset default)
- Only one protobuf is returned.
- `all=true`
- All available protobufs are returned.
##### **/api/v1/fromradio?chunked**
- `chunked=false` (unset default, not yet implemented)
- The request returns all protobufs that can be delivered for the client's session (this would allow the client to poll by doing a series of requests). This is the only option that is supported in the initial release.
- `chunked=true` (not yet implemented)
- If chunked=true, the response will be a [stream of chunks](https://en.wikipedia.org/wiki/Chunked_transfer_encoding) that the server will keep open as long as the client wants. This will allow efficient streaming of new `FromRadio` protobufs as they are generated by the radio.
## Authentication
The initial release will not have **any** user authentication. i.e. we assume access to the HTTP server is enough to establish trust.
The initial release will not have **any** user authentication. We assume access to the HTTP server is enough to establish trust.
Since authentication is also eventually needed for our other transports (TCP and eventually open BLE), we will be adding authentication **in-band**. When added in the second release there will be a new payload supported inside ToRadio for `SignIn <userid> <usersecret>`. The server will respond with a FromRadio `SignInResponse okay|fail`. Also, in the case of the REST API, that SignIn status will then be associated with the current session key. Most (all?) ToRadio packets will be ignored if the client is not signed in. Most (all?) FromRadio packets will be sent to clients that are not signed in.
@ -67,7 +83,7 @@ Since authentication is also eventually needed for our other transports (TCP and
See: <https://github.com/meshtastic/meshtastic.js>
A reference client written in JavaScript will provide a JavaScript API for using this transport. That client will do HTTP connections, use the generated protobuf JavaScript code and provide an API that hides all of this REST plumbing. The two key methods will be "sendToRadio(packet) and onFromRadio(callback)".
A reference client written in JavaScript will provide a JavaScript API for using this transport. That client will do HTTP connections, use the generated protobuf JavaScript code and provide an API that hides all of this REST plumbing. The two key methods will be `sendToRadio(packet)` and `onFromRadio(callback)`.
### Protoman

2
docs/settings/config/lora.mdx
View file

@ -57,7 +57,7 @@ A number from 7 to 12. Indicates the number of chirps per symbol as 1<<spread_fa
### Coding Rate
The denominator of the coding rate. ie for 4/8, the value is 8. 5/8 the value is 5.
The denominator of the coding rate. ie for 4/5, the value is 5. 4/8 the value is 8.
### Frequency Offset