meshmonitor-chat.el/README.md

MeshMonitor Chat for Emacs

Chat client for MeshMonitor (Meshtastic) in Emacs, inspired by ERC and rcirc.

Requires Emacs 28.1 or later.

Connects directly to the MeshMonitor REST API using a Bearer token. No Meshtastic client or external libraries required.

How it works

  LoRa Radio            MeshMonitor             Emacs
 +-----------+      +----------------+      +------------------+
 | Meshtastic|----->| Web server     |----->| meshmonitor-chat |
 |   Node    |<-----| REST API       |<-----| (this package)   |
 +-----------+      +----------------+      +------------------+
   Physical           Proxy + DB              Chat buffers
   device             (port 3000)             Polling / Send

1. A Meshtastic node sends and receives messages over LoRa radio.
2. MeshMonitor connects to the node (TCP/serial/BLE), caches messages in a database and exposes a REST API.
3. meshmonitor-chat.el talks to the REST API to list channels, fetch messages and send new ones.

Buffers

Channel list (M-x meshmonitor-chat-channels)

  ID  Name          Role
  0   LongFast      Primary
  1   HikingGroup   Secondary
  2   EmergNet      Secondary

Node list (M-x meshmonitor-chat-nodes)

  Hops  Name                           Node ID         Last heard
  1     Hilltop Relay                  !a1b2c3d4       5m
  1     Solar Node 7                   !d4e5f6a7       12m
  2     BaseStation K9                 !b8c9d0e1       now
  3     Mountain Peak                  !f2a3b4c5       1h
  4     River Bridge                   !e6f7a8b9       3d

Chat buffer (channel or DM)

[08:15] <Hilltop Relay> Good morning mesh!
[08:20] <BaseStation K9> Morning! Signal is great today
[08:21] <Solar Node 7> Copy that, 3 hops from here
[08:45] <Mountain Peak> Anyone near the trailhead?
[09:02] <Hilltop Relay> I can see 12 nodes from up here
[09:05] <BaseStation K9> Nice coverage, checking in from base
[09:30] <River Bridge> Just set up a new repeater
[09:31] <Solar Node 7> Welcome aboard!
[09:33] <River Bridge> Thanks, running on solar
[09:40] <Mountain Peak> Can you relay to the valley?
[09:41] <BaseStation K9> Testing now ·
[09:42] <BaseStation K9> Yes, confirmed ✓
#LongFast> _

Features

• Channel list: browse available Meshtastic channels in a tabulated buffer.
• Node list: browse all mesh nodes sorted by hop count, with last-heard time.
• Direct messages: list active DM conversations with other nodes.
• Chat buffers: read and send messages with an ERC-like prompt interface.
• Delivery confirmation: sent messages display · (pending), ✓ (confirmed) or ✗ (failed).
• Polling: automatic periodic fetch of new messages in open chat buffers.
• Input size indicator: mode-line shows byte count with warnings for large messages (LoRa limit ~200 bytes per part, max 3 parts).
• UTF-8 support: correctly displays accented characters and emojis from mesh nodes.
• Message deduplication: avoids rendering the same message twice.
• Input history: navigate previous inputs with M-p / M-n.

Keymap

Channel / Node / DM list buffers

Key	Description
RET	Open channel chat or DM with node
g	Refresh list from server
q	Quit buffer

Chat buffers

Key	Description
RET	Send message
M-p	Previous input from history
M-n	Next input from history

Installation

use-package with :vc (Emacs 29+)

(use-package meshmonitor-chat
  :vc (:url "https://git.andros.dev/andros/meshmonitor-chat.el"
       :rev :newest)
  :config
  (setq meshmonitor-chat-host "192.168.1.100"
        meshmonitor-chat-port 3000
        meshmonitor-chat-token "mm_v1_your_token_here"))

use-package with :load-path

For manual installation or Emacs < 29:

(use-package meshmonitor-chat
  :load-path "/path/to/meshmonitor-chat.el"
  :config
  (setq meshmonitor-chat-host "192.168.1.100"
        meshmonitor-chat-port 3000
        meshmonitor-chat-token "mm_v1_your_token_here"))

Manual

Clone the repository and place the files in a directory on your load-path:

git clone https://git.andros.dev/andros/meshmonitor-chat.el.git

Then add to your init file:

(add-to-list 'load-path "/path/to/meshmonitor-chat.el")
(require 'meshmonitor-chat)
(setq meshmonitor-chat-host "192.168.1.100"
      meshmonitor-chat-port 3000
      meshmonitor-chat-token "mm_v1_your_token_here")

Usage

1. Configure meshmonitor-chat-host, meshmonitor-chat-port and meshmonitor-chat-token in your init file.
2. Run one of the available commands:
   • M-x meshmonitor-chat-channels to browse channels.
   • M-x meshmonitor-chat-nodes to list all nodes sorted by hops.
   • M-x meshmonitor-chat-direct-messages to list DM conversations.
3. Press RET on a channel or node to open the chat buffer.
4. Type your message and press RET to send.

Connection is established automatically on first use.

Customization

Run M-x customize-group RET meshmonitor-chat RET to list all available options.

Key options:

• meshmonitor-chat-host: MeshMonitor server hostname or IP.
• meshmonitor-chat-port (default 3000): server port.
• meshmonitor-chat-token: Bearer token for API authentication.
• meshmonitor-chat-use-tls (default nil): use HTTPS.
• meshmonitor-chat-poll-interval (default 10): seconds between polling for new messages.
• meshmonitor-chat-message-limit (default 50): number of messages to fetch per request.
• meshmonitor-chat-timestamp-format (default "%H:%M"): format for message timestamps.

Username/password authentication is also supported via meshmonitor-chat-username and meshmonitor-chat-password if no token is provided.

API

This package uses the MeshMonitor REST API v1:

• GET /api/v1/channels: list channels.
• GET /api/v1/nodes: list mesh nodes.
• GET /api/v1/messages: fetch messages with filters.
• POST /api/v1/messages: send messages.
• GET /api/status: connection and node info.

See the MeshMonitor documentation for details.

Contributing

Contributions are welcome! Please see the contribution guidelines for instructions on how to submit issues or pull requests.

License

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program. If not, see https://www.gnu.org/licenses/.