MESH-API v0.7.5.2 Beta — Meshtastic + MeshCore Mesh Router & API / AI Bridge

🎉 Now with full MeshCore support (since v0.7.0)

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.

⚠️ 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. Your real-world reports directly shape the MeshCore implementation going forward.

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.

🆕 What's new

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), and v0.7.3.6 added a token-free heartbeat for named AI endpoints.

📜 See the full version history in CHANGELOG.md.

❤️ Support MESH-API Development — Keep the Lights On

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.

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.

Donate via PayPal (Preferred)

Click here to donate via PayPal

Crypto Donations

Thank you to everyone who has donated, filed issues, tested pre-releases, and spread the word. You are what makes this project possible. 🙏

MESH-API is an experimental project that bridges Meshtastic (& now MeshCore ) LoRa mesh networks with powerful AI chatbots and 3rd party APIs.

What Sets MESH-API Apart?

Most projects in this space stop at being "AI chatbot integrations" — but MESH-API is much more than that.

• Full Router / Mesh Operator
  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.

• Not a One-Trick Pony
  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.

• Expandable by Design
  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.

• AI-Powered Off-Grid Networks
  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.

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.

Disclaimer:
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.

v0.7.4.1 Beta:
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.

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!

The Meshtastic logo trademark is the trademark of Meshtastic LLC.

Features

• Multi-Radio: Meshtastic, MeshCore, or Both (New in v0.7.0)
  • MeshCore is a first-class, core-owned radio (not an extension) on equal footing with Meshtastic, connecting over serial / TCP / BLE.
  • 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.
  • Slash commands, the AI assistant, and every extension work across both networks. Send to one network or both at once.
  • 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.
• MCP (Model Context Protocol) Server (New in v0.7.0)
  • 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.
• Firmware & Software Updates (New in v0.7.0)
  • 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).
• Plugin-Based Extensions System (New in v0.6.0)
  • 30 built-in extensions across 7 categories: Communication, Notifications, Emergency/Weather, Ham Radio/Off-Grid, Smart Home, Mesh Bridging, and AI Agents.
  • Drop-in plugin architecture — add or remove extensions by copying a folder. No core code changes required.
  • Extensions can register slash commands, react to emergencies, observe messages, expose HTTP endpoints, and run background services.
  • WebUI Extensions Manager — view, enable/disable, and configure extensions from the dashboard.
  • See the Extensions Reference section below for full details on all built-in extensions, or Developing Custom Extensions to build your own.
• Multiple AI Providers
  • 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.
• Home Assistant Integration
  • Seamlessly forward messages from a designated channel to Home Assistant’s conversation API. Optionally secure the integration using a PIN.
• NASA Space Weather Monitoring
  • 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.
• n8n Workflow Automation
  • Bidirectional bridge with n8n — 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.
• Advanced Slash Commands
  • 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.
  • Commands are now case‑insensitive for improved mobile usability.
  • 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.
  • Strongly encouraged: customize your commands in commands_config.json to avoid collisions with other users.
• Emergency Alerts
  • Trigger alerts that are sent via Twilio SMS, SMTP Email, and, if enabled, Discord.
  • Emergency notifications include GPS coordinates, UTC timestamps, and user messages.
• Enhanced REST API & WebUI Dashboard
  • 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).
  • 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.
  • Collapsible Channel Groups — Each channel is a toggle‑able group with an unread‑count badge. Click the 📻 header to expand/collapse.
  • 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.
  • 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.
  • 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.
  • 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).
  • 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.
  • 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.
  • 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.
  • 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.
• Improved Message Chunking & Routing
  • Automatically splits long AI responses into configurable chunks with delays to reduce radio congestion.
  • Configurable flags control whether the bot replies to broadcast channels and/or direct messages.
  • 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.
  • Etiquette: Using AI bots on public LongFast is discouraged; keep it off unless you’re on an isolated/private mesh with community consent.
• Robust Error Handling & Logging
  • Uses UTC‑based timestamps with an auto‑truncating script log file (keeping the last 100 lines if the file grows beyond 100 MB).
  • Enhanced error detection (including specific OSError codes) and graceful reconnection using threaded exception hooks.
