Skip to content
Back to search

mesh-api

MESH-API — Off-Grid AI & API Router & with MCP server & over 30 API extensions for Meshtastic & MeshCore - Seamlessly connect LM Studio, Ollama, AI Providers , 3rd-party APIs, Agents & Home Assistant to your LoRa mesh. Supports custom commands, Twilio SMS, Discord channel routing, & GPS emergency alerts via SMS, email, or Discord + SO MUCH MORE

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/mr-tbot/mesh-api with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/mr-tbot/mesh-api'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/mr-tbot--mesh-api/badge.svg)](/listings/mr-tbot--mesh-api)

HTML

<a href="/listings/mr-tbot--mesh-api"><img src="/api/listings/mr-tbot--mesh-api/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

1. **Prerequisites** - **Python 3.11+** — Download from [python.org](https://www.python.org/downloads/). During install, check **“Add Python to PATH”**. - **Git** (optional) — [git-scm.com](https://git-scm.com/downloads/win) for cloning, or download the ZIP from GitHub.

2. **Download/Clone** - Clone the repository (or download and extract the ZIP): ```bash git clone https://github.com/mr-tbot/mesh-api.git cd mesh-api ```

3. **Create & Activate a Virtual Environment:** ```bash python -m venv venv .\venv\Scripts\activate ```

4. **Install Dependencies:** ```bash pip install --upgrade pip pip install -r requirements.txt ```

5. **Configure Files:** - Edit `config.json`, `commands_config.json`, and `motd.json` as needed. Refer to the **Configuration** section below. - Or use the **Setup Wizard** on first launch in the WebUI.

6. **Start the Bot:** - Double-click `Run MESH-API - Windows.bat` or run: ```bash python mesh-api.py ```

7. **Access the WebUI Dashboard:** - Open your browser and navigate to [http://localhost:5000/dashboard](http://localhost:5000/dashboard).

---

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 839 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. # MESH-API v0.7.6.0 Beta — Meshtastic + MeshCore Mesh Router & API / AI Bridge
  2. > ## 🎉 Now with full MeshCore support (since v0.7.0)
  3. >
  4. > **You can run MESH-API with EITHER a Meshtastic node, a MeshCore node — or BOTH at the same time, with MESH-API handling cross-network routing between them.** MeshCore is a **first-class, core-owned radio** on equal footing with Meshtastic. Slash commands, the AI assistant, and *every* extension work across both networks, and the WebUI adapts to whichever radios you have connected.
  5. >
  6. > **⚠️ These features are widely untested and I am actively seeking community feedback.** If you run a Meshtastic-only, MeshCore-only, or dual-radio setup, please tell me what works, what breaks, and what you'd like to see — open a [GitHub Issue](https://github.com/mr-tbot/mesh-api/issues). Your real-world reports directly shape the MeshCore implementation going forward.
  7. >
  8. > Also included: a built-in **MCP (Model Context Protocol) server** that turns MESH-API into an agentic backend for AI tools, and a **firmware/software update system**. See the dedicated sections below.
  9. > ### 🆕 What's new
  10. >
  11. > **v0.7.5.0** matures the **MeshCore Bluetooth / Wi-Fi / USB** connection paths: a configured **`ble_pin` now actually pairs** (MESH-API auto-registers a BlueZ pairing agent that supplies it), `ble_pin` is now in the **⚙️ Config** editor and **Setup Wizard**, and the connection banner now shows **why** MeshCore isn't connected (BLE **signal strength**, node-seen-in-scan, and a plain-language hint). It also rolls up a batch of fixes — the **#60 WebUI-save startup crash**, a path-traversal hole, node-name XSS, restored **`/emergency` on LongFast**, plus **Home Assistant `agent_id`** (#61) and opt-in **commands from Telegram** (#59). Building on: **v0.7.4.1** revamps the dashboard **Send a Message** composer — Broadcast/Direct mode tabs, per-network broadcast checkboxes (📡 Meshtastic, 🟣 MeshCore, 🌉 Bridged), and a bridged channel dropdown that now shows **both** routed channels (e.g. `0 → 📡 LongFast + 🟣 Public`) — adds a **Previously Seen** node section with an adjustable staleness threshold, and fixes **MeshCore presence** so addressable contacts no longer drop out of the live node list (activity-based last-heard). **v0.7.4** updated the **first-start Setup Wizard** to walk you through **MeshCore** as well as Meshtastic: a dedicated MeshCore step (serial / TCP / BLE, adverts, channel bridging), a toggle to run a **MeshCore-only / standalone node**, and a **default send-network** selector. The prior **v0.7.3.7** ensured **all extensions route to MeshCore** (GitHub [#59](https://github.com/mr-tbot/mesh-api/issues/59)), and **v0.7.3.6** added a **token-free heartbeat** for named AI endpoints.
  12. >
  13. > 📜 **See the full version history in [CHANGELOG.md](CHANGELOG.md).**
  14. ## ❤️ Support MESH-API Development — Keep the Lights On
  15. MESH-API is built and maintained by **one developer** with the help of AI tools. There is no corporate sponsor, no VC funding — just late nights, community feedback, and a passion for off-grid communication.
  16. If MESH-API has been useful to you — whether you're running it on a Raspberry Pi in your go-bag, bridging your local mesh to Discord, or experimenting with AI on LoRa — **please consider making a donation.** Every contribution, no matter the size, directly fuels continued development, bug fixes, new extensions, and keeping this project free and open-source for everyone.
  17. ### Donate via PayPal (Preferred)
  18. [![Donate via PayPal](https://img.shields.io/badge/Donate-PayPal-blue.svg?logo=paypal&style=for-the-badge)](https://www.paypal.com/donate/?business=7DQWLBARMM3FE&no_recurring=0&item_name=Support+the+development+and+growth+of+innovative+MR_TBOT+projects.&currency_code=USD)
  19. [**Click here to donate via PayPal**](https://www.paypal.com/donate/?business=7DQWLBARMM3FE&no_recurring=0&item_name=Support+the+development+and+growth+of+innovative+MR_TBOT+projects.&currency_code=USD)
  20. ### Crypto Donations
  21. | Currency | Address |
  22. |----------|---------|
  23. | **BTC** | `bc1qalnp0xze5t9nner2754k2pj7yjhkrt3uzvzdvt` |
  24. | **ETH** | `0xAd640c506f5d2368cAF420a117380820C0C5F61C` |
  25. | **XRP** | `rpciwKrQSaRZ1UjPunH8vLJhoM2s4NaYoL` |
  26. | **DOGE** | `DM79aRx58J6RYuWakHjiELWbNJkTTDj1cv` |
  27. **Thank you to everyone who has donated, filed issues, tested pre-releases, and spread the word.** You are what makes this project possible. 🙏
  28. <img width="1151" height="251" alt="MESH-API-HEADER" src="https://github.com/user-attachments/assets/53d213fe-fd3d-4d24-b62d-5620a0c81791" />
  29. **MESH-API** is an experimental project that bridges [Meshtastic](https://meshtastic.org/) (& now [MeshCore](https://meshcore.co.uk/) ) LoRa mesh networks with powerful AI chatbots and 3rd party APIs.
  30. ## What Sets MESH-API Apart?
  31. Most projects in this space stop at being "AI chatbot integrations" — but **MESH-API is much more than that.**
  32. - **Full Router / Mesh Operator**
  33. MESH-API isn’t just talking to an LLM. It’s a **protocol bridge** and **mesh backbone**, designed to let LoRa networks, online (or offline) services, and APIs talk to each other in real time.
  34. - **Not a One-Trick Pony**
  35. Where other tools simply connect to AI, MESH-API is built to **route, translate, and post messages** between different systems and services — making it a true hub for both on-grid and off-grid communication.
  36. - **Expandable by Design**
  37. Any software with a working API can be integrated. That means you can merge in external services, dashboards, or automation platforms, extending the mesh far beyond its original scope.
  38. - **AI-Powered Off-Grid Networks**
  39. MESH-API provides the foundation for **self-sufficient LoRa mesh networks enhanced with AI**, ensuring communication, automation, and decision-making remain possible — even without the internet.
  40. In short, MESH-API bridges the gap between **mesh services** and **online/locally hosted services**, making it a powerful backbone for resilient, intelligent LoRa networks.
  41. > **Disclaimer:**
  42. > This project is **NOT ASSOCIATED** with the official Meshtastic Project. It is provided solely as an extension to add AI and advanced features to your Mesh network.
  43. > **v0.7.4.1 Beta:**
  44. > The 0.7.x line makes MeshCore a first-class radio and adds the MCP server and firmware-update system; v0.7.4.1 revamps the **Send a Message** composer (broadcast/direct mode tabs, multi-network broadcast targeting, bridged dropdown showing both channels), adds a **Previously Seen** node section, and fixes **MeshCore node presence**, building on v0.7.4's MeshCore Setup Wizard and v0.7.3.7's fix so **every extension routes outbound messages to MeshCore as well as Meshtastic**. **These features are still relatively untested in the field — I am actively seeking community feedback.** Run it with a Meshtastic node, a MeshCore node, or both, and please report what works and what breaks. Avoid relying on it for mission‑critical tasks or emergencies; always keep backup communication methods available and use responsibly.
  45. >
  46. > *I am one robot using other robots to write this code. Some features are still untested in the field. Check the GitHub issues for fixes or feedback!*
  47. ---
  48. [![image](https://github.com/user-attachments/assets/bdf08934-3a80-4dc6-8a91-78e33c34db59)](https://meshtastic.org)
  49. The Meshtastic logo trademark is the trademark of Meshtastic LLC.
  50. ## Features
  51. - **Multi-Radio: Meshtastic, MeshCore, or Both** *(New in v0.7.0)*
  52. - **MeshCore is a first-class, core-owned radio** (not an extension) on equal footing with Meshtastic, connecting over serial / TCP / BLE.
  53. - Run a **Meshtastic radio only**, a **MeshCore radio only** (fully standalone — no Meshtastic device required), or **one of each** with MESH-API as a cross-network man-in-the-middle.
  54. - Slash commands, the AI assistant, and **every extension work across both networks**. Send to one network or both at once.
  55. - **WebUI adapts** — per-network connection banner, node **network filter** with collapsible Meshtastic/MeshCore sections, network badges on nodes & messages, distinct map markers, MeshCore group/private channels in the send form, and DMs to MeshCore contacts.
  56. - **MCP (Model Context Protocol) Server** *(New in v0.7.0)*
  57. - Exposes MESH-API core functions **and** extensions as MCP **tools** at `POST /mcp`, so external AI agents (Claude, Perplexity, Hermes, custom) can drive the mesh as an agentic backend. Disabled by default; bearer-token auth. See **[MCP Server](#mcp-server-model-context-protocol)**.
  58. - **Firmware & Software Updates** *(New in v0.7.0)*
  59. - Detects your connected Meshtastic/MeshCore device and notifies you (🔄 Updates badge) when newer **Meshtastic firmware**, **MeshCore firmware**, or **MESH-API** is available, with **stable / beta / alpha** release-channel selection. Optional ESP32 over-USB flashing (off by default).
  60. - **Plugin-Based Extensions System** *(New in v0.6.0)*
  61. - 30 built-in extensions across 7 categories: Communication, Notifications, Emergency/Weather, Ham Radio/Off-Grid, Smart Home, Mesh Bridging, and AI Agents.
  62. - Drop-in plugin architecture — add or remove extensions by copying a folder. No core code changes required.
  63. - Extensions can register slash commands, react to emergencies, observe messages, expose HTTP endpoints, and run background services.
  64. - **WebUI Extensions Manager** — view, enable/disable, and configure extensions from the dashboard.
  65. - See the [Extensions Reference](#extensions-reference) section below for full details on all built-in extensions, or [Developing Custom Extensions](#developing-custom-extensions) to build your own.
  66. - **Multiple AI Providers**
  67. - Support for **Local** models (LM Studio, Ollama), **OpenAI**, **Claude**, **Gemini**, **Grok**, **OpenRouter**, **Groq**, **DeepSeek**, **Mistral**, **Hermes** (Nous Research), generic OpenAI-compatible endpoints, and **Home Assistant** integration.
  68. - **Home Assistant Integration**
  69. - Seamlessly forward messages from a designated channel to Home Assistant’s conversation API. Optionally secure the integration using a PIN.
  70. - **NASA Space Weather Monitoring**
  71. - Track geomagnetic storms, solar flares, coronal mass ejections, and more via NASA's DONKI API. Auto-broadcast significant events to the mesh with configurable Kp index and flare class thresholds. Slash commands: `/spaceweather`, `/solarflare`, `/geomagstorm`.
  72. - **n8n Workflow Automation**
  73. - Bidirectional bridge with [n8n](https://n8n.io) — forward mesh messages and emergencies to n8n webhook triggers, receive workflow outputs on the mesh, list active workflows, and trigger them via slash commands. Enables powerful no-code automation pipelines for your mesh network.
  74. - **Advanced Slash Commands**
  75. - Built‑in commands: suffixed `/about-XY`, `/help-XY`, `/motd-XY`, `/whereami-XY`, `/nodes-XY`, AI commands with your unique suffix (e.g., `/ai-XY`, `/bot-XY`, `/query-XY`, `/data-XY`), unsuffixed `/test`, and unsuffixed `/emergency` (or `/911`), plus custom commands via `commands_config.json`.
  76. - Commands are now case‑insensitive for improved mobile usability.
  77. - New: a per-install randomized alias (e.g. `/ai-9z`) is generated on first run to reduce collisions when multiple bots exist on the same mesh or MQTT network. You can change it in `config.json` (field `ai_command`). All AI commands require this suffix, and other built‑ins (except emergency/911) also require your suffix.
  78. - Strongly encouraged: customize your commands in `commands_config.json` to avoid collisions with other users.
  79. - **Emergency Alerts**
  80. - Trigger alerts that are sent via **Twilio SMS**, **SMTP Email**, and, if enabled, **Discord**.
  81. - Emergency notifications include GPS coordinates, UTC timestamps, and user messages.
  82. - **Enhanced REST API & WebUI Dashboard**
  83. - A modern three‑column layout showing direct messages, channel messages, and available nodes. Stacks on mobile; 3‑wide on desktop. Controls (⌘ Commands, 🧩 Extensions, ⚙️ Config, 📜 Logs) live in the “Send a Message” header (top‑right).
  84. - **Interactive Node Map** — Leaflet.js‑powered map view with markers for all GPS‑enabled nodes. **25 tile providers** including OpenStreetMap, Carto (Light, Dark, Voyager, No‑Label variants), OpenTopoMap, Esri (Street, Satellite, Topo, NatGeo, Light/Dark Gray Canvas, Ocean), Stadia (Stamen Terrain/Toner/Toner Lite/Watercolor, Alidade Smooth/Dark, Outdoors, OSM Bright), Humanitarian OSM, CyclOSM, and OPNVKarte. Defaults to Carto Positron (Light). **Offline map image support** — upload a local map image with lat/lon bounds via settings; Leaflet overlays it as a fully functional map layer with markers, pan, and zoom. Offline detection with fallback notice. Popups include node name, custom name, favorite star, ID, last heard, hop count, DM/PING/PONG buttons, and Google Maps link — all on a single row. Mini DM box over the map includes Send, PING, and PONG on the same row.
  85. - **Collapsible Channel Groups** — Each channel is a toggle‑able group with an unread‑count badge. Click the 📻 header to expand/collapse.
  86. - **Draggable Dashboard** — All major sections (Send Form, Node Map, Message Panels, Discord) can be reordered via ☰ drag handles. The three message columns (DMs, Channels, Nodes) are also independently sortable. Layout order is saved to localStorage. Sections can be hidden/shown from the UI Settings panel.
  87. - **Notification Sounds** — Five built‑in Web Audio API sounds (Two‑Tone Beep, Triple Chirp, Alert Chime, Sonar Ping, Radio Blip) plus a **custom sounds library** supporting multiple uploaded audio files (stored as base64 in localStorage). Separate sound selection for Default, DMs, Channels, and individual nodes — each with its own dropdown populated from built‑in plus all custom sounds. Test button, volume slider, and per‑node sound management in settings.
  88. - **Node Enhancements** — Every node shows DM, PING, and PONG buttons, last‑heard time (📡), beacon time, hop count, distance, Show on Map (fly‑to), and Google Maps link on a single line. **Favorite nodes** — toggle a ⭐ star to pin nodes to the top of the Available Nodes list (persisted in localStorage). **Custom node names** — click ✏️ to assign a logical name displayed in cyan alongside the original shortName. Favorites and custom names also appear in map popup titles and tooltip labels.
  89. - Emoji enhancements: each message has a React button that reveals a compact, hidden emoji picker; choosing an emoji auto‑sends a reaction (DM or channel). The send form includes a Quick Emoji bar that inserts emojis into your draft (does not auto‑send).
  90. - Additional endpoints include `/messages`, `/nodes`, `/connection_status`, `/logs`, `/logs_stream`, `/send`, `/ui_send`, `/commands_info` (JSON commands list), and a new `/discord_webhook` for inbound Discord messages.
  91. - UI customization through settings panel including button theme color, section colors, 25 map tile styles (default: Carto Light), offline map image upload with lat/lon bounds, hue rotation, notification sounds (built‑in or custom library with multiple files), per‑node sound assignments, section visibility toggles, and volume control. An About section with links to Meshtastic, MeshCore, and the project's GitHub and website.
  92. - Config Editor (WebUI): Click the “Config” button in the header to view/edit `config.json`, `commands_config.json`, and `motd.json` in a tabbed editor. JSON is validated before saving; writes are atomic. Some changes may require a restart to take effect.
  93. - Extensions Manager (WebUI): Click the “Extensions” button to view extension status, enable/disable extensions, edit extension configs, and hot‑reload all extensions — all from the browser.
  94. - **Improved Message Chunking & Routing**
  95. - Automatically splits long AI responses into configurable chunks with delays to reduce radio congestion.
  96. - Configurable flags control whether the bot replies to broadcast channels and/or direct messages.
  97. - New: LongFast (channel 0) response toggle — by default the bot will NOT respond on LongFast to avoid congestion. Enable `ai_respond_on_longfast` only if your local mesh agrees.
  98. - Etiquette: Using AI bots on public LongFast is discouraged; keep it off unless you’re on an isolated/private mesh with community consent.
  99. - **Robust Error Handling & Logging**
  100. - Uses UTC‑based timestamps with an auto‑truncating script log file (keeping the last 100 lines if the file grows beyond 100 MB).
  101. - Enhanced error detection (including specific OSError codes) and graceful reconnection using threaded exception hooks.
  102. - **Discord Integration Enhancements**
  103. - Route messages to and from Discord.
  104. - New configuration options and a dedicated `/discord_webhook` endpoint allow for inbound Discord message processing.
  105. - MQTT-aware response gating: set `respond_to_mqtt_messages` to true in `config.json` if you want the bot to respond to messages that arrive via MQTT. Off by default to prevent multiple server responses.
  106. - User‑initiated only: The AI does not auto‑message or greet new nodes; it responds only to explicit user input.
  107. - **Commands modal & startup helper**
  108. - WebUI includes a Commands modal (button in the “Send a Message” header) that lists available commands with descriptions.
  109. - The current alias suffix and a one‑line commands list are printed at startup for easy reference.
  110. - **Windows & Linux Focused**
  111. - Official support for Windows environments with installation guides; instructions for Linux available now - MacOS coming soon!
  112. ---
  113. ![image](https://github.com/user-attachments/assets/8ea74ff1-bb34-4e3e-9514-01a98a469cb2)
  114. > An example of an awesome Raspberry Pi 5 powered mini terminal - running MESH-API & Ollama with HomeAssistant integration!
  115. > - Top case model here by oinkers1: https://www.thingiverse.com/thing:6571150
  116. > - Bottom Keyboard tray model here by mr_tbot: https://www.thingiverse.com/thing:7084222
  117. > - Keyboard on Amazon here: https://a.co/d/2dAC9ph
  118. ---
  119. ## Quick Start (Windows)
  120. 1. **Prerequisites**
  121. - **Python 3.11+** — Download from [python.org](https://www.python.org/downloads/). During install, check **“Add Python to PATH”**.
  122. - **Git** (optional) — [git-scm.com](https://git-scm.com/downloads/win) for cloning, or download the ZIP from GitHub.
  123. 2. **Download/Clone**
  124. - Clone the repository (or download and extract the ZIP):
  125. ```bash
  126. git clone https://github.com/mr-tbot/mesh-api.git
  127. cd mesh-api
  128. ```
  129. 3. **Create & Activate a Virtual Environment:**
  130. ```bash
  131. python -m venv venv
  132. .\venv\Scripts\activate
  133. ```
  134. 4. **Install Dependencies:**
  135. ```bash
  136. pip install --upgrade pip
  137. pip install -r requirements.txt
  138. ```
  139. 5. **Configure Files:**
  140. - Edit `config.json`, `commands_config.json`, and `motd.json` as needed. Refer to the **Configuration** section below.
  141. - Or use the **Setup Wizard** on first launch in the WebUI.
  142. 6. **Start the Bot:**
  143. - Double-click `Run MESH-API - Windows.bat` or run:
  144. ```bash
  145. python mesh-api.py
  146. ```
  147. 7. **Access the WebUI Dashboard:**
  148. - Open your browser and navigate to [http://localhost:5000/dashboard](http://localhost:5000/dashboard).
  149. ---
  150. ## Quick Start (Ubuntu / Linux)
  151. 1. **Prerequisites**
  152. - Python 3.11+ and pip:
  153. ```bash
  154. sudo apt update && sudo apt install -y python3 python3-pip python3-venv git
  155. ```
  156. - Grant serial port access (required for USB-connected Meshtastic devices):
  157. ```bash
  158. sudo usermod -aG dialout $USER
  159. ```
  160. Log out and back in for the group change to take effect.
  161. 2. **Download/Clone**
  162. ```bash
  163. git clone https://github.com/mr-tbot/mesh-api.git
  164. cd mesh-api
  165. ```
  166. 3. **Create & Activate a Virtual Environment:**
  167. ```bash
  168. python3 -m venv venv
  169. source venv/bin/activate
  170. ```
  171. 4. **Install Dependencies:**
  172. ```bash
  173. pip install --upgrade pip
  174. pip install -r requirements.txt
  175. ```
  176. 5. **Configure Files:**
  177. - Edit `config.json`, `commands_config.json`, and `motd.json` as needed. Refer to the **Configuration** section below.
  178. - Or use the **Setup Wizard** on first launch in the WebUI.
  179. 6. **Start the Bot:**
  180. ```bash
  181. python mesh-api.py
  182. ```
  183. 7. **Access the WebUI Dashboard:**
  184. - Open your browser and navigate to [http://localhost:5000/dashboard](http://localhost:5000/dashboard).
  185. ## Quick Start (Docker)
  186. Multi-arch Docker images are published for **linux/amd64** (x86_64) and **linux/arm64** (Raspberry Pi 4/5, Apple Silicon).
  187. 1. **Prerequisites**
  188. - [Docker Engine](https://docs.docker.com/engine/install/) (or Docker Desktop) installed on your host.
  189. - A Meshtastic device connected via USB serial, Wi-Fi, or Bluetooth.
  190. 2. **Prepare the Volume Structure**
  191. - `docker-required-volumes.zip` in the repository contains a ready-to-use `mesh-api/` directory with default configs, all 30 built-in extensions, and empty log files. Unpack it into your working directory:
  192. ```bash
  193. git clone https://github.com/mr-tbot/mesh-api.git
  194. cd mesh-api
  195. unzip docker-required-volumes.zip # creates ./mesh-api/
  196. ```
  197. - Edit the config files inside `mesh-api/config/` before starting:
  198. ```
  199. mesh-api/
  200. ├── config/
  201. │ ├── config.json # Core configuration (AI provider, connection, etc.)
  202. │ ├── commands_config.json # Custom slash commands
  203. │ └── motd.json # Message of the Day
  204. ├── extensions/ # All 30 built-in extensions (add your own here too)
  205. │ ├── __init__.py
  206. │ ├── base_extension.py
  207. │ ├── loader.py
  208. │ ├── discord/
  209. │ ├── telegram/
  210. │ ├── mqtt/
  211. │ └── ... (30 built-in extensions)
  212. └── logs/
  213. ├── script.log
  214. ├── messages.log
  215. └── messages_archive.json
  216. ```
  217. 3. **Pull & Run with Docker Compose**
  218. - Copy the included `docker-compose.yml` to the same directory as your `mesh-api/` folder, then:
  219. ```bash
  220. docker compose pull
  221. docker compose up -d
  222. ```
  223. - **USB Serial devices:** Uncomment the `devices` and `/dev` volume lines in `docker-compose.yml` and set your serial device path (e.g. `/dev/ttyUSB0` or `/dev/ttyACM0`).
  224. - **Wi-Fi connection:** Set `use_wifi: true` and `wifi_host` in `mesh-api/config/config.json` — no device passthrough needed.
  225. 4. **Verify the Container:**
  226. ```bash
  227. docker compose logs -f mesh-api
  228. ```
  229. 5. **Access the WebUI Dashboard:**
  230. - Open your browser and navigate to [http://localhost:5000/dashboard](http://localhost:5000/dashboard).
  231. - On first launch the **Setup Wizard** will guide you through initial configuration.
  232. > **Tip:** To add custom extensions, drop the extension folder into `mesh-api/extensions/` on the host — it's volume-mounted into the container so no rebuild is needed. Restart the container with `docker compose restart` to pick up new extensions.
  233. > **Updating (v0.7.5.5+):** `docker compose pull && docker compose up -d` now updates the built-in extensions too. Because `mesh-api/extensions/` is mounted from the host, earlier images kept running whatever extension code was first copied there, so extension fixes never arrived with a new image. On startup the container now brings the built-in extension code in that folder up to the image's version. Your `config.json` files and any custom extensions are never touched, and every file it replaces is saved first under `mesh-api/extensions/_replaced/<version>/`. To manage extension code yourself, set `MESH_API_SYNC_EXTENSIONS=0` in the container's environment.
  234. ---
  235. ## Supported Mesh Networks
  236. MESH-API supports **two mesh radio platforms** that can operate independently or be **bridged together** for cross-network communication.
  237. ### Meshtastic (Primary)
  238. [Meshtastic](https://meshtastic.org/) is MESH-API's primary mesh network. Connection is handled automatically by the core — just plug in your Meshtastic device and configure the connection method in `config.json`.
  239. | Setting | Description |
  240. |---------|-------------|
  241. | `use_wifi` | Set `true` to connect via TCP/WiFi instead of USB serial |
  242. | `wifi_host` | IP address of your Meshtastic node (when using WiFi) |
  243. | `wifi_port` | TCP port (default `4403`) |
  244. | `serial_port` | USB serial port (e.g. `/dev/ttyUSB0` or `COM3`) — leave empty for auto-detect |
  245. | `serial_baud` | Baud rate (default `460800`) |
  246. | `use_mesh_interface` | Set `true` for direct MeshInterface mode (no serial/WiFi) |
  247. **All MESH-API features** — AI commands, slash commands, emergency alerts, extensions, WebUI dashboard — work natively over the Meshtastic connection.
  248. ### MeshCore (First-Class Radio — v0.7.0)
  249. [MeshCore](https://meshcore.co.uk/) is a lightweight, multi-hop LoRa mesh firmware focused on embedded packet routing. **As of v0.7.0, MeshCore is a first-class radio owned by the MESH-API core** (`meshcore_core.py`) — *not* an extension. It connects directly to a MeshCore companion-firmware device over **USB serial, TCP, or BLE**, and its inbound traffic flows through the **same network-agnostic pipeline** as Meshtastic, so commands, AI, and every extension work on it natively.
  250. > ⬆️ **Upgrading from an earlier build?** The old `extensions/meshcore` bridge plugin is **deprecated** and automatically defers to the core when the core MeshCore radio is enabled — you do not need (and should not use) the extension anymore. Move your settings into the `meshcore` block of `config.json` (see below).
  251. You can run **one Meshtastic radio, one MeshCore radio, or one of each.** With both connected, MESH-API acts as the man-in-the-middle, optionally bridging chat between the two networks. See **[Running With Meshtastic, MeshCore, or Both](#running-with-meshtastic-meshcore-or-both-v070)** just below for the full configuration, topologies, and WebUI behavior.
  252. **Quick start:**
  253. 1. `pip install meshcore` *(already in `requirements.txt`)*.
  254. 2. Flash a companion device with MeshCore **Companion** firmware (USB‑serial, BLE, or TCP variant) from [https://flasher.meshcore.co.uk](https://flasher.meshcore.co.uk).
  255. 3. Enable and configure the radio in the **`meshcore`** block of [config.json](config.json) (set `enabled: true`, pick `connection_type`, and the port/host/address).
  256. 4. Restart MESH-API. The 🟣 MeshCore status appears in the connection banner, MeshCore nodes show on the harmonized map, and you can send to MeshCore (or both networks) from the dashboard.
  257. ---
  258. <img width="2543" height="1271" alt="image" src="https://github.com/user-attachments/assets/d2091bab-cbdf-4b4d-b424-10d59d812f22" />
  259. The latest v0.7.6.0 Beta Web-UI! NEW MAPS FEATURES AND TONS OF NEW GOODIES!
  260. ---
  261. ## Running With Meshtastic, MeshCore, or Both (v0.7.0)
  262. MESH-API v0.7.0 treats **MeshCore as a first-class radio** managed by the core
  263. (`meshcore_core.py`), feeding inbound messages through the *same* network-agnostic
  264. pipeline as Meshtastic. You can run any of three topologies:
  265. | Topology | How |
  266. |----------|-----|
  267. | **Meshtastic only** (classic) | Leave `meshcore.enabled: false`. Nothing changes. |
  268. | **MeshCore only** (standalone) | Set `meshtastic_enabled: false` and `meshcore.enabled: true`. No Meshtastic device required. |
  269. | **Both** (cross-network router) | `meshtastic_enabled: true` + `meshcore.enabled: true`. MESH-API bridges traffic between the two networks. |
  270. Configure MeshCore in the `meshcore` block of [config.json](config.json):
  271. ```jsonc
  272. "meshtastic_enabled": true, // set false to run MeshCore-only
  273. "default_send_network": "auto", // auto | meshtastic | meshcore | both
  274. "meshcore": {
  275. "enabled": true,
  276. "connection_type": "serial", // serial | tcp | ble
  277. "serial_port": "/dev/ttyUSB1", // or tcp_host/tcp_port, or ble_address
  278. "serial_baud": 115200,
  279. "bridge_enabled": true, // mirror chat between networks when both present
  280. "bridge_meshcore_channel_to_meshtastic_channel": { "0": 0 },
  281. "bridge_meshtastic_channel_to_meshcore_channel": { "0": 0 }
  282. }
  283. ```
  284. **What works across both networks:** slash commands, the AI assistant, every
  285. extension/plugin, the harmonized node map, DMs, channel/group messaging, and
  286. emergency broadcasts. The WebUI adapts automatically — a per-network connection
  287. banner, a node **network filter** with collapsible Meshtastic/MeshCore sections,
  288. network badges (📡 MT / 🟣 MC) on nodes and messages, distinct map markers, and a
  289. **Network** selector in the send form (Auto / Meshtastic / MeshCore / Both) that
  290. appears when both radios are present.
  291. > ⚠️ MeshCore support is brand new and widely untested — please report your
  292. > experience (any topology) on [GitHub](https://github.com/mr-tbot/mesh-api/issues).
  293. ---
  294. ## MCP Server (Model Context Protocol)
  295. v0.7.0 ships a built-in **MCP server** that exposes MESH-API's core functions
  296. **and** its extensions as callable *tools*, so external AI agents and services —
  297. **Claude, Perplexity, Hermes, custom agents, OpenClaw, etc.** — can drive your
  298. Meshtastic and/or MeshCore networks as an **agentic backend**. This enables
  299. advanced workflows: an agent can read the mesh, decide, and act (send messages,
  300. run commands, trigger extensions) over LoRa.
  301. ### How it works
  302. - **Transport:** Streamable HTTP / JSON-RPC 2.0 at a single endpoint, `POST /mcp`.
  303. Implemented directly in Flask (no async/uvicorn dependency — runs fine on a Pi
  304. Zero). Compatible with MCP clients that speak HTTP directly, or with stdio-only
  305. clients (e.g. Claude Desktop) via the [`mcp-remote`](https://github.com/geelen/mcp-remote) bridge.
  306. - **Disabled by default.** Enable it in the `mcp` block of [config.json](config.json):
  307. ```jsonc
  308. "mcp": {
  309. "enabled": true,
  310. "require_auth": true, // bearer token (auto-generated + printed on first start)
  311. "auth_token": "", // leave blank to auto-generate; also accepted as X-API-Key
  312. "allowed_origins": ["*"], // DNS-rebinding allowlist
  313. "allow_emergency": false, // gate the emergency tool
  314. "rate_limit_per_min": 120
  315. }
  316. ```
  317. On first start with auth enabled, a token like `mesh-mcp-XXXX` is generated,
  318. saved to config, and printed to the log. Pass it as `Authorization: Bearer <token>`.
  319. ### Connecting a client
  320. Point any MCP client at `http://<host>:5000/mcp` with the bearer token. For
  321. Claude Desktop / stdio clients:
  322. ```jsonc
  323. {
  324. "mcpServers": {
  325. "mesh-api": {
  326. "command": "npx",
  327. "args": ["-y", "mcp-remote", "http://<host>:5000/mcp",
  328. "--header", "Authorization: Bearer mesh-mcp-YOURTOKEN"]
  329. }
  330. }
  331. }
  332. ```
  333. ### Built-in core tools
  334. | Tool | Purpose |
  335. |------|---------|
  336. | `mesh_send_message` | Send to a network (meshtastic / meshcore / both / auto), broadcast or DM |
  337. | `mesh_list_nodes` | List nodes across both networks (filterable) |
  338. | `mesh_get_messages` | Read the recent mesh chat log |
  339. | `mesh_network_status` | Status of both radios |
  340. | `mesh_list_channels` | Meshtastic + MeshCore channels |
  341. | `mesh_ai_query` | Ask the configured AI provider |
  342. | `mesh_list_commands` / `mesh_run_command` | List / run any slash command |
  343. | `meshcore_list_contacts` | MeshCore DM targets |
  344. | `mesh_send_emergency` | Emergency broadcast (gated by `allow_emergency`) |
  345. ### Extensions as MCP tools
  346. **Every loaded extension's slash command is auto-exposed** as an `ext_cmd_<command>`
  347. tool — no work required. Extensions can additionally provide **richer, typed
  348. tools** by implementing two optional, duck-typed methods (no base-class change):
  349. ```python
  350. def get_mcp_tools(self) -> list[dict]:
  351. return [{
  352. "name": "lookup_city", # exposed as ext_<slug>_lookup_city
  353. "description": "Look up weather for a city",
  354. "inputSchema": {"type": "object",
  355. "properties": {"city": {"type": "string"}},
  356. "required": ["city"]},
  357. }]
  358. def call_mcp_tool(self, name: str, arguments: dict) -> str:
  359. if name == "lookup_city":
  360. return self._weather_for(arguments.get("city", ""))
  361. return f"Unknown tool: {name}"
  362. ```
  363. The tool list is rebuilt on every `tools/list`, so enabling/reloading an
  364. extension surfaces its tools without restarting MESH-API. See
  365. [DEVELOPING_EXTENSIONS.md](DEVELOPING_EXTENSIONS.md#mcp-tools-v070) for details.
  366. ### Security
  367. Tool calls can send mesh traffic and trigger actions, so the server validates
  368. inputs, requires a bearer token by default, validates the `Origin` header,
  369. rate-limits calls, clamps output size, and gates the emergency tool. Treat the
  370. token like a password. There should always be a human in the loop for sensitive
  371. operations.
  372. ---
  373. ## Firmware & Software Updates
  374. v0.7.0 adds a comprehensive, **safe-by-default** update system (`firmware_updater.py`):
  375. - **Detection** — identifies the connected Meshtastic device (hardware model +
  376. firmware variant `pioEnv` + version) and the MeshCore device (model + version).
  377. - **Update notifications** — a 🔄 **Updates** button in the WebUI masthead shows a
  378. badge when a newer **Meshtastic firmware**, **MeshCore firmware**, or **MESH-API**
  379. release is available (checked against GitHub on a periodic timer + on demand).
  380. - **Release channels** — pick **stable / beta / alpha** independently for
  381. Meshtastic and MeshCore firmware. Beta/alpha track GitHub pre-releases; the
  382. WebUI shows the newest matching version for the channel you choose. (Your device
  383. is not always a Heltec V3 — detection adapts to whatever is connected.)
  384. - **Flashing (optional, off by default)** — for ESP32-class Meshtastic devices,
  385. the latest firmware can be downloaded and flashed over USB serial via `esptool`.
  386. nRF52/UF2 devices and MeshCore companions fall back to guided
  387. [web-flasher](https://flasher.meshtastic.org/) instructions (unattended flashing
  388. there is unsafe). Enable with `firmware.allow_flashing: true`; optional
  389. `firmware.auto_update: true` flashes ESP32 Meshtastic devices unattended.
  390. ```jsonc
  391. "firmware": {
  392. "auto_check": true,
  393. "check_interval_sec": 86400,
  394. "allow_flashing": false, // master gate for flashing
  395. "auto_update": false, // never flashes unattended unless true
  396. "meshtastic_channel": "stable", // stable | beta | alpha
  397. "meshcore_channel": "stable",
  398. "meshtastic_fw_repo": "meshtastic/firmware",
  399. "meshcore_fw_repo": "meshcore-dev/MeshCore",
  400. "mesh_api_repo": "mr-tbot/mesh-api"
  401. }
  402. ```
  403. > ⚠️ Flashing can brick a radio. Always keep a backup device, and prefer the web
  404. > flasher unless you understand the risks. The radio goes offline during flashing.
  405. ---
  406. ## Channel Agents — Assign a Channel to an Agent
  407. v0.7.0 generalizes the old Home Assistant per-channel routing into **Channel
  408. Agents**: assign any mesh channel to a specific agent, and all plain-text
  409. (non-command) traffic on that channel is handled by it. Use it to dedicate a
  410. channel to **OpenClaw**, **Hermes**, **Home Assistant**, or any AI provider —
  411. on either Meshtastic or MeshCore.
  412. Configure it in the top-level `channel_agents` block of [config.json](config.json),
  413. mapping a channel index (as seen by MESH-API) to an agent spec:
  414. ```jsonc
  415. "channel_agents": {
  416. "6": { "agent": "ai", "provider": "hermes" }, // ch6 → Hermes
  417. "7": { "agent": "extension", "slug": "openclaw" }, // ch7 → OpenClaw agent
  418. "5": { "agent": "ai", "provider": "home_assistant" }, // ch5 → Home Assistant
  419. "8": { "agent": "ai", "provider": "openai", "require_pin": true }
  420. }
  421. ```
  422. - **`agent: "ai"`** routes the channel to a named AI provider (`openai`, `hermes`,
  423. `ollama`, `claude`, `home_assistant`, etc.) — independent of the global
  424. `ai_provider`, so different channels can use different models.
  425. - **`agent: "extension"`** routes to a loaded extension (e.g. `openclaw`) via its
  426. `handle_channel_message()` hook, falling back to `get_ai_response()` or a
  427. configured `command`. See [DEVELOPING_EXTENSIONS.md](DEVELOPING_EXTENSIONS.md#channel-agents-v070).
  428. - **`require_pin: true`** gates the channel behind a `PIN=XXXX` prefix (like the
  429. Home Assistant secure mode).
  430. - Channels with an assigned agent **always respond**, bypassing the global
  431. `reply_in_channels` setting. Slash commands still work normally there.
  432. - The legacy `home_assistant_channel_index` setting continues to work and is
  433. surfaced via `GET /api/channel_agents`.
  434. > Channel indices differ between physical MeshCore devices — assign the agent to
  435. > the index **as MESH-API receives it** (visible in the logs / message panel).
  436. ---
  437. ## Extensions Reference
  438. > **Note:** The extensions system and all corresponding extensions are **new and largely untested**. Please report any issues on [GitHub](https://github.com/mr-tbot/mesh-api/issues) so they may be investigated and addressed.
  439. MESH-API ships with 30 built-in extensions across 7 categories — Communication
  440. (Discord, Slack, Telegram, Matrix, Signal, WhatsApp, Mattermost, Zello, MQTT,
  441. Webhook, IMAP, Mastodon, n8n), Notifications (Apprise, Ntfy, Pushover, PagerDuty,
  442. OpsGenie), Emergency & Weather (NWS Alerts, OpenWeatherMap, USGS Earthquakes,
  443. GDACS, Amber Alerts, NASA Space Weather), Ham Radio & Off-Grid (Winlink, APRS,
  444. BBS), Smart Home (Home Assistant), Mesh Bridging (MeshCore — *deprecated, now a
  445. core radio*), and AI Agents (OpenClaw).
  446. Each extension is a self-contained plugin in the `extensions/` directory with its
  447. own `config.json`, `extension.py`, and `__init__.py`. **Quick start:** enable any
  448. extension by setting `"enabled": true` in its `config.json` and restarting MESH-API.
  449. 📦 **Full per-extension command lists, config keys, and hooks are documented in
  450. [EXTENSIONS.md](EXTENSIONS.md).** To build your own, see
  451. [Developing Custom Extensions](#developing-custom-extensions) and
  452. [DEVELOPING_EXTENSIONS.md](DEVELOPING_EXTENSIONS.md).
  453. ---
  454. ## Developing Custom Extensions
  455. > 🧩 **The full extension-development guide now lives in its own file:
  456. > [DEVELOPING_EXTENSIONS.md](DEVELOPING_EXTENSIONS.md).**
  457. MESH-API uses a plugin-based extension system where each extension is a
  458. self-contained Python package in the `extensions/` directory. Extensions can
  459. register slash commands, send/receive mesh messages, react to emergencies,
  460. observe all inbound traffic, expose Flask HTTP endpoints, run background
  461. polling threads, and act as AI providers — all auto-discovered at startup with
  462. no changes to core code.
  463. **To build one:**
  464. 1. Copy the template: `cp -r extensions/_example extensions/my_extension`
  465. 2. Edit the three files — `__init__.py` (empty), `config.json` (must include `"enabled": true`), and `extension.py` (subclass `BaseExtension`).
  466. 3. Restart MESH-API — it's auto-discovered and loaded.
  467. 4. Send `/extensions` on the mesh to verify it's listed.
  468. 📚 **Full reference** — the complete Base Class API, every lifecycle/message
  469. hook, the `app_context` dict, a step-by-step tutorial, background-thread and
  470. Flask-route patterns, best practices, and troubleshooting are all documented in
  471. **[DEVELOPING_EXTENSIONS.md](DEVELOPING_EXTENSIONS.md)**. For the catalog of the
  472. 30 built-in extensions and their config keys, see
  473. **[EXTENSIONS.md](EXTENSIONS.md)**.
  474. ---
  475. ## Roadmap
  476. - **API Integration Workflow (Planned)**
  477. - A guided workflow for adding new API integrations, including configuration templates, validation checks, and safe test routes before production use.
  478. - Goal: make it easier to connect external services without editing core code.
  479. - **MeshCore Routing Support (Initial Implementation — v0.6.0)**
  480. - MeshCore extension added with bidirectional bridge, command support, and AI integration.
  481. - Supports USB serial and TCP/WiFi connections to MeshCore companion devices.
  482. - *(Superseded in v0.7.0 — MeshCore is now a first-class core radio; see [Running With Meshtastic, MeshCore, or Both](#running-with-meshtastic-meshcore-or-both-v070).)*
  483. ---
  484. ## Changelog
  485. 📜 **The full version history has moved to [CHANGELOG.md](CHANGELOG.md)** to keep
  486. this README short. It covers every release from v0.1 through the current
  487. v0.7.4.1 Beta, with both per-release summaries and detailed notes.
  488. ---
  489. ## Basic Usage
  490. - **Interacting with the AI:**
  491. - Use your randomized alias shown at startup (e.g., `/ai-9z`) — AI commands require the suffix: `/ai-9z`, `/bot-9z`, `/query-9z`, `/data-9z` followed by your message.
  492. - To avoid collisions (multiple bots responding), prefer your unique alias and/or customize commands in `commands_config.json`.
  493. - For direct messages, simply DM the AI node if configured to reply.
  494. - **Location Query:**
  495. - Send `/whereami-XY` (replace `XY` with your suffix) to retrieve the node’s GPS coordinates (if available).
  496. - **Emergency Alerts:**
  497. - Trigger an emergency using `/emergency <message>` or `/911 <message>`.
  498. - These commands send alerts via Twilio, SMTP, and Discord (if enabled), including GPS data and timestamps.
  499. - **Sending and receiving SMS:**
  500. - Send SMS using your suffixed command, e.g., `/sms-9z <+15555555555> <message>`
  501. - Config options to either route incoming Twilio SMS messages to a specific node, or a channel index.
  502. - **Home Assistant Integration:**
  503. - When enabled, messages sent on the designated Home Assistant channel (as defined by `"home_assistant_channel_index"`) are forwarded to Home Assistant’s conversation API.
  504. - In secure mode, include the PIN in your message (format: `PIN=XXXX your message`).
  505. - **WebUI Messaging:**
  506. - Use the dashboard’s send‑message form to reach the mesh. See [Web UI / Dashboard](#web-ui--dashboard) below for the full breakdown of broadcast/direct modes and multi‑network targeting.
  507. ### Web UI / Dashboard
  508. The dashboard at `http://<host>:5000/dashboard` is the primary control surface.
  509. Key panels:
  510. - **📤 Send a Message** — a two‑mode composer:
  511. - **Broadcast mode** lets you target one or more networks at once via
  512. checkboxes. Each enabled network shows its own channel picker:
  513. - 📡 **Meshtastic** — pick a Meshtastic channel.
  514. - 🟣 **MeshCore** — pick a MeshCore channel.
  515. - 🌉 **Bridged** — a single selection that fans out to *both* radios; the
  516. dropdown shows the paired routing, e.g. `0 → 📡 LongFast + 🟣 Public`,
  517. so you can see exactly which Meshtastic and MeshCore channels a bridged
  518. send will hit.
  519. - **Direct mode** searches your node list (across both networks) and sends a
  520. DM; a hint shows which network the selected node lives on.
  521. - **🟢 Nodes** — live node list grouped by network, plus a **Previously Seen**
  522. section for nodes that have gone stale (with an adjustable staleness
  523. threshold). Favorites can be pinned so they stay in the main list. MeshCore
  524. contacts use activity‑based presence (message activity), since MeshCore nodes
  525. advertise only occasionally rather than beaconing continuously.
  526. - **🗺️ Map** — node positions using live GPS or your manual location.
  527. - **📈 Traffic Monitor** — recent mesh message feed across both networks.
  528. - **🤖 Channel Agents** — assign a dedicated AI persona/provider per channel.
  529. - **🛠️ Config Editor / Setup Wizard** — edit `config.json`,
  530. `commands_config.json`, and `motd.json` from the browser (see below).
  531. ### WebUI Config Editor (new)
  532. - Open the dashboard and click the “Config” button in the header (next to Commands/Logs).
  533. - A tabbed editor appears with four views:
  534. - **⚙️ config.json** — a form-based editor for all core app settings (providers, timeouts, routing, integrations, etc.)
  535. - **📝 Raw JSON** — direct JSON editing for advanced users
  536. - **commands_config.json** — a form-based command builder. Add, edit, or remove slash commands. Each command has a trigger (`/mycommand`), a type (Static Response or AI Prompt), a response/prompt value, and a description. No manual JSON editing needed.
  537. - **motd.json** — a simple text field for the Message of the Day string
  538. - Make edits and click Save. The editor validates data before saving and writes changes atomically.
  539. - **🧙 Run Setup Wizard** — re-run the first-start wizard at any time from the Config Editor header. The wizard walks you through your **Meshtastic radio**, your **MeshCore radio** (serial / TCP / BLE, adverts, channel bridging — or a MeshCore-only/standalone node), your **AI provider**, and **node identity** (including the default send-network). It pre-populates every field from the existing configuration so you can review and update settings without starting from scratch.
  540. - Changes to some settings may require restarting the app/container to take effect (e.g., provider, connectivity, or Discord/Twilio credentials).
  541. - Security note: If you expose the WebUI beyond localhost, protect access to the dashboard since configuration files may contain secrets (API keys, tokens).
  542. ### Manual GPS Location
  543. - If your node does not have a GPS module, you can set your latitude and longitude manually in the **UI Settings** panel under "📍 My Location (Manual GPS)".
  544. - When set, distance calculations to other nodes and the “You” marker on the map will use your manual coordinates instead of the connected node’s GPS.
  545. - Leave the fields blank to revert to the connected node’s GPS.
  546. ### Channel Names from Node
  547. - Channel names are now automatically pulled from the connected Meshtastic node via the `/api/channels` endpoint.
  548. - You can rename channels in the **UI Settings** panel under "📡 Channel Names". Overrides are stored locally and take priority over node-reported names.
  549. #### WebUI Config Options (Quick Guide)
  550. The Config Editor includes a grouped help panel. These are the main groups and what they cover:
  551. - **Core**: AI provider selection, system prompt, alias suffix, AI node name, local location string.
  552. - **Diagnostics**: debug logging and message log limits.
  553. - **Providers**: LM Studio, OpenAI, Ollama, and Home Assistant settings.
  554. - **Connectivity**: WiFi, serial, or mesh interface options and advanced node overrides.
  555. - **Policy**: Reply behavior and MQTT response gating.
  556. - **Performance**: Chunk sizing and delays for radio-friendly responses.
  557. - **Channels**: Friendly channel names and `/nodes-XY` online window.
  558. - **Integrations**: Home Assistant, Discord, Twilio, and SMTP credentials and routing. (future home of API integration settings)
  559. ### How AI messages are identified and ignored by other bots
  560. - AI responses include a very short prefix marker `m@i` at the start of the message body. This is not configurable on purpose and is capped at 3 characters to conserve airtime.
  561. - Other MESH-API instances will ignore messages that start with this marker, preventing bots from talking to each other.
  562. - Each instance also tracks node IDs that have sent AI-tagged messages and ignores further messages from those nodes.
  563. #### What is bot‑looping and why is it a problem?
  564. - Bot‑looping happens when two or more automated agents see each other’s messages as prompts and keep replying back and forth without a human in the loop.
  565. - On a constrained LoRa mesh, this can quickly saturate airtime (especially on LongFast), drain batteries, and crowd out legitimate traffic.
  566. - Loops can be surprisingly hard to break because:
  567. - Messages may be re‑broadcast via MQTT and multiple gateways, multiplying replies.
  568. - Nodes can buffer/retry after brief outages, re‑triggering the loop even if you silence one side.
  569. - Different bots might parse/quote each other in ways that keep producing “valid” prompts.
  570. - MESH‑API mitigations:
  571. - A fixed 3‑char marker (`m@i`) at the start of AI replies so other instances will ignore them.
  572. - A memory of node IDs that have emitted AI‑tagged messages to avoid engaging those nodes.
  573. - Conservative defaults: no LongFast replies by default and MQTT response gating disabled by default.
  574. - Policy: the AI never initiates conversations or responds to arrival/presence events—only explicit human messages.
  575. ---
  576. ## Using the API
  577. The MESH-API server (running on Flask) exposes the following endpoints.
  578. > 🔐 **Login (v0.7.6.0+):** out of the box these endpoints need no login. If you turn on the
  579. > optional WebUI login (**⚙️ Config → 🔐 WebUI Access**), it covers the dashboard **and every
  580. > endpoint below**, so scripts must send the API token
  581. > (`Authorization: Bearer <token>` or `X-API-Key: <token>`). To keep `/send`, `/messages`,
  582. > `/nodes`, `/connection_status` and `/commands_info` open while the dashboard and config stay
  583. > behind the login, set `webui.auth.protect_api` to `false`. Details:
  584. > [WebUI access control](CONFIGURATION.md#webui-access-control).
  585. - **GET `/messages`**
  586. Retrieve the last 100 messages in JSON format.
  587. - **GET `/nodes`**
  588. Retrieve a live list of connected nodes as JSON.
  589. - **GET `/connection_status`**
  590. Get current connection status and error details.
  591. - **GET `/logs`**
  592. View a styled log page showing uptime, restarts, and recent log entries.
  593. - **GET `/logs_stream`**
  594. Stream recent logs in JSON for lightweight polling.
  595. - **GET `/dashboard`**
  596. Access the full WebUI dashboard.
  597. - **GET `/commands_info`**
  598. Retrieve a JSON list of available commands and descriptions (used by the in‑app Commands modal).
  599. - **GET `/config_editor/load`**
  600. Load the current contents of `config.json`, `commands_config.json`, and `motd.json` for the WebUI Config Editor.
  601. - **POST `/config_editor/save`**
  602. Save updates to the above files. Payload is validated (JSON where applicable) and written atomically. Some settings require an app restart to apply.
  603. - **POST `/send`** and **POST `/ui_send`**
  604. Send messages programmatically.
  605. - **POST `/discord_webhook`**
  606. Receive messages from Discord (if configured).
  607. - **POST `/twilio_webhook`**
  608. Receive inbound SMS from Twilio. Only answers while **Enable Twilio** is on.
  609. Webhook endpoints and `/mcp` are never covered by the WebUI login, because the services that call them cannot log in.
  610. ---
  611. ## Configuration
  612. > ⚙️ **The full configuration reference now lives in
  613. > [CONFIGURATION.md](CONFIGURATION.md).**
  614. Core MESH-API settings live in [config.json](config.json) — connection, AI
  615. provider, messaging, and emergency alerts. Most people never hand-edit it: the
  616. dashboard's **⚙️ Config** editor and re-runnable **🧙 Setup Wizard** cover every
  617. core setting (see [Web UI / Dashboard](#web-ui--dashboard)).
  618. [CONFIGURATION.md](CONFIGURATION.md) documents the complete annotated default
  619. `config.json`, the multi-radio blocks (`meshtastic_enabled`,
  620. `default_send_network`, `meshcore`, `mcp`, `firmware`), and the other
  621. operational settings (logging, device connection, message routing, AI provider
  622. selection).
  623. > **Note:** Integration-specific settings (Discord, Home Assistant, Slack,
  624. > Telegram, etc.) are configured **per-extension** in
  625. > `extensions/<name>/config.json`, not in the core config — see
  626. > [INTEGRATIONS.md](INTEGRATIONS.md) and [EXTENSIONS.md](EXTENSIONS.md).
  627. ---
  628. ## Integrations
  629. > 🔌 **Integration setup guides now live in
  630. > [INTEGRATIONS.md](INTEGRATIONS.md).**
  631. MESH-API connects to external services for AI, alerting, and chat bridging:
  632. - **Home Assistant** — forward a channel to the HA conversation API (with
  633. optional PIN security).
  634. - **LLM API** — 12 AI providers (LM Studio, OpenAI, Ollama, Claude, Gemini,
  635. Grok, OpenRouter, Groq, DeepSeek, Mistral, OpenAI-compatible).
  636. - **Email (SMTP)** and **Twilio SMS** — emergency alerting with a Google Maps
  637. link.
  638. - **Discord** — full bot + webhook bridge (detailed bot/permissions setup).
  639. Step-by-step setup for each lives in **[INTEGRATIONS.md](INTEGRATIONS.md)**.
  640. Chat-bridge integrations (Discord, Telegram, Matrix, Mattermost, etc.) are
  641. extensions — see **[EXTENSIONS.md](EXTENSIONS.md)**.
  642. ---
  643. ## Contributing & Disclaimer
  644. - **v0.7.4.1 Beta:**
  645. The 0.7.x line makes MeshCore a first-class radio and adds the MCP server, firmware-update system, token-free AI-endpoint heartbeat monitoring (v0.7.3.6), the all-extensions-to-MeshCore fix (v0.7.3.7), and the v0.7.4 MeshCore Setup Wizard; v0.7.4.1 revamps the **Send a Message** composer (mode tabs, multi-network broadcast targeting, bridged dropdown showing both routed channels), adds a **Previously Seen** node section, and fixes **MeshCore presence** (activity-based last-heard). These features are still relatively untested in the field — please report any issues on [GitHub](https://github.com/mr-tbot/mesh-api/issues) so they may be investigated and addressed.
  646. - **Feedback & Contributions:**
  647. Report issues or submit pull requests on GitHub. Your input is invaluable.
  648. - **Use Responsibly:**
  649. Modifying this code for nefarious purposes is strictly prohibited. Use at your own risk.
  650. ---
  651. ## Conclusion
  652. MESH-API v0.7.4.1 Beta is here! The 0.7.x line treats **MeshCore as a first-class radio** alongside Meshtastic, adds a built-in **MCP server** for external AI agents, a **firmware/software update manager**, token-free AI-endpoint heartbeat monitoring (v0.7.3.6), the all-extensions-to-MeshCore routing fix (v0.7.3.7), the v0.7.4 **MeshCore Setup Wizard**, and — new in v0.7.4.1 — a revamped **Send a Message** composer (broadcast/direct tabs, multi-network targeting, a bridged dropdown showing both routed channels), a **Previously Seen** node section, and a **MeshCore presence** fix. All on top of the powerful 30-extension plugin system, 12 AI providers, and safer defaults. Whether you’re chatting directly with your node, integrating with Home Assistant, or leveraging multi‑channel alerting (Twilio, Email, Discord), this release offers the most comprehensive and extensible off‑grid AI assistant experience yet. Please report any issues on [GitHub](https://github.com/mr-tbot/mesh-api/issues).
  653. **Enjoy tinkering, stay safe, and have fun!**
  654. Please share your feedback or report issues on [GitHub](https://github.com/mr-tbot/mesh-api/issues).

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.