From 3d4bb4b609944f4fca845f682dc25a9d7a193ceb Mon Sep 17 00:00:00 2001 From: Pablo Vitasso <4544017+pavelw@users.noreply.github.com> Date: Tue, 5 Dec 2023 17:32:56 +0100 Subject: [PATCH 1/3] add node-red-contrib-meshtastic plugin --- docs/software/mqtt/nodered.mdx | 55 +++++++++++++++++++++++++++------- 1 file changed, 45 insertions(+), 10 deletions(-) diff --git a/docs/software/mqtt/nodered.mdx b/docs/software/mqtt/nodered.mdx index 51261a46..e50f1648 100644 --- a/docs/software/mqtt/nodered.mdx +++ b/docs/software/mqtt/nodered.mdx @@ -5,7 +5,43 @@ sidebar_label: Node-RED sidebar_position: 3 --- -### Using MQTT with Node-RED +## Using MQTT with Node-RED + +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. + + +### Enabling MQTT + +Use http://client.meshtastic.org/ , the python CLI, or an Apple or Android app to connect to your device and adjust these settings. + +Step one: +Enable and enter network SSID/PSK. + +- Settings--> Radio Config--> Network; Save. +- Set MQTT server address. +- Settings--> Module Config--> MQTT config; Verify Encryption Enabled is OFF. +- (optional) Turn JSON Output Enabled ON. Save. +- 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. + + +### Using Node-RED with Meshtastic +Now, there are three possible approaches: + +1. Using JSON messages. +2. Using protobuf with a converter node. +3. Using protobuf with locally saved proto files + +Be aware that JSON option is somewhat less supported: +> JSON was only ever intended to be a convenience for folks wanting to consume data in things like Home Assistant. + +> Protobufs are mesh native. + +#### 1. Using JSON messages +Make sure that option *JSON Output Enabled* is set in MQTT module options. Below is a valid JSON envelope for information sent by MQTT to a device for broadcast onto the mesh. @@ -16,21 +52,20 @@ Below is a valid JSON envelope for information sent by MQTT to a device for broa "payload": text or a json object go here } ``` +#### 2. Using protobuf with a converter node +Install Node-Red plug-in: +https://flows.nodered.org/node/@meshtastic/node-red-contrib-meshtastic -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. +More info and example flow is in the plug-in source repository: +https://github.com/scruplelesswizard/meshtastic-node-red -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--> Radio 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. -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. - -Step three: install Node-RED plug-ins to your node-RED application for an embedded MQTT server and a protobuf decoder. +#### 3. Using protobuf with locally saved proto files +Install Node-RED plug-ins to your Node-RED application for an embedded MQTT server and a protobuf decoder. https://flows.nodered.org/node/node-red-contrib-aedes https://flows.nodered.org/node/node-red-contrib-protobuf -Drag, drop, and wire the nodes like this. For this example, I ran node-RED on a Windows machine. Note that file paths might be specified differently on different platforms. MQTT server wild cards are usually the same. A "+" is a single level wildcard for a specific topic level. A "#" is a multiple level wildcard that can be used at the end of a topic filter. The debug messages shown are what happens when the inject button sends a JSON message with a topic designed to be picked up by the specified Meshtastic device and then having it rebroadcast the message. +Drag, drop, and wire the nodes like this. For this example, I ran Node-RED on a Windows machine. Note that file paths might be specified differently on different platforms. MQTT server wild cards are usually the same. A "+" is a single level wildcard for a specific topic level. A "#" is a multiple level wildcard that can be used at the end of a topic filter. The debug messages shown are what happens when the inject button sends a JSON message with a topic designed to be picked up by the specified Meshtastic device and then having it rebroadcast the message. [](/documents/mqtt/NodeRedTwo.jpg) [](/documents/mqtt/NodeRedThree.jpg) From ef9647e8d7d2eebefa1edbe4cef78349ca2fc085 Mon Sep 17 00:00:00 2001 From: Pablo Vitasso <4544017+pavelw@users.noreply.github.com> Date: Thu, 14 Dec 2023 11:02:50 +0100 Subject: [PATCH 2/3] implemented feedback of @scruplelesswizard --- docs/software/mqtt/nodered.mdx | 54 ++++++++++++++++++++++------------ 1 file changed, 36 insertions(+), 18 deletions(-) diff --git a/docs/software/mqtt/nodered.mdx b/docs/software/mqtt/nodered.mdx index e50f1648..db295454 100644 --- a/docs/software/mqtt/nodered.mdx +++ b/docs/software/mqtt/nodered.mdx @@ -16,31 +16,44 @@ I will use this platform as a practical example on how to interface with the MQT Use http://client.meshtastic.org/ , the python CLI, or an Apple or Android app to connect to your device and adjust these settings. -Step one: -Enable and enter network SSID/PSK. -- Settings--> Radio Config--> Network; Save. -- Set MQTT server address. -- Settings--> Module Config--> MQTT config; Verify Encryption Enabled is OFF. -- (optional) Turn JSON Output Enabled ON. Save. -- Go to Channel Editor and set Uplink and Downlink enabled to True. Save. +1. Settings--> Radio Config--> Network + - On the node that will act as the gateway between the mesh and MQTT enable a network connection (i.e. Wifi, Ethernet). + - 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. +2. Settings--> Module Config--> MQTT config + - Configure the MQTT gateway's network configuration. + - Verify Encryption Enabled is OFF. + - (optional) Turn JSON Output Enabled ON. + - Save +3. Channel Editor + - Go to Channel Editor and enable Uplink and Downlink on the channels you wish to publish to MQTT. + - Save ### Using Node-RED with Meshtastic -Now, there are three possible approaches: +There are three common approaches: -1. Using JSON messages. -2. Using protobuf with a converter node. -3. Using protobuf with locally saved proto files +1. Using JSON-encoded messages +2. Using protobuf-encoded messages with the Meshtastic decode node +3. Using protobuf-encoded messages with a protobuf decode node and the Meshtastic protobuf definitions -Be aware that JSON option is somewhat less supported: -> JSON was only ever intended to be a convenience for folks wanting to consume data in things like Home Assistant. +The JSON output only publishes the following subset of the messages on a Meshtastic network +- Text Message +- Telemetry + - Device Metrics + - Environment Metrics + - Power Metrics +- Node Info +- Position +- Waypoint +- Neighbor Info + +> JSON is intended to be a convenience for consuming data in other applications like Home Assistant. > Protobufs are mesh native. -#### 1. Using JSON messages +#### 1. Using JSON-encoded messages Make sure that option *JSON Output Enabled* is set in MQTT module options. Below is a valid JSON envelope for information sent by MQTT to a device for broadcast onto the mesh. @@ -52,15 +65,20 @@ Below is a valid JSON envelope for information sent by MQTT to a device for broa "payload": text or a json object go here } ``` -#### 2. Using protobuf with a converter node +#### 2. Using protobuf-encoded messages with the Meshtastic decode node Install Node-Red plug-in: https://flows.nodered.org/node/@meshtastic/node-red-contrib-meshtastic -More info and example flow is in the plug-in source repository: +More info is in the plug-in source repository. + +There is an example flow using this mechanism available https://github.com/scruplelesswizard/meshtastic-node-red -#### 3. Using protobuf with locally saved proto files +#### 3. Using protobuf-encoded messages with a protobuf decode node and the Meshtastic protobuf definitions + + 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. + Install Node-RED plug-ins to your Node-RED application for an embedded MQTT server and a protobuf decoder. https://flows.nodered.org/node/node-red-contrib-aedes https://flows.nodered.org/node/node-red-contrib-protobuf From 2289a9ff209ffb01407acafbc0b5c422a8c773c4 Mon Sep 17 00:00:00 2001 From: Pablo Vitasso <4544017+pavelw@users.noreply.github.com> Date: Thu, 14 Dec 2023 11:06:37 +0100 Subject: [PATCH 3/3] small typo fix --- docs/software/mqtt/nodered.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/software/mqtt/nodered.mdx b/docs/software/mqtt/nodered.mdx index db295454..17db1290 100644 --- a/docs/software/mqtt/nodered.mdx +++ b/docs/software/mqtt/nodered.mdx @@ -38,7 +38,7 @@ There are three common approaches: 2. Using protobuf-encoded messages with the Meshtastic decode node 3. Using protobuf-encoded messages with a protobuf decode node and the Meshtastic protobuf definitions -The JSON output only publishes the following subset of the messages on a Meshtastic network +The JSON output only publishes the following subset of the messages on a Meshtastic network: - Text Message - Telemetry - Device Metrics