@meri-imperiumi/signalk-meshtastic 1.0.0

package/.eslintrc.json

@@ -0,0 +1,6 @@
+{
+  "extends": "airbnb-base",
+  "parserOptions": {
+    "ecmaVersion": 11
+  }
+}

package/.github/workflows/publish.yml

@@ -0,0 +1,30 @@
+name: Publish Node.js Package
+
+on:
+  push:
+    tags:
+      - "*"
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3.0.2
+      - uses: actions/setup-node@v3.1.1
+        with:
+          node-version: 22
+      - run: npm install
+      - run: npm test
+
+  publish-npm:
+    needs: build
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3.0.2
+      - uses: actions/setup-node@v3.1.1
+        with:
+          node-version: 22
+          registry-url: https://registry.npmjs.org/
+      - run: npm publish
+        env:
+          NODE_AUTH_TOKEN: ${{secrets.NPM_TOKEN}}

package/.github/workflows/test.yml

@@ -0,0 +1,21 @@
+name: Node CI
+
+on: [push, pull_request]
+
+jobs:
+  test:
+    name: Run test suite
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        node-version: [22.x]
+    steps:
+    - uses: actions/checkout@v3.0.2
+    - name: Use Node.js ${{ matrix.node-version }}
+      uses: actions/setup-node@v3.1.1
+      with:
+        node-version: ${{ matrix.node-version }}
+    - run: npm install
+    - run: npm test
+      env:
+        CI: true

package/README.md