• Discord Integration Enhancements
  • Route messages to and from Discord.
  • New configuration options and a dedicated /discord_webhook endpoint allow for inbound Discord message processing.
  • 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.
  • User‑initiated only: The AI does not auto‑message or greet new nodes; it responds only to explicit user input.
• Commands modal & startup helper
  • WebUI includes a Commands modal (button in the “Send a Message” header) that lists available commands with descriptions.
  • The current alias suffix and a one‑line commands list are printed at startup for easy reference.
• Windows & Linux Focused
  • Official support for Windows environments with installation guides; instructions for Linux available now - MacOS coming soon!

An example of an awesome Raspberry Pi 5 powered mini terminal - running MESH-API & Ollama with HomeAssistant integration!

• Top case model here by oinkers1: https://www.thingiverse.com/thing:6571150
• Bottom Keyboard tray model here by mr_tbot: https://www.thingiverse.com/thing:7084222
• Keyboard on Amazon here: https://a.co/d/2dAC9ph

Quick Start (Windows)

1. Prerequisites

   • Python 3.11+ — Download from python.org. During install, check “Add Python to PATH”.
   • Git (optional) — git-scm.com for cloning, or download the ZIP from GitHub.

2. Download/Clone

   • Clone the repository (or download and extract the ZIP):

     git clone https://github.com/mr-tbot/mesh-api.git
     cd mesh-api
     

3. Create & Activate a Virtual Environment:

   python -m venv venv
   .\venv\Scripts\activate
   

4. Install Dependencies:

   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:

     python mesh-api.py
     

7. Access the WebUI Dashboard:

   • Open your browser and navigate to http://localhost:5000/dashboard.

Quick Start (Ubuntu / Linux)

1. Prerequisites

   • Python 3.11+ and pip:

     sudo apt update && sudo apt install -y python3 python3-pip python3-venv git
     

   • Grant serial port access (required for USB-connected Meshtastic devices):

     sudo usermod -aG dialout $USER
     

     Log out and back in for the group change to take effect.

2. Download/Clone

   git clone https://github.com/mr-tbot/mesh-api.git
   cd mesh-api
   

3. Create & Activate a Virtual Environment:

   python3 -m venv venv
   source venv/bin/activate
   

4. Install Dependencies:

   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:

   python mesh-api.py
   

7. Access the WebUI Dashboard:

   • Open your browser and navigate to http://localhost:5000/dashboard.

Quick Start (Docker)

Multi-arch Docker images are published for linux/amd64 (x86_64) and linux/arm64 (Raspberry Pi 4/5, Apple Silicon).

1. Prerequisites

   • Docker Engine (or Docker Desktop) installed on your host.
   • A Meshtastic device connected via USB serial, Wi-Fi, or Bluetooth.

2. Prepare the Volume Structure

   • The docker-required-volumes/ folder in the repository contains a ready-to-use mesh-api/ directory with default configs, all 30 built-in extensions, and empty log files. Copy it to your working directory:

     git clone https://github.com/mr-tbot/mesh-api.git
     cd mesh-api
     cp -r docker-required-volumes/mesh-api ./mesh-api
     

   • Edit the config files inside mesh-api/config/ before starting:

   mesh-api/
   ├── config/
   │   ├── config.json           # Core configuration (AI provider, connection, etc.)
   │   ├── commands_config.json   # Custom slash commands
   │   └── motd.json              # Message of the Day
   ├── extensions/                # All 30 built-in extensions (add your own here too)
   │   ├── __init__.py
   │   ├── base_extension.py
   │   ├── loader.py
   │   ├── discord/
   │   ├── telegram/
   │   ├── mqtt/
   │   └── ...  (30 built-in extensions)
   └── logs/
       ├── script.log
       ├── messages.log
       └── messages_archive.json
   

3. Pull & Run with Docker Compose

   • Copy the included docker-compose.yml to the same directory as your mesh-api/ folder, then:

     docker compose pull
     docker compose up -d
     

   • 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).
   • Wi-Fi connection: Set use_wifi: true and wifi_host in mesh-api/config/config.json — no device passthrough needed.

