mirror of
https://github.com/meshtastic/meshtastic.git
synced 2025-02-02 08:42:11 -08:00
Ben Lipsey
GitHub
commit
49619622b1
|
|
@ -9,28 +9,28 @@ sidebar_position: 6
|
|||
|
||||
Meshtastic networks in different locations beyond the reach of LoRa can be easily bridged together using MQTT. The simplest option is to connect your mesh to the official Meshtastic MQTT broker. This makes your devices appear on the world map, and provides a copy of your mesh traffic, translated into JSON. All you have to do to join the public MQTT server is to Enable MQTT and set Uplink and Downlink on the channels that you want to share over MQTT. The default device configuration using the public MQTT Server is encrypted.
|
||||
|
||||
You can also share channel settings with a remote network. 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. You can also specify your own private MQTT broker and specify authentication for that broker to bridge several mesh networks together, via the internet (or just a local IP network).
|
||||
You can also share channel settings with a remote network. 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. You can also specify your own private MQTT broker and specify authentication for that broker to bridge several mesh networks together, via the internet (or just a local IP network).
|
||||
|
||||
You can find the settings available for MQTT [here](/docs/settings/moduleconfig/mqtt).
|
||||
|
||||
:::important
|
||||
When MQTT is turned on, you are potentially broadcasting your entire mesh's traffic onto the public internet. This includes messages and position information.
|
||||
:::
|
||||
|
||||
## Software Integrations
|
||||
|
||||
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 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](https://www.hivemq.com/blog/mqtt-essentials-part-5-mqtt-topics-best-practices)
|
||||
|
||||
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:
|
||||
Each device that is connected to MQTT will publish its MQTT state (`online`/`offline`) to:
|
||||
|
||||
`msh/2/stat/USERID`, where `USERID` is the user ID of the gateway device (the one connected to MQTT).
|
||||
`msh/2/stat/USERID`, where `USERID` is the node ID of the gateway device (the one connected to MQTT).
|
||||
|
||||
For each channel where uplink and/or downlink is enabled two other topics might be used.
|
||||
For each channel where uplink and/or downlink is enabled, two other topics might be used:
|
||||
|
||||
#### Protobufs topic
|
||||
A gateway node will uplink and/or downlink raw ([protobuf](https://developers.google.com/protocol-buffers)) MeshPackets to the topic:
|
||||
|
|
@ -50,7 +50,7 @@ The payload is a raw protobuf, whose definitions for Meshtastic can be found [he
|
|||
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:
|
||||
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`, `TELEMETRY_APP`, `NODEINFO_APP`, `POSITION_APP` and `WAYPOINT_APP`. These are then forwarded to the topic:
|
||||
|
||||
`msh/2/json/CHANNELNAME/USERID`.
|
||||
|
||||
|
|
@ -78,7 +78,7 @@ 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.
|
||||
- "`from`" is the unique node number of the node on the mesh that sent this message.
|
||||
- "`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.
|
||||
|
|
@ -88,7 +88,7 @@ The meaning of these fields is as follows:
|
|||
- "`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.
|
||||
The `from` field can thus be used as a stable identifier for a specific node. Note that in firmware prior to 2.2.0, this is a signed value in JSON, while in firmware 2.2.0 and higher, the JSON values are 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.
|
||||
|
||||
|
|
@ -238,17 +238,12 @@ Below is a valid JSON envelope for information sent by MQTT to a device for broa
|
|||
}
|
||||
```
|
||||
|
||||
Node-RED is a free cross-platform programming tool for wiring together hardware, APIs, and online services developed originally by IBM for IOT. It is widely used for home automation by many non-professional programmers and runs well on Pi's. Node-red has many plug-in modules written by the community. I will use this platform as a practical example on how to interface with the MQTT features of Meshtastic. Everything can be done from GUI's without using command line.
|
||||
Node-RED is a free cross-platform programming tool for wiring together hardware, APIs, and online services developed originally by IBM for IOT. It is widely used for home automation by many non-professional programmers and runs well on Pi's. Node-RED has many plug-in modules written by the community. I will use this platform as a practical example on how to interface with the MQTT features of Meshtastic. Everything can be done from GUI's without using command line.
|
||||
|
||||
Step one: use http://client.meshtastic.org/ one of the Apple apps or the CLI to connect to your device and adjust these settings.
|
||||
Step one: use http://client.meshtastic.org/ , the python CLI, or an Apple or Android app to connect to your device and adjust these settings.
|
||||
Enable and enter network SSID/PSK. Settings--> Device Config--> Network; Save.
|
||||
Set MQTT server address. Settings--> Module Config--> MQTT config; Verify Encryption Enabled is OFF. Turn JSON Output Enabled ON. Save.
|
||||
Go to Channel Editor and set Uplink and Downlink enabled to True. Save. There is currently a bug for setting Uplink and Downlink Saving for the default channel. If you encounter this use the CLI commands:
|
||||
|
||||
```shell
|
||||
meshtastic --ch-index 0 --ch-set uplink_enabled true
|
||||
meshtastic --ch-index 0 --ch-set downlink_enabled true
|
||||
```
|
||||
Go to Channel Editor and set Uplink and Downlink enabled to True. Save.
|
||||
|
||||
Step two: if you don't want to depend on JSON decoding on the device, you can decode the protobuf messages off-device. To do that you will need to get the .proto files from https://github.com/meshtastic/protobufs. They function as a schema and are required for decoding in Node-RED. Save the files where the node-RED application can access them and note the file path of the "mqtt.proto" file.
|
||||
|
||||
|
|
|
|||
Loading…
Reference in a new issue