Skip to main content

Meshtastic smart home integration, free and open source

Meshtastic integration for Gladys Assistant

Meshtastic LoRa mesh: nodes, battery, telemetry, received and sent text messages.

View on GitHubAll integrations

Brings your Meshtastic LoRa mesh into Gladys: one device per node (online, last heard, signal, hops, battery, voltage, distance from home, temperature, humidity, pressure), a scene trigger on every text message received and a scene action to send one.

Developed without LoRa hardware: tested against the official meshtasticd firmware in simulated-radio mode, over TCP and over MQTT. Feedback welcome on the Gladys forum.

What you get​

  • Devices: every node your node knows is offered in the Discovery tab, named as on the mesh (long name, !xxxxxxxx id). Add the ones you care about. Each one gets:
    • Online (heard within the delay you choose) and Last heard (date and time);
    • Signal (direct reception): 0 to 5, from the SNR of the last packet heard directly (no relay);
    • Hops away: how many relays the last packet went through;
    • Battery and Battery voltage, when the node reports them (a node on mains power reads 100 %);
    • Distance from home in km, when the node shares its position and your Gladys house is located;
    • Temperature, Humidity, Pressure, when the node has an environment sensor.
  • Scene trigger "Message received": a text message arrived on a channel, or directly to your node. Filter by channel (or "Direct message") and by sender node; the text, the sender name, its id and the channel are available as variables for the next actions (send it on Telegram, say it out loud...).
  • Scene action "Send a message": sends a text on a channel, or directly to one node. Cut to 200 bytes, the radio limit.
  • Widget "Meshtastic mesh": your nodes with battery and last heard, the last message received, and a Send a message button.
  • Check the connection button on the integration page.

The integration never changes the configuration of your radio.

Requirements​

  • Gladys Assistant 5.2.0 or later.
  • Either a node reachable on the network, on TCP port 4403: an ESP32 board on Wi-Fi or Ethernet with the network API on, or a Linux host running meshtasticd;
  • or a local MQTT broker the MQTT module of a node publishes to, with JSON output on (mqtt.json_enabled). JSON is not available on nRF52 boards (RAK4631, T-Echo...): use TCP with another node, or an ESP32 node as gateway.
  • USB serial is not supported: the integration runs in a container, without access to the USB ports.

Installation​

  1. In Gladys, open Integrations → Install from GitHub and enter https://github.com/guim31/gladys-meshtastic.
  2. Open the integration, choose the connection and fill in its fields, save.
  3. Press Check the connection, then open the Discovery tab and add your nodes.

Gladys asks for the location of your house at installation: it is only used for the distance feature, and never leaves your Gladys.

Configuration​

FieldUse
ConnectionTCP to a node (recommended: full node list, channel names, direct messages) or MQTT broker (JSON).
Node address (TCP)IP address or host name of the node, e.g. 192.0.2.40. Port 4403 unless changed.
Broker addressmqtt://host:1883 or mqtts://host:8883, with its user name and password if any.
Root topicThe root topic of the node's MQTT module, msh by default. The firmware adds the region (msh/EU_868/2/json/...).
Sending node (MQTT)Id (!a1b2c3d4) of the node that sends your messages over MQTT. Empty: the last node heard.
Offline afterA node not heard for this long is shown offline (2 hours by default; nodes send telemetry every 30 minutes by default).
LanguageLanguage of the feature names and of the messages of the integration.

TCP​

On the node, turn on Wi-Fi or Ethernet in the network settings (the network API listens on port 4403). A node accepts one TCP client at a time: while Gladys is connected, the Meshtastic app cannot connect to the same node over Wi-Fi (Bluetooth still works). The integration reconnects by itself every 15 seconds after a cut.

MQTT​

On the gateway node: MQTT module on, address of your local broker, JSON output on, and uplink enabled on the channels to follow. The integration subscribes to <root>/# and reads the .../2/json/... topics; encrypted packets are ignored. Do not point it at the public broker mqtt.meshtastic.org: it carries the whole world.

To send over MQTT, the gateway needs a channel named mqtt with downlink enabled (its key does not matter), then a reboot; that is how the firmware accepts JSON messages to send. Put its id in Sending node if several nodes publish to the broker.

Devices and features​

A feature appears only when the node has reported it when you add it (battery, position, environment sensor). If one appears later, Gladys shows Update next to the node in the Discovery tab.

  • The signal is the one of the last packet heard directly by your node: a node always heard through relays keeps no value. Scale: 5 for an SNR of 5 dB or more, 4 from 0 dB, 3 from -5 dB, 2 from -10 dB, 1 below.
  • Hops away counts the relays of the last packet (0: heard directly).
  • The node you are connected to over TCP is always online while the connection is up.
  • After a restart, a node not heard yet is shown offline only once the offline delay has passed.