4. Verify the Container:

   docker compose logs -f mesh-api
   

5. Access the WebUI Dashboard:

   • Open your browser and navigate to http://localhost:5000/dashboard.
   • On first launch the Setup Wizard will guide you through initial configuration.

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.

Supported Mesh Networks

MESH-API supports two mesh radio platforms that can operate independently or be bridged together for cross-network communication.

Meshtastic (Primary)

Meshtastic 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.

All MESH-API features — AI commands, slash commands, emergency alerts, extensions, WebUI dashboard — work natively over the Meshtastic connection.

MeshCore (First-Class Radio — v0.7.0)

MeshCore 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.

⬆️ 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).

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 just below for the full configuration, topologies, and WebUI behavior.

Quick start:

1. pip install meshcore (already in requirements.txt).
2. Flash a companion device with MeshCore Companion firmware (USB‑serial, BLE, or TCP variant) from https://flasher.meshcore.co.uk.
3. Enable and configure the radio in the meshcore block of config.json (set enabled: true, pick connection_type, and the port/host/address).
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.

The latest v0.7.5.2 Beta Web-UI! NEW MAPS FEATURES AND TONS OF NEW GOODIES!

Running With Meshtastic, MeshCore, or Both (v0.7.0)

MESH-API v0.7.0 treats MeshCore as a first-class radio managed by the core (meshcore_core.py), feeding inbound messages through the same network-agnostic pipeline as Meshtastic. You can run any of three topologies:

Configure MeshCore in the meshcore block of config.json:

"meshtastic_enabled": true,            // set false to run MeshCore-only
"default_send_network": "auto",        // auto | meshtastic | meshcore | both
"meshcore": {
  "enabled": true,
  "connection_type": "serial",         // serial | tcp | ble
  "serial_port": "/dev/ttyUSB1",       // or tcp_host/tcp_port, or ble_address
  "serial_baud": 115200,
  "bridge_enabled": true,              // mirror chat between networks when both present
  "bridge_meshcore_channel_to_meshtastic_channel": { "0": 0 },
  "bridge_meshtastic_channel_to_meshcore_channel": { "0": 0 }
}

What works across both networks: slash commands, the AI assistant, every extension/plugin, the harmonized node map, DMs, channel/group messaging, and emergency broadcasts. The WebUI adapts automatically — a per-network connection banner, a node network filter with collapsible Meshtastic/MeshCore sections, network badges (📡 MT / 🟣 MC) on nodes and messages, distinct map markers, and a Network selector in the send form (Auto / Meshtastic / MeshCore / Both) that appears when both radios are present.

⚠️ MeshCore support is brand new and widely untested — please report your experience (any topology) on GitHub.

MCP Server (Model Context Protocol)

v0.7.0 ships a built-in MCP server that exposes MESH-API's core functions and its extensions as callable tools, so external AI agents and services — Claude, Perplexity, Hermes, custom agents, OpenClaw, etc. — can drive your Meshtastic and/or MeshCore networks as an agentic backend. This enables advanced workflows: an agent can read the mesh, decide, and act (send messages, run commands, trigger extensions) over LoRa.

How it works

• Transport: Streamable HTTP / JSON-RPC 2.0 at a single endpoint, POST /mcp. Implemented directly in Flask (no async/uvicorn dependency — runs fine on a Pi Zero). Compatible with MCP clients that speak HTTP directly, or with stdio-only clients (e.g. Claude Desktop) via the mcp-remote bridge.

• Disabled by default. Enable it in the mcp block of config.json:

  "mcp": {
    "enabled": true,
    "require_auth": true,        // bearer token (auto-generated + printed on first start)
    "auth_token": "",            // leave blank to auto-generate; also accepted as X-API-Key
    "allowed_origins": ["*"],    // DNS-rebinding allowlist
    "allow_emergency": false,    // gate the emergency tool
    "rate_limit_per_min": 120
  }
  

  On first start with auth enabled, a token like mesh-mcp-XXXX is generated, saved to config, and printed to the log. Pass it as Authorization: Bearer <token>.

