binkterm-php Meshtastic Bridge

Experimental and untested. This bridge has not been tested against live hardware. Expect rough edges. Please report issues at github.com/awehttam/binktermphp-meshtasticbridge/issues.

Python bridge between a Meshtastic device and the binkterm-php packet BBS gateway API.

The bridge connects to a Meshtastic node over TCP (WiFi) or USB serial using the official meshtastic-python library. When another Meshtastic node sends a direct message (DM) to the gateway node, the bridge forwards the text as a command to the BBS API and sends the plain-text response back in chunks sized for the LoRa MTU.

Security note: this bridge should not currently be treated as a hardened secure transport for PacketBBS. Meshtastic support here is experimental and untested, and direct-addressed messages still depend on the trust model of the shared Meshtastic channel rather than verified per-recipient end-to-end privacy.

Requirements

• Python 3.10 or newer
• A Meshtastic device accessible via TCP (WiFi) or USB serial
• A reachable binkterm-php instance with the packet BBS API enabled
• An API key accepted by the BBS packet API

Installation

pip install -r requirements.txt

Configuration

cp bridge.json.example bridge.json

Edit bridge.json:

Key	Description
bbs_url	Full URL of your binkterm-php instance
api_key	PACKET_BBS_API_KEY value from the BBS .env
connection_type	"tcp" (WiFi) or "serial" (USB)
tcp_host	Device IP address (TCP mode only)
tcp_port	Device TCP port (default: 4403)
serial_port	Serial device path (serial mode only, e.g. /dev/ttyUSB0)
gateway_node_id	Your device's node ID as !hex (e.g. !a1b2c3d4), or "auto" to read from the device at startup
max_chunk_chars	Maximum characters per LoRa packet (default: 220)
inter_chunk_delay_ms	Delay between chunks in milliseconds (default: 600)
min_command_interval_seconds	Minimum seconds between commands from the same node (default: 5)
poll_interval_seconds	How often to poll the BBS for queued outbound messages (default: 30)

Usage

python bridge.py
python bridge.py --debug
python bridge.py /path/to/custom-bridge.json

For persistent operation, run via systemd or nohup:

nohup python bridge.py >> bridge.log 2>&1 &

systemd example

[Unit]
Description=binkterm-php Meshtastic Bridge
After=network.target

[Service]
Type=simple
WorkingDirectory=/opt/binktermphp-meshtasticbridge
ExecStart=/usr/bin/python3 bridge.py
Restart=on-failure
RestartSec=10

[Install]
WantedBy=multi-user.target

How it works

1. The bridge connects to the Meshtastic device and subscribes to incoming text messages.
2. When a DM arrives addressed to the gateway node, the bridge:
   • Rate-limits the sender (configurable minimum interval between commands)
   • POSTs the message text to POST /api/packetbbs/command on the BBS
   • Splits the plain-text response into chunks of max_chunk_chars or fewer
   • Sends each chunk back to the originating node with a short inter-chunk delay
3. Every poll_interval_seconds, the bridge polls GET /api/packetbbs/pending for each node that has sent at least one command and delivers any queued BBS messages (e.g. new-mail notifications).

BBS-side setup

1. In the BBS admin panel, enable Packet BBS under BBS Settings.
2. Copy the PACKET_BBS_API_KEY from the BBS .env file into api_key in bridge.json.
3. The gateway node will appear in Admin → BBS Settings → Packet BBS Nodes after its first successful command.

Finding your gateway node ID

If you set gateway_node_id to "auto", the bridge reads the node ID from the device at startup and logs it. Copy this value into bridge.json for subsequent runs so that the BBS correctly identifies which node is the gateway.

Alternatively, run the Meshtastic app on your phone or meshtastic --info on the CLI — the node ID is displayed as ! followed by 8 hex digits.