Scenes​

Message received​

Fires once per message, even when it is heard several times (relays, several MQTT gateways). Filters:

  • Channel: a channel index (0 is the primary channel), or Direct message;
  • Sender node: one of your node devices.

Variables: Message text, Sender name (its name in Gladys if you added it, else on the mesh), Sender node id, Channel (0...7 or direct). Messages you send from Gladys do not fire it.

Send a message​

Fields: the message, the channel (index on your node), and optionally a node for a direct message. Outputs: Sent, Cut to 200 bytes, Sentence (e.g. "Message sent to channel 0."). The action fails, with a clear message, when the text is empty or the mesh not connected.

Widget​

Meshtastic mesh shows the nodes you added (online first, with battery and how long ago they were heard), the last message received, and a Send a message button opening a small form (text and channel). Each block can be hidden in the widget settings: Show the last message, Show the send button, Hide offline nodes.

Limits​

  • Developed and tested without LoRa hardware, against meshtasticd in simulated-radio mode: feedback welcome.
  • No USB serial, no Bluetooth: TCP or MQTT only.
  • Over MQTT, only what a gateway publishes in JSON is seen; no channel names, and a direct message is sent only if the gateway can reach the node.
  • Waypoints, traceroutes, neighbor info and other modules are not shown.
  • A text is limited to 200 bytes (about 200 Latin letters, fewer with accents or emoji).

Privacy and network​

Everything stays on your local network: the integration talks only to your node or to your broker. Received messages are kept in memory (the last 20, for the widget) and never written to disk. The MQTT client id is stored in /data. The broker password is never written in the logs.

Troubleshooting​

  • "The Meshtastic node does not answer on TCP": check the address, that Wi-Fi or Ethernet is on, and that the Meshtastic app is not connected to the node over Wi-Fi at the same time.
  • Connected over MQTT but no node: check the root topic and that JSON output is on (mqtt.json_enabled).
  • "No gateway heard on MQTT yet": the integration learns the topic to send to from the traffic; wait for a first packet.
  • A message is not sent over MQTT: the gateway needs a channel named mqtt with downlink enabled, then a reboot.
  • Detailed logs: start the integration with LOG_LEVEL=debug.

Credits​

Meshtastic® is a registered trademark of Meshtastic LLC. This integration is not affiliated with or endorsed by Meshtastic LLC. It reads the public client API (protobuf field numbers of meshtastic/protobufs) and the JSON format of the firmware, without reusing their code.

Configuration settings​

These are the settings Meshtastic asks for in its configuration screen in Gladys.

SettingTypeRequiredDescription
Connection to the meshsectionNoEither TCP to one node on Wi-Fi or Ethernet (or meshtasticd), or the JSON its MQTT module publishes. USB serial is not supported.
ConnectionselectYes
Node address (TCP)stringNoIP address or host name of the node, with its network API on. The node accepts one TCP client at a time.
TCP portnumberNo
MQTT brokersectionNoOnly with the MQTT connection: a local broker the node's MQTT module publishes to, with JSON output on (not available on nRF52 boards).
Broker addressstringNo
User namestringNo
PasswordsecretNo
Accept a self-signed certificate (mqtts)booleanNo
Root topicstringNoThe root topic of the node's MQTT module (msh by default); the region is added by the firmware.
Sending node (MQTT)stringNoId of the node that has a channel named mqtt with downlink on, to send messages. Empty: the last node heard on MQTT.
OptionssectionNo
Offline afterselectNoA node not heard for this long is shown offline. Nodes send their telemetry every 30 minutes by default.
Language of the textsselectNoLanguage of the feature names and of the texts the integration produces.

How to install Meshtastic in Gladys​

  1. In Gladys, open Integrations: Meshtastic appears in the catalog, next to the native integrations, with a community badge.
  2. Click Install. Gladys pulls the Docker image (ghcr.io/guim31/gladys-meshtastic:1.0.0), starts it in a sandbox isolated from the core, and generates the integration's interface (devices, discovery and configuration).
  3. Open the Configuration screen of the integration, fill in the settings, and save.
  4. You can also install it directly from its repository URL: https://github.com/guim31/gladys-meshtastic.

Meshtastic requires Gladys >=5.2.0. The catalog inside Gladys refreshes every hour, so a new version becomes available at most one hour after its release.

Not running Gladys yet? It is free and open source: follow the installation guide to get started.

About external integrations​

Meshtastic is an external integration: a community integration packaged as a Docker container and published on GitHub, that Gladys installs in one click and runs in a sandbox isolated from its core. It is published and maintained by guim31, not by the Gladys core team.

Subscribe to the Gladys Assistant newsletter

A few emails per month about new releases and project news. Sent by Pierre-Gilles Leymarie, founder of the project. Unsubscribe anytime 🙂
Last updated on