Connecting a client

Point any MCP client at http://<host>:5000/mcp with the bearer token. For Claude Desktop / stdio clients:

{
  "mcpServers": {
    "mesh-api": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "http://<host>:5000/mcp",
               "--header", "Authorization: Bearer mesh-mcp-YOURTOKEN"]
    }
  }
}

Built-in core tools

Extensions as MCP tools

Every loaded extension's slash command is auto-exposed as an ext_cmd_<command> tool — no work required. Extensions can additionally provide richer, typed tools by implementing two optional, duck-typed methods (no base-class change):

def get_mcp_tools(self) -> list[dict]:
    return [{
        "name": "lookup_city",          # exposed as ext_<slug>_lookup_city
        "description": "Look up weather for a city",
        "inputSchema": {"type": "object",
                        "properties": {"city": {"type": "string"}},
                        "required": ["city"]},
    }]

def call_mcp_tool(self, name: str, arguments: dict) -> str:
    if name == "lookup_city":
        return self._weather_for(arguments.get("city", ""))
    return f"Unknown tool: {name}"

The tool list is rebuilt on every tools/list, so enabling/reloading an extension surfaces its tools without restarting MESH-API. See DEVELOPING_EXTENSIONS.md for details.

Security

Tool calls can send mesh traffic and trigger actions, so the server validates inputs, requires a bearer token by default, validates the Origin header, rate-limits calls, clamps output size, and gates the emergency tool. Treat the token like a password. There should always be a human in the loop for sensitive operations.

Firmware & Software Updates

v0.7.0 adds a comprehensive, safe-by-default update system (firmware_updater.py):

• Detection — identifies the connected Meshtastic device (hardware model + firmware variant pioEnv + version) and the MeshCore device (model + version).
• Update notifications — a 🔄 Updates button in the WebUI masthead shows a badge when a newer Meshtastic firmware, MeshCore firmware, or MESH-API release is available (checked against GitHub on a periodic timer + on demand).
• Release channels — pick stable / beta / alpha independently for Meshtastic and MeshCore firmware. Beta/alpha track GitHub pre-releases; the WebUI shows the newest matching version for the channel you choose. (Your device is not always a Heltec V3 — detection adapts to whatever is connected.)
• Flashing (optional, off by default) — for ESP32-class Meshtastic devices, the latest firmware can be downloaded and flashed over USB serial via esptool. nRF52/UF2 devices and MeshCore companions fall back to guided web-flasher instructions (unattended flashing there is unsafe). Enable with firmware.allow_flashing: true; optional firmware.auto_update: true flashes ESP32 Meshtastic devices unattended.

"firmware": {
  "auto_check": true,
  "check_interval_sec": 86400,
  "allow_flashing": false,          // master gate for flashing
  "auto_update": false,             // never flashes unattended unless true
  "meshtastic_channel": "stable",   // stable | beta | alpha
  "meshcore_channel": "stable",
  "meshtastic_fw_repo": "meshtastic/firmware",
  "meshcore_fw_repo": "meshcore-dev/MeshCore",
  "mesh_api_repo": "mr-tbot/mesh-api"
}

⚠️ Flashing can brick a radio. Always keep a backup device, and prefer the web flasher unless you understand the risks. The radio goes offline during flashing.

Channel Agents — Assign a Channel to an Agent

v0.7.0 generalizes the old Home Assistant per-channel routing into Channel Agents: assign any mesh channel to a specific agent, and all plain-text (non-command) traffic on that channel is handled by it. Use it to dedicate a channel to OpenClaw, Hermes, Home Assistant, or any AI provider — on either Meshtastic or MeshCore.

Configure it in the top-level channel_agents block of config.json, mapping a channel index (as seen by MESH-API) to an agent spec:

"channel_agents": {
  "6": { "agent": "ai", "provider": "hermes" },          // ch6 → Hermes
  "7": { "agent": "extension", "slug": "openclaw" },      // ch7 → OpenClaw agent
  "5": { "agent": "ai", "provider": "home_assistant" },   // ch5 → Home Assistant
  "8": { "agent": "ai", "provider": "openai", "require_pin": true }
}

