mirror of
https://github.com/meshtastic/meshtastic.git
synced 2024-12-27 14:39:54 -08:00
Merge branch 'master' into development-web
This commit is contained in:
rcarteraz
GitHub
commit
2a0f8463fd
|
|
@ -21,7 +21,7 @@ values={[
|
|||
<TabItem value="android">
|
||||
|
||||
:::info
|
||||
As of this writing, the current Android release of the nRF DFU app (v2.3.0) is not compatible with Meshtastic firmware updates.
|
||||
As of this writing, the current Android release of the nRF DFU app (v2.3.0) is not compatible with Meshtastic firmware updates. Please use the instructions below for updating via OTA with the nRF Connect App.
|
||||
:::
|
||||
|
||||
OTA firmware updates are available for Android using an older release of the more advanced nRF Connect App __version 4.24.3__ which is available for download from the [Nordic Semiconductor GitHub page](https://github.com/NordicSemiconductor/Android-nRF-Connect/releases/tag/v4.24.3).
|
||||
|
|
|
|||
|
|
@ -22,3 +22,5 @@ sidebar_label: Trademark Grants
|
|||
- Details: Paul primarily designs enclosures and assembles complete Meshtastic Radios for sale using modules from TTGO, Heltec and RAK. He runs an online shop for Meshtastic powered devices which carry the "Meshtastic" and M logos. The use of the Meshtastic Logo and Trademarks does not imply Paul is sponsored or endorsed by Meshtastic. Paul also agrees to maintain compliance with the Meshtastic Legal requirements. This grant is revokable at any time for any reason.
|
||||
- Grant: [Keith Monaghan](http://voltaicenclosures.com/)
|
||||
- Details: Keith is a contributer of computer aided design (CAD)/3D designs primarily for device enclosures and accessories, and runs an online shop for Meshtastic powered devices which carry the "Meshtastic" and "M" logos. The use of the Meshtastic Logo and Trademarks does not imply Keith is sponsored or endorsed by Meshtastic. Keith also agrees to maintain compliance with the Meshtastic Legal requirements. This grant is revokable at any time for any reason.
|
||||
- Grant: [Neil Hao](https://shop.uniteng.com/)
|
||||
- Details: Neil is a contributer of hardware designs, and runs an online shop for Meshtastic powered devices which carry the "Meshtastic" and "M" logos. The use of the Meshtastic Logo and Trademarks does not imply Neil is sponsored or endorsed by Meshtastic. Neil also agrees to maintain compliance with the Meshtastic Legal requirements. This grant is revokable at any time for any reason.
|
||||
|
|
|
|||
|
|
@ -17,22 +17,29 @@ You can find the settings available for MQTT [here](/docs/settings/moduleconfig/
|
|||
|
||||
Using or emitting packets directly in/from smart home control software such as Home Assistant or other consumers that can work with JSON messages.
|
||||
|
||||
When MQTT is enabled, the Meshtastic device simply uplinks and/or downlinks every raw protobuf packet that it sees to the MQTT broker. In addition, some packet types are serialized or deserialized from/to JSON messages for easier use in consumers. All packets are sent to the broker, whether they originate from another device on the mesh, or the gateway node itself.
|
||||
When MQTT is enabled, the Meshtastic device simply uplinks and/or downlinks every raw protobuf MeshPacket that it sees to the MQTT broker, encapsulated in a [ServiceEnvelope protobuf](https://buf.build/meshtastic/protobufs/docs/main:meshtastic#meshtastic.ServiceEnvelope). In addition, some packet types are serialized or deserialized from/to JSON messages for easier use in consumers. All packets are sent to the broker, whether they originate from another device on the mesh, or the gateway node itself.
|
||||
|
||||
Packets may be encrypted. If you use the default meshtastic MQTT server, packets are always encrypted. If you use a custom MQTT broker (ie set `mqtt.address`), the `mqtt.encryption_enabled` setting applies, which by default is false.
|
||||
|
||||
IMPORTANT: When MQTT is turned on, you are potentially broadcasting your entire mesh traffic onto the public internet. This includes messages and position information.
|
||||
|
||||
### MQTT Topics
|
||||
### MQTT [Topics](https://www.hivemq.com/blog/mqtt-essentials-part-5-mqtt-topics-best-practices)
|
||||
|
||||
The device will uplink and downlink raw ([protobuf](https://developers.google.com/protocol-buffers)) packets to the `msh/` prefix:
|
||||
If no specific [root topic](/docs/settings/moduleconfig/mqtt#root-topic) is configured, the default root topic will be `msh/`.
|
||||
Each device that is connected to MQTT will publish its MQTT state ("`online`"/"`offline`") to:
|
||||
|
||||
`msh/2/c/ShortFast/!12345678` where
|
||||
`msh/2/stat/USERID`, where `USERID` is the user ID of the gateway device (the one connected to MQTT).
|
||||
|
||||
- `!12345678` is the address of the gateway device.
|
||||
- `ShortFast` is the channel name.
|
||||
For each channel where uplink and/or downlink is enabled two other topics might be used.
|
||||
|
||||
The payload is a raw protobuf. Looking at the MQTT traffic with a program like `mosquitto_sub` will tell you it's working, but you won't get much useful information out of it. For example:
|
||||
#### Protobufs topic
|
||||
A gateway node will uplink and/or downlink raw ([protobuf](https://developers.google.com/protocol-buffers)) MeshPackets to the topic:
|
||||
|
||||
`msh/2/c/CHANNELNAME/USERID`, where `CHANNELNAME` is the name of the channel.
|
||||
|
||||
For example: `msh/2/c/LongFast/!abcd1234`
|
||||
|
||||
The payload is a raw protobuf, whose definitions for Meshtastic can be found [here](https://github.com/meshtastic/protobufs/blob/master/meshtastic). Reference guides for working with protobufs in several popular programming languages can be found [here](https://protobuf.dev/reference/). Looking at the MQTT traffic with a program like `mosquitto_sub` will tell you it's working, but you won't get much useful information out of it. For example:
|
||||
|
||||
```text
|
||||
苓????"!
|
||||
|
|
@ -40,7 +47,12 @@ The payload is a raw protobuf. Looking at the MQTT traffic with a program like `
|
|||
ShortFast !937bed1c
|
||||
```
|
||||
|
||||
Packets from the following [port numbers](/docs/development/firmware/portnum) are serialized to JSON and then forwarded to the `msh/2/json/CHANNELID/DEVICEID` topic: `TEXT_MESSAGE_APP`, `ENVIRONMENTAL_MEASUREMENT_APP`, `NODEINFO_APP` and `POSITION_APP`.
|
||||
If [encryption_enabled](/docs/settings/moduleconfig/mqtt#encryption-enabled) is set to true, the payload of the MeshPacket will remain encrypted with the key for the specified channel.
|
||||
|
||||
#### JSON topic
|
||||
If [JSON is enabled](/docs/settings/moduleconfig/mqtt/#json-enabled), packets from the following [port numbers](/docs/development/firmware/portnum) are serialized to JSON: `TEXT_MESSAGE_APP`, `ENVIRONMENTAL_MEASUREMENT_APP`, `NODEINFO_APP` and `POSITION_APP`. These are then forwarded to the topic:
|
||||
|
||||
`msh/2/json/CHANNELNAME/USERID`.
|
||||
|
||||
An example of a received `NODEINFO_APP` message:
|
||||
|
||||
|
|
@ -62,6 +74,22 @@ An example of a received `NODEINFO_APP` message:
|
|||
}
|
||||
```
|
||||
|
||||
The meaning of these fields is as follows:
|
||||
|
||||
- "`id`" is the unique ID for this message.
|
||||
- "`channel`" is the channel index this message was received on.
|
||||
- "`from`" is the unique node number of the node on the mesh that sent this message, represented as a signed decimal number.
|
||||
- "`id`" inside the payload of a `NODEINFO_APP` message is the user ID of the node that sent it, which is currently just the hexadecimal representation of the node number.
|
||||
- "`hardware`" is the [hardware model](https://github.com/meshtastic/protobufs/blob/master/meshtastic/mesh.proto#L215) of the node sending the `NODEINFO_APP` message.
|
||||
- "`longname`" is the long name of the device that sent the `NODEINFO_APP` message.
|
||||
- "`shortname`" is the short name of the device that sent the `NODEINFO_APP` message.
|
||||
- "`sender`" is the user ID of the gateway device, which is in this case the same node that sent the `NODEINFO_APP` message (the hexadecimal value `7efeee00` represented by an integer in decimal is `2130636288`).
|
||||
- "`timestamp`" is the Unix Epoch when the message was received, represented as an integer in decimal.
|
||||
- "`to`" is the node number of the destination of the message. In this case, "-1" means it was a broadcast message (this is the decimal integer representation of `0xFFFFFFFF`).
|
||||
- "`type`" is the type of the message, in this case it was a `NODEINFO_APP` message.
|
||||
|
||||
The "from" field can thus be used as a stable identifier for a specific node. Note that (like the "`id`" and "`to`" fields) in JSON this is a signed value, whereas in protobufs it is unsigned.
|
||||
|
||||
If the message received contains valid JSON in the payload, the JSON is deserialized and added as a JSON object rather than a string containing the serialized JSON.
|
||||
|
||||
**Sent messages** will be checked if the MQTT payload contains a valid JSON-encoded envelope:
|
||||
|
|
@ -90,34 +118,6 @@ Check out [MQTT Settings](/docs/settings/moduleconfig/mqtt) for full information
|
|||
`uplink_enabled` will tell the device to publish mesh packets to MQTT.
|
||||
`downlink_enabled` will tell the device to subscribe to MQTT, and forward any packets from there onto the mesh.
|
||||
|
||||
### Topics
|
||||
|
||||
The "mesh/crypt/CHANNELID/NODEID/PORTID" [topic](https://www.hivemq.com/blog/mqtt-essentials-part-5-mqtt-topics-best-practices) will be used for messages sent from/to a mesh.
|
||||
|
||||
Gateway nodes will forward any MeshPacket from a local mesh channel with uplink_enabled. The packet (encapsulated in a ServiceEnvelope) will remain encrypted with the key for the specified channel.
|
||||
|
||||
For any channels in the local node with downlink_enabled, the gateway node will forward packets from MQTT to the local mesh. It will do this by subscribing to mesh/crypt/CHANNELID/# and forwarding relevant packets.
|
||||
|
||||
If the channelid 'well known'/public it could be decrypted by a web service (if the web service was provided with the associated channel key), in which case it will be decrypted by a web service and appear at "mesh/clear/CHANNELID/NODEID/PORTID". Note: This is not in the initial deliverable.
|
||||
|
||||
#### Service Envelope
|
||||
|
||||
The payload published on mesh/... will always be wrapped in a [ServiceEnvelope protobuf](https://buf.build/meshtastic/protobufs/docs/main:meshtastic#meshtastic.ServiceEnvelope).
|
||||
|
||||
ServiceEnvelope will include the message, and full information about arrival time, who forwarded it, source channel, source mesh id, etc...
|
||||
|
||||
#### NODEID
|
||||
|
||||
The unique ID for a node. A hex string that starts with an ! symbol.
|
||||
|
||||
#### USERID
|
||||
|
||||
A user ID string. This string is either a user ID if known or a nodeid to simply deliver the message to whoever the local user is of a particular device (i.e. person who might see the screen). FIXME, see what riot.im uses and perhaps use that convention? Or use the signal +phone number convention? Or the email address?
|
||||
|
||||
#### CHANNELID
|
||||
|
||||
FIXME, figure out how channelids work
|
||||
|
||||
### Gateway nodes
|
||||
|
||||
Any meshtastic node that has a direct connection to the internet (either via a helper app or installed WiFi/4G/satellite hardware) can function as a "Gateway node".
|
||||
|
|
|
|||
Loading…
Reference in a new issue