@@ -0,0 +1,92 @@
+Signal K integration with Meshtastic
+====================================
+
+This plugin enables vessels running [Signal K](https://signalk.org) to interact with the [Meshtastic](https://meshtastic.org) mesh network. Meshtastic allows radio communications between relatively inexpensive LoRa devices over long distances. The Signal K Meshtastic plugin allows seeing telemetry and receiving alerts from your vessel while ashore. It can also control vessel features like digital switching over text message.
+
+If desired, telemetry and position information can also be shared between multiple Meshtastic-using vessels, making it effectively a "pseudo-AIS" system.
+
+![Basic Meshtastic communications](./doc/meshtastic-bequia.png)
+
+Being a mesh network, there is no need for external telecommunications infrastructure or monthly payments. This means communication between Meshtastic devices onboard and on shore can work just as well in the Finnish Archipelago Sea as in the Tuamotus. In more densely populated places communications may benefit from other Meshtastic users relaying the messages, making it possible to communicate with the boat across a city.
+
+This plugin is designed to work with regular unmodified Meshtastic devices and settings. You can keep your boat and other Meshtastic nodes either in the public channel, or [set up your private mesh](https://meshtastic.org/docs/configuration/tips/#not-sharing-your-location). With a private channel the location of your devices won't be visible to the public, and communications between them will be encrypted.
+
+Many different kinds of Meshtastic devices are available, from basic microcontroller boards to ready-to-go consumer devices. Some are entirely standalone with screens and keyboards, and others need a smartphone app.
+
+[Here is a good introduction](https://tech.gillyb.net/understanding-meshtastic-off-grid-communication-made-simple/) to Meshtastic:
+> Picture this: you’re a family is anchored in a bay. Parents are hiking inland, kids are visiting friends on another boat, and you’re on your boat (“Boat Node”) in the middle. When the kids send, “What’s for dinner?”, Meshtastic uses “flood routing” to make sure it reaches everyone.
+> Here’s how it works:
+> - The kids’ node sends the message.
+> - Boat Node receives it and decides, “This is new—let’s pass it on!”
+> - Boat Node rebroadcasts the message.
+> - Parents’ node, unable to hear the kids directly, receives it through Boat Node.
+
+## Status
+
+In production use on several boats.
+
+## Features
+
+* Connect to a Meshtastic node
+  * Keep a persistent database of all seen Meshtastic nodes
+* Update Meshtastic node position from Signal K GNSS position
+* Send Signal K alerts as Meshtastic text messages to crew
+  * MOB alerts (for example from [signalk-mob-notifier](https://github.com/meri-imperiumi/signalk-mob-notifier)) also send a waypoint to the MOB beacon
+* Control Signal K with Meshtastic direct messages:
+  * Share Meshtastic waypoints for AIS targets (_"Waypoint DH8613"_)
+  * Control digital switching (_"Turn decklight on"_). Opt-in.
+* Share weather station data from Signal K (wind, temperature, etc) over Meshtastic. Opt-in.
+* Show position-sharing Meshtastic nodes as vessels in Freeboard etc. Opt-in.
+  * Associate Meshtastic nodes with other (AIS) vessels based on the `Some node name DE <callsign>` pattern
+
+## Planned features
+
+* Guard mode to alert if the tracked dinghy moves
+* Keeping a mileage log for the dinghy
+* More text commands over Meshtastic to query vessel status etc
+
+## Requirements
+
+* This plugin running inside your Signal K installation
+* One [Meshtastic device](https://meshtastic.org/docs/hardware/devices/) running and connected to the same network (typically boat WiFi) as Signal K. This should be an [ESP32 based](https://meshtastic.org/docs/hardware/devices/heltec-automation/lora32/?heltec=v3) device for WiFi connectivity
+* At least one additional Meshtastic device for the crew ashore. [Seeed T1000-e](https://meshtastic.org/docs/hardware/devices/seeed-studio/sensecap/card-tracker/) is a great option, but any battery-powered Meshtastic device will work. Having a device for each crew member is even better. In busy areas these should be set to [`CLIENT_MUTE` role](https://meshtastic.org/blog/choosing-the-right-device-role/)
+* Optionally, a Meshtastic GPS tracker device installed in the dinghy
+* Optionally, a [Meshtastic mast-top repeater](https://www.printables.com/model/1396221-meshtastic-boat-module-masthead) for greatly increased communications range
+
+LoRa is line-of-sight communications quite similarly to VHF. Communications range would greatly benefit from a Meshtastic repeater installed high in the mast. Similarly, repeaters on nearby hills or high buildings can be helpful. But just with the boat node and the node carried by crew it should be possible to reach ranges of over 1km. We've been able to communicate at over 8km distances in our early tests in Curacao.
+
+**Please note** that this plugin connects to the "boat node" as a client, meaning that while Signal K is running, the regular Meshtastic client app _won't be able to connect to the same device_. It is a good idea to [enable remote administration](https://meshtastic.org/docs/configuration/radio/security/#admin-key) so that you can modify the settings of the device over LoRa.
+
+## Getting started
+
+* Configure your "boat Meshtastic node" device so that it is connected to your boat network
+* If you have a valid Ship Station License, add your callsign to the long name of the node. Typical pattern is `<Vessel name> DE <Callsign>`, for example _"Lille Oe DE DH8613"_<br>
+  (yes, you need to use `DE` also for non-German vessels. This is radio slang for "this is", not a country code)
+* Install and enable this plugin, and set up the connection details (IP address etc)
+* Wait for some minutes for the plugin to see nearby Meshtastic nodes
+* Configure plugin and set appropriate roles for the crew and dinghy tracker Meshtastic devices
+
+![](./doc/config-crew-role.png)
+
+## Telemetry sent to Meshtastic
+
+If enabled, your "boat node" will transmit the following telemetry to Meshtastic. This enables tracking various important metrics about your boat also remotely. They are visible in the device details in your Meshtastic app:
+
+![](./doc/telemetry.png)
+
+Metrics used:
+
+* Temperature (from `environment.outside.temperature`)
+* Relative humidity (from `environment.outside.relativeHumidity`)
+* Barometric pressure (from `environment.outside.pressure`)
+* Wind direction (from `environment.wind.directionTrue`)
+* Wind speed (median of last ten minutes from `environment.wind.speedOverGround`)
+* Battery voltage (from `electrical.batteries.house.voltage`)
+* Battery current (from `electrical.batteries.house.current`)
+* If anchored, distance to anchor (from `navigation.anchor.distanceFromBow`)
+* If not anchored, distance is water depth (from `environment.depth.belowSurface`)
+
+## Changes
+
+* 1.0.0 (2025-09-11)
+  - Initial release with HTTP and TCP transports

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@meri-imperiumi/signalk-meshtastic",
+  "version": "1.0.0",
+  "description": "Signal K plugin for interfacing with the Meshtastic LoRa mesh network",
+  "scripts": {
+    "test": "eslint ."
+  },
+  "keywords": [
+    "meshtastic",
+    "signalk-node-server-plugin",
+    "signalk-category-ais",
+    "signalk-category-hardware"
+  ],
+  "main": "plugin/index.js",
+  "signalk-plugin-enabled-by-default": false,
+  "author": "Henri Bergius <henri.bergius@iki.fi>",
+  "license": "GPLV3",
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@bufbuild/protobuf": "^2.6.0",
+    "@meshtastic/core": "^2.6.7",
+    "@meshtastic/transport-http": "^0.2.5",
+    "@meshtastic/transport-node": "^0.0.2"
+  },
+  "devDependencies": {
+    "eslint": "^8.57.1",
+    "eslint-config-airbnb-base": "^15.0.0",
+    "eslint-plugin-import": "^2.32.0"
+  },
+  "engines": {
+    "node": ">=22.0.0"
+  }
+}

package/plugin/commands/index.js

@@ -0,0 +1,37 @@
+exports.ping = require('./ping');
+exports.switching = require('./switching');
+exports.waypoint = require('./waypoint');
+
+exports.isFromCrew = (msg, settings) => {
+  const crew = settings.nodes
+    .filter((node) => {
+      if (node.role === 'crew') {
+        return true;
+      }
+      return false;
+    })
+    .map((node) => node.node);
+  if (crew.indexOf(msg.from) !== -1) {
+    return true;
+  }
+  return false;
+};
+
+exports.help = {
+  crewOnly: false,
+  example: 'Help',
+  accept: (msg) => (msg.data.toLowerCase() === 'help'),
+  handle: (msg, settings, device) => {
+    const commands = Object.keys(exports).filter((cmd) => {
+      if (cmd === 'isFromCrew') {
+        return false;
+      }
+      if (!exports.isFromCrew(msg, settings) && exports[cmd].crewOnly) {
+        return false;
+      }
+      return true;
+    })
+      .map((cmd) => exports[cmd].example);
+    return device.sendText(`Commands: ${commands.join(', ')}`, msg.from, true, false);
+  },
+};

package/plugin/commands/ping.js

@@ -0,0 +1,6 @@
+module.exports = {
+  crewOnly: false,
+  example: 'Ping',
+  accept: (msg) => (msg.data.toLowerCase() === 'ping'),
+  handle: (msg, settings, device) => device.sendText('Pong', msg.from, true, false),
+};

package/plugin/commands/switching.js

@@ -0,0 +1,33 @@
+module.exports = {
+  crewOnly: true,
+  example: 'Turn <switch name> on',
+  accept: (msg, settings) => {
+    const switching = msg.data.match(/turn ([a-z0-9]+) (on|off)/i);
+    if (settings.communications
+      && settings.communications.digital_switching
+      && switching) {
+      return true;
+    }
+    return false;
+  },
+  handle: (msg, settings, device, app) => {
+    const switching = msg.data.match(/turn ([a-z0-9]+) (on|off)/i);
+    const light = switching[1];
+    const value = switching[2] === 'on';
+    return new Promise((resolve, reject) => {
+      app.putSelfPath(`electrical.switches.${light}.state`, value, (res) => {
+        if (res.state !== 'COMPLETED') {
+          return;
+        }
+        if (res.statusCode !== 200) {
+          reject(new Error(res.message));
+          return;
+        }
+        resolve();
+        device.sendText(res.message, msg.from, true, false)
+          .catch((e) => app.error(`Failed to send message: ${e.message}`));
+      });
+    })
+      .then(() => device.sendText(`OK, ${light} is ${switching[2]}`, msg.from, true, false));
+  },
+};

package/plugin/commands/waypoint.js

@@ -0,0 +1,56 @@
+const { vesselIcon } = require('../waypoint');
+
+const regex = /waypoint ([a-z0-9]+)( ([0-9]+)h)?/i;
+
+module.exports = {
+  crewOnly: true,
+  example: 'Waypoint <callsign or boat name>',
+  accept: (msg) => {
+    // FIXME: Add support for vessel names with spaces
+    const waypointTgt = msg.data.match(regex);
+    if (waypointTgt) {
+      return true;
+    }
+    return false;
+  },
+  handle: (msg, settings, device, app, create, Protobuf) => {
+    const waypointTgt = msg.data.match(regex);
+    const identifier = waypointTgt[1];
+    const length = waypointTgt[3] || 1;
+    const waypointVesselCtx = Object.keys(app.signalk.root.vessels)
+      .find((vesselCtx) => {
+        const vessel = app.signalk.root.vessels[vesselCtx];
+        const lIdentifier = identifier.toLowerCase();
+        if (vessel.mmsi === identifier) {
+          return true;
+        }
+        if (vessel.name && vessel.name.toLowerCase() === lIdentifier) {
+          return true;
+        }
+        if (vessel.communication
+          && vessel.communication.callsignVhf
+          && vessel.communication.callsignVhf.toLowerCase() === lIdentifier) {
+          return true;
+        }
+        return false;
+      });
+    if (!waypointVesselCtx) {
+      return device.sendText(`Unable to find vessel ${identifier}`, msg.from, true, false);
+    }
+    const waypointVessel = app.signalk.root.vessels[waypointVesselCtx];
+    if (!waypointVessel.navigation.position.value
+      || !waypointVessel.navigation.position.value.latitude) {
+      return device.sendText(`Vessel ${identifier} has no known position`, msg.from, true, false);
+    }
+    const setWaypointMessage = create(Protobuf.Mesh.WaypointSchema, {
+      id: waypointVessel.mmsi,
+      latitudeI: Math.floor(waypointVessel.navigation.position.value.latitude / 1e-7),
+      longitudeI: Math.floor(waypointVessel.navigation.position.value.longitude / 1e-7),
+      expire: Math.floor((new Date().getTime() / 1000) + (length * 60 * 60)),
+      name: waypointVessel.name,
+      description: `AIS vessel ${waypointVessel.mmsi}`,
+      icon: vesselIcon(waypointVessel),
+    });
+    return device.sendWaypoint(setWaypointMessage, 'broadcast', 0);
+  },
+};