Skip to content

Commit

Permalink
Update readme
Browse files Browse the repository at this point in the history
  • Loading branch information
@KomelT
KomelT committed Aug 28, 2024
1 parent 9bed081 commit c27db7f
Show file tree
Hide file tree
Showing 3 changed files with 34 additions and 125 deletions.
159 changes: 34 additions & 125 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,12 +1,7 @@
<h2 align="center">Meshtastic Map</h2>
**Created by:** Liam Cottle
**Forked by:** Tilen Komel

<p align="center">
<a href="https://discord.gg/K55zeZyHKK"><img src="https://img.shields.io/badge/Discord-Liam%20Cottle's%20Discord-%237289DA?style=flat&logo=discord" alt="discord"/></a>
<a href="https://twitter.com/liamcottle"><img src="https://img.shields.io/badge/Twitter-@liamcottle-%231DA1F2?style=flat&logo=twitter" alt="twitter"/></a>
<br/>
<a href="https://ko-fi.com/liamcottle"><img src="https://img.shields.io/badge/Donate%20a%20Coffee-liamcottle-yellow?style=flat&logo=buy-me-a-coffee" alt="donate on ko-fi"/></a>
<a href="./donate.md"><img src="https://img.shields.io/badge/Donate%20Bitcoin-3FPBfiEwioWHFix3kZqe5bdU9F5o8mG8dh-%23FF9900?style=flat&logo=bitcoin" alt="donate bitcoin"/></a>
</p>
<h2 align="center">Meshtastic Map</h2>

A map of all Meshtastic nodes heard via MQTT.

Expand All @@ -16,7 +11,7 @@ My version of the map is available at https://map.meshnet.si

## How does it work?

