Skip to main content
Version: 2.8

HTTP API

info

This is a mini-spec on a HTTP API which can be used by browser based clients to interact with Meshtastic devices.

Why protobufs​

  • No need for JSON parsing on the resource constrained embedded server.
  • Small.
  • Already in use for all other transports (so shared testing/tooling coverage).
  • Backwards and forward compatible.

Request headers​

  • Content-Type: application/x-protobuf
    • Indicates protobufProtobuf (Protocol Buffers). A method developed by Google for serializing structured data, used in Meshtastic for efficient communication protocol between devices. content (Meshtastic protobufsProtobuf (Protocol Buffers). A method developed by Google for serializing structured data, used in Meshtastic for efficient communication protocol between devices.)

Response headers​

  • Content-Type: application/x-protobuf
    • Indicates protobufProtobuf (Protocol Buffers). A method developed by Google for serializing structured data, used in Meshtastic for efficient communication protocol between devices. content (Meshtastic protobufsProtobuf (Protocol Buffers). A method developed by Google for serializing structured data, used in Meshtastic for efficient communication protocol between devices.)
  • X-Protobuf-Schema: <URI to the .proto schema file>
    • Not required but recommended for documentation/reflection purposes

Endpoints​

Two endpoints are specified:

/api/v1/toradio​

Allows PUT and OPTION requests.

PUT​

A PUT request to this endpoint will be expected to contain a series of ToRadio protobufProtobuf (Protocol Buffers). A method developed by Google for serializing structured data, used in Meshtastic for efficient communication protocol between devices. payloads.

The protobufsProtobuf (Protocol Buffers). A method developed by Google for serializing structured data, used in Meshtastic for efficient communication protocol between devices. will be sent in binary as the body for the request.

Only one ToRadio message per request is supported.

OPTIONS​

An OPTIONSrequest to this endpoint will return a response status code 204 and headers only.

/api/v1/fromradio​

Allows GET requests.

GET​

A GET request from this endpoint will return a series of FromRadio protobufsProtobuf (Protocol Buffers). A method developed by Google for serializing structured data, used in Meshtastic for efficient communication protocol between devices..

The protobufsProtobuf (Protocol Buffers). A method developed by Google for serializing structured data, used in Meshtastic for efficient communication protocol between devices. will be sent in binary as the body for the request.

Parameters

/api/v1/fromradio?all​
  • all=false (unset default)
    • Only one protobufProtobuf (Protocol Buffers). A method developed by Google for serializing structured data, used in Meshtastic for efficient communication protocol between devices. is returned.
  • all=true
    • All available protobufsProtobuf (Protocol Buffers). A method developed by Google for serializing structured data, used in Meshtastic for efficient communication protocol between devices. are returned.
/api/v1/fromradio?chunked​
  • chunked=false (unset default, not yet implemented)
    • The request returns all protobufsProtobuf (Protocol Buffers). A method developed by Google for serializing structured data, used in Meshtastic for efficient communication protocol between devices. 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 that the server will keep open as long as the client wants. This will allow efficient streaming of new FromRadio protobufsProtobuf (Protocol Buffers). A method developed by Google for serializing structured data, used in Meshtastic for efficient communication protocol between devices. as they are generated by the radio.

Authentication​

There isn't any user authentication. We assume access to the HTTP server is enough to establish trust.

Client​

JavaScript​

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 protobufProtobuf (Protocol Buffers). A method developed by Google for serializing structured data, used in Meshtastic for efficient communication protocol between devices. 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​

See: https://github.com/spluxx/Protoman

Protoman is able to interface with the Meshtastic REST API out of the box. This is useful for manual testing of the endpoints.

Security​

HTTP and HTTPS are both supported on the ESP32ESP32A chipset of microcontroller made/designed by Espressif, used by a number of devices. Higher power usage than nRF52, but often cheaper and supports Wi-Fi if desired. using self-signed certificates on HTTPS.