• agent: "ai" routes the channel to a named AI provider (openai, hermes, ollama, claude, home_assistant, etc.) — independent of the global ai_provider, so different channels can use different models.
• agent: "extension" routes to a loaded extension (e.g. openclaw) via its handle_channel_message() hook, falling back to get_ai_response() or a configured command. See DEVELOPING_EXTENSIONS.md.
• require_pin: true gates the channel behind a PIN=XXXX prefix (like the Home Assistant secure mode).
• Channels with an assigned agent always respond, bypassing the global reply_in_channels setting. Slash commands still work normally there.
• The legacy home_assistant_channel_index setting continues to work and is surfaced via GET /api/channel_agents.

Channel indices differ between physical MeshCore devices — assign the agent to the index as MESH-API receives it (visible in the logs / message panel).

Extensions Reference

Note: The extensions system and all corresponding extensions are new and largely untested. Please report any issues on GitHub so they may be investigated and addressed.

MESH-API ships with 30 built-in extensions across 7 categories — Communication (Discord, Slack, Telegram, Matrix, Signal, WhatsApp, Mattermost, Zello, MQTT, Webhook, IMAP, Mastodon, n8n), Notifications (Apprise, Ntfy, Pushover, PagerDuty, OpsGenie), Emergency & Weather (NWS Alerts, OpenWeatherMap, USGS Earthquakes, GDACS, Amber Alerts, NASA Space Weather), Ham Radio & Off-Grid (Winlink, APRS, BBS), Smart Home (Home Assistant), Mesh Bridging (MeshCore — deprecated, now a core radio), and AI Agents (OpenClaw).

Each extension is a self-contained plugin in the extensions/ directory with its own config.json, extension.py, and __init__.py. Quick start: enable any extension by setting "enabled": true in its config.json and restarting MESH-API.

📦 Full per-extension command lists, config keys, and hooks are documented in EXTENSIONS.md. To build your own, see Developing Custom Extensions and DEVELOPING_EXTENSIONS.md.

Developing Custom Extensions

🧩 The full extension-development guide now lives in its own file: DEVELOPING_EXTENSIONS.md.

MESH-API uses a plugin-based extension system where each extension is a self-contained Python package in the extensions/ directory. Extensions can register slash commands, send/receive mesh messages, react to emergencies, observe all inbound traffic, expose Flask HTTP endpoints, run background polling threads, and act as AI providers — all auto-discovered at startup with no changes to core code.

To build one:

1. Copy the template: cp -r extensions/_example extensions/my_extension
2. Edit the three files — __init__.py (empty), config.json (must include "enabled": true), and extension.py (subclass BaseExtension).
3. Restart MESH-API — it's auto-discovered and loaded.
4. Send /extensions on the mesh to verify it's listed.

📚 Full reference — the complete Base Class API, every lifecycle/message hook, the app_context dict, a step-by-step tutorial, background-thread and Flask-route patterns, best practices, and troubleshooting are all documented in DEVELOPING_EXTENSIONS.md. For the catalog of the 30 built-in extensions and their config keys, see EXTENSIONS.md.

Roadmap

• API Integration Workflow (Planned)

  • A guided workflow for adding new API integrations, including configuration templates, validation checks, and safe test routes before production use.
  • Goal: make it easier to connect external services without editing core code.

• MeshCore Routing Support (Initial Implementation — v0.6.0)

  • MeshCore extension added with bidirectional bridge, command support, and AI integration.
  • Supports USB serial and TCP/WiFi connections to MeshCore companion devices.
  • (Superseded in v0.7.0 — MeshCore is now a first-class core radio; see Running With Meshtastic, MeshCore, or Both.)

Changelog

📜 The full version history has moved to CHANGELOG.md to keep this README short. It covers every release from v0.1 through the current v0.7.4.1 Beta, with both per-release summaries and detailed notes.

Basic Usage

• Interacting with the AI:
  • 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 me