- An [mqtt client](./src/mqtt.js) is persistently connected to `mqtt.meshtastic.org` and subscribed to the `msh/#` topic.
- An [mqtt client](./src/mqtt.js) is persistently connected to `mqtt.meshnet.si` and subscribed to the `si/#` topic.
- All messages received are attempted to be decoded as [ServiceEnvelope](https://buf.build/meshtastic/protobufs/docs/main:meshtastic#meshtastic.ServiceEnvelope) packets.
- If a packet is encrypted, it attempts to decrypt it with the default `AQ==` key.
- If a packet can't be decoded as a `ServiceEnvelope`, it is ignored.
Expand Down Expand Up @@ -47,161 +42,79 @@ My version of the map is available at https://map.meshnet.si
- Meshtastic firmware older than [v2.3.2](https://github.com/meshtastic/firmware/releases/tag/v2.3.2.63df972) reports MQTT nodes as Neighbours.
- This was fixed in [meshtastic/firmware/#3457](https://github.com/meshtastic/firmware/pull/3457), but adoption will likely be slow...

## TODO

- use vuejs build process to make managing code easier
- don't use cdn hosted javascript deps so we can run fully offline
- offline map tiles?
- dedupe packets to prevent spamming database
## Dev

## Install

Clone the project repo.
Clone the project repo:

```
git clone https://github.com/liamcottle/meshtastic-map
git clone https://github.com/KomelT/meshtastic-map
cd meshtastic-map
```

Install NodeJS dependencies
Build Docker images:

```
npm install
docker compose -f docker-compose.dev.yaml build
```

Create a `.env` environment file.
Update environment variables:

```
touch .env
nano docker-compose.yaml
```

Add a database [connection string for prisma](https://www.prisma.io/docs/getting-started/setup-prisma/add-to-existing-project/relational-databases/connect-your-database-typescript-postgresql) to `.env` file.
ENV lists:

```
DATABASE_URL="mysql://root@localhost:3306/meshtastic-map?connection_limit=100"
```
- [MQTT](./mqtt/src/settings.ts)
- [API](./api/src/settings.ts)
- [APP](./app/index.js)

> Note: Some queries are MySQL specific. Other db providers have not been tested.
Migrate the database.
Run:

```
npx prisma migrate dev
docker compose -f docker-compose.dev.yaml up
```

Run the MQTT listener, to save packets to database.
## Run

```
node src/mqtt.js
```
Clone the project repo:

Run the Express Server, to serve the `/api` and Map UI.

```
node src/index.js
# Server running at http://127.0.0.1:8080
```

> Note: You can also use a custom port with `--port 8123`
## Upgrading

Run the following commands from inside the `meshtastic-map` repo.

```
# update repo
git fetch && git pull
# migrate database
npx prisma migrate dev
```

You will now need to restart the `index.js` and `mqtt.js` scripts.

## MQTT Collector

By default, the [MQTT Collector](./src/mqtt.js) connects to the public Meshtastic MQTT server.
Alternatively, you may provide the relevant options shown in the help section below to connect to your own MQTT server along with your own decryption keys.

```
node src/mqtt.js --help
```

```
Meshtastic MQTT Collector
Collects and processes service envelopes from a Meshtastic MQTT server.
Options
-h, --help Display this usage guide.
--mqtt-broker-url string MQTT Broker URL (e.g: mqtt://mqtt.meshtastic.org)
--mqtt-username string MQTT Username (e.g: meshdev)
--mqtt-password string MQTT Password (e.g: large4cats)
--mqtt-topic MQTT Topic to subscribe to (e.g: msh/#)
--collect-service-envelopes This option will save all received service envelopes to the database.
--collect-text-messages This option will save all received text messages to the database.
--collect-waypoints This option will save all received waypoints to the database.
--collect-neighbour-info This option will save all received neighbour infos to the database.
--collect-map-reports This option will save all received map reports to the database.
--decryption-keys <base64DecryptionKey> ... Decryption keys encoded in base64 to use when decrypting service envelopes.
--purge-interval-seconds number How long to wait between each automatic database purge.
--purge-nodes-unheard-for-seconds number Nodes that haven't been heard from in this many seconds will be purged from the database.
git clone https://github.com/KomelT/meshtastic-map
cd meshtastic-map
```

To connect to your own MQTT server, you could do something like the following;
Build Docker images:

```
node src/mqtt.js --mqtt-broker-url mqtt://mqtt.example.com --mqtt-username username --mqtt-password password --decryption-keys 1PG7OiApB1nwvP+rz05pAQ==
docker compose build
```

## MQTT Connection Status

The map shows a different coloured icon for nodes based on their connection state to MQTT.

- `Green`: Online (connected to MQTT)
- `Blue`: Offline (disconnected from MQTT)

This works by listening to `/stat/!ID` topics on the MQTT server.

When a node connects to MQTT it publishes `online` to the topic, and when the MQTT server detects the client has disconnected (via an [LWT](https://www.hivemq.com/blog/mqtt-essentials-part-9-last-will-and-testament/)) it publishes `offline` to the topic.

The Meshtastic [firmware configures](https://github.com/meshtastic/firmware/blob/279464f96d5139920b017d437501233737daf407/src/mqtt/MQTT.cpp#L330) an [LWT](https://www.hivemq.com/blog/mqtt-essentials-part-9-last-will-and-testament/) (Last Will and Testament), which the MQTT server publishes upon client disconnect.

After a node boots up, there is a ~30 second delay before the `online` state is published.
After a node disconnects from MQTT, there is a ~30 second delay before the `offline` state is published.

This works well when your node connects to MQTT over WiFi, however, when using the `MQTT Client Proxy` feature, your node sends/receives packets to/from your Android/iOS device, and then your device connects to MQTT and proxies the messages.
Update environment variables:

```
Meshtastic Node <-> Android/iOS <-> MQTT
nano docker-compose.yaml
```

Unfortunately, when using that feature your `online` / `offline` states will not work as expected.

As of the time of writing these docs, the mobile devices do not correctly configure the LWT for the node being proxied, and thus do not publish the `offline` state for the node, so you can't detect if your node disconnected from MQTT.

Your node will stay "stuck" in the `online` state in the MQTT server.
ENV lists:

## Docker Compose
- [MQTT](./mqtt/src/settings.ts)
- [API](./api/src/settings.ts)
- [APP](./app/index.js)

A [docker-compose.yml](./docker-compose.yml) is available. You can run the following command to launch everything;
Run:

```
docker compose up
```

This will:
## Updating

- Start a MariaDB database server.
- Run the database migrations.
- Start the MQTT collector.
- Start the Map UI.
- Expose the map on port 8080.
You can just `git pull` or pull new image from Docekr Hub. Migrations will handle DB update.

## Contributing

If you have a feature request, or find a bug, please [open an issue](https://github.com/liamcottle/meshtastic-map/issues) here on GitHub.
If you have a feature request, or find a bug, please [open an issue](https://github.com/Komelt/meshtastic-map/issues) here on GitHub.

## License

Expand All @@ -210,10 +123,6 @@ MIT
## Legal

This project is not affiliated with or endorsed by the Meshtastic project.

The Meshtastic logo is the trademark of Meshtastic LLC.

## References

- https://meshtastic.org/docs/software/integrations/mqtt/
- https://buf.build/meshtastic/protobufs/docs/main:meshtastic
THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
0 docker-compose.dev.yml → docker-compose.dev.yaml
View file
File renamed without changes.
0 docker-compose.yml → docker-compose.yaml
View file
File renamed without changes.

0 comments on commit c27db7f

Please sign in to comment.