TiggyOpenMesh

1. Quick Start

If you just want to get two devices talking, start here. You do not need to understand the protocol, gateway, or code structure first.

What You Need

Recommended Starter Setups

10-Minute Messaging Setup

1. Flash your first device from the web flasher.
2. Flash your second device.
3. On first boot, note the randomly generated AES key or set your own shared key.
4. Make sure both devices use the same AES key.
5. Make sure each device has a different node ID.
6. Open the Android app or use the T-Deck UI.
7. Connect to a node over BLE.
8. Send a short test message to the other node.

Add a Repeater

If you want more range, flash a third node as a repeater and place it between the two endpoints. The mesh will forward traffic automatically when it hears packets that are not for itself.

Add Alerts or Remote Control

Once basic messaging works, connect a relay or sensor to a repeater node. From the Android app or T-Deck you can then read inputs, trigger outputs, and optionally forward group alerts to Telegram when a phone has internet access.

First Things To Configure

• Node ID: each device must be unique
• AES key: every device in the same mesh must share the same key
• Target node: direct message target or FFFF for broadcast
• Telegram settings: optional, only needed for phone-based alert forwarding
• Gateway settings: optional, only needed for map or internet bridging

If It Does Not Work

2. System Overview

TiggyOpenMesh is an off-grid messaging, alerting, and remote-control system built on cheap ESP32 LoRa boards. It is designed for small private networks where you want messages, SOS alerts, sensor inputs, and relay outputs to keep working even when there is no internet or mobile coverage.

System Roles

Key Specs

2. Hardware & Pin Maps

        [USB-C]
D0/GPIO1  ●  ● 5V      RF_SW1 (TX/RX control)
D1/GPIO2  ●  ● GND     Free relay/GPIO
D2/GPIO3  ●  ● 3V3     RST
D3/GPIO4  ●  ● D10/GPIO10  MOSI
D4/GPIO5  ●  ● D9 /GPIO9   MISO  (optional OLED SDA)
D5/GPIO6  ●  ● D8 /GPIO8   SCK   (optional OLED SCL)
D6/GPIO43 ●  ● D7 /GPIO44  CS/NSS

3. Code Architecture

MeshCore Shared Library

All mesh protocol logic lives in lib/MeshCore/. Both firmwares link against it — no duplicate code.

Callback Architecture

Each firmware registers hardware-specific callbacks with MeshCore at startup:

// In setup():
mesh.onTransmitRaw    = radioTransmit;      // Send raw bytes via SX1262/SX1276
mesh.onChannelFree    = radioChannelFree;    // Check RSSI for listen-before-talk
mesh.onMessage        = handleMessage;       // Decrypted message arrived for us
mesh.onCmd            = handleCmd;           // CMD (GPIO control) arrived
mesh.onAck            = handleAck;           // ACK received
mesh.onNodeDiscovered = handleNodeDiscovered;// New node heard for first time
mesh.onIdConflict     = handleIdConflict;    // Another node using our ID detected
mesh.onCfg            = handleCfg;           // Config change request (SF change)
mesh.onCfgAck         = handleCfgAck;        // Config change acknowledged by a node
mesh.onCfgGo          = handleCfgGo;         // Config change committed — apply now

Main Loop Flow (both firmwares)

loop() {
    receiveCheck();                  // Check radio ISR flag, read packet, call mesh.processPacket()
    handleAckRetry();                // Retry unacknowledged messages
    mesh.processPendingForwards();   // Send jitter-delayed forwards

    // Heartbeat (every ~30s with ±2s jitter)
    if (millis() > nextHeartbeatTime)
        mesh.sendHeartbeat();

    // Route cleanup (every 10s)
    mesh.pruneStale();

    // ... GPS, UI, BLE handling ...
}

File Map

4. Packet Format & Protocol

Raw Packet Structure (on the air)

Payload Formats

Data Message Payload

<from>,<to>,<mid>,<ttl>,<route>,<encrypted_hex>

Example: "0001,0002,abcxyz,5,0001,48656C6C6F..."

Fields:
  from          4-char hex sender ID
  to            4-char hex destination (FFFF = broadcast)
  mid           6-char message ID (A-Z random)
  ttl           Remaining hop count
  route         Comma-separated path (e.g. "0001,0003,0005")
  encrypted_hex AES-128-GCM encrypted payload (hex encoded, nonce || ciphertext || tag)

After Decryption — Message Types

Special Packets (unencrypted)

5. Encryption Details

AES Key

• Exactly 16 ASCII characters (128 bits)
• Generated randomly on first boot if no valid key is already stored
• All nodes must share the same key to communicate
• Stored in EEPROM at address 450

AES-128-GCM (Authenticated Encryption)

Each message uses a 12-byte random nonce generated via esp_random(). GCM provides both confidentiality and authentication — no separate CRC needed.

// Encrypted blob format (hex-encoded):
nonce(12 bytes) || ciphertext(N bytes) || tag(16 bytes)

// Decryption: extract nonce, decrypt, verify GCM tag
// If tag check fails → message rejected (tampered or wrong key)

Message ID

6-character random (A-Z), used for deduplication and ACK matching. It is not used as the encryption nonce.

6. Routing & Scalability

Directed Routing Algorithm

This system maintains a routing table and prefers directed forwarding when a route is known. If no route exists, it falls back to a controlled broadcast with random jitter to reduce collision storms.

// Route cost = (hop_count × 10) - RSSI
// Lower is better. Closer nodes with fewer hops win.

Example:
  Route via 0003: cost = (2 hops × 10) - (-85 RSSI) = 105
  Route via 0005: cost = (1 hop  × 10) - (-60 RSSI) = 70  ← winner

Smart Forward Decision

Collision Avoidance

Deduplication

// FNV-1a hash of the 6-char Message ID
hash = 2166136261;    // FNV offset basis
for each char c in mid:
    hash ^= c;
    hash *= 16777619; // FNV prime
hash |= 1;           // Never zero (zero = empty slot)

// Stored in 128-slot ring buffer. O(1) lookup, O(1) insert.

7. T-Deck Plus User Interface

The T-Deck Plus has a full 320×240 colour TFT display with a hardware QWERTY keyboard and trackball. All screens share a consistent layout: header bar (28px), content area, and status bar (18px).

Main Menu

Menu Items Explained

Chat View

Text Input

Settings Submenu

Settings Actions

SOS Mode

Remote Control Panel

First-Boot Wizard

On first power-up (EEPROM magic byte 0xA5 not found), a 3-step wizard guides setup:

1. Step 1: A random 4-hex-char Node ID is auto-generated (e.g. 3FA7) and a 10-second conflict scan runs in the background. A progress bar and countdown are shown on screen. If no conflict is detected, the suggested ID is accepted. If a collision is found, the ID auto-regenerates and re-scans. You can override the ID at any time by typing a custom one.
2. Step 2: Set or accept the AES encryption key (16 chars, pre-filled with default)
3. Step 3: Confirmation screen showing all settings, press Enter to start

Keyboard Controls

Boot Screen

8. Repeater OLED Display

The repeater boards (LoRa32 & Heltec V3) show a 128×64 OLED stats screen that refreshes every 5 seconds.

Display Fields

9. Android App

The companion Android app connects to any repeater node via BLE (Nordic UART Service). It turns any headless board into a full communicator with chat, relay control, sensor monitoring, and remote node management. A foreground BLE service keeps the connection alive when the app is in the background.

App Screens

App Architecture

Remote Node Control

The Control screen includes a node picker dropdown at the top. Select any discovered mesh node to control its relays and read its sensors remotely. Commands are encrypted and sent via MSG,<nodeId>,CMD,... over the mesh. The local node processes commands directly via BLE.

Background BLE

The app uses an Android foreground service (BleConnectionService) to maintain the BLE connection when the app is backgrounded or the screen is off. A persistent notification shows the connection status. This prevents Android from killing the BLE connection during battery optimization.

10. BLE Protocol (Phone ↔ Node)

Commands: Phone → Node

Notifications: Node → Phone

11. Serial Configuration (Repeater)

Connect to the repeater via USB serial at 115200 baud. Same commands work via BLE.

ID <4hex>              Set node ID          e.g. ID 0002
KEY <16chars>          Set AES key          e.g. KEY MySecretKey12345
RELAY <pins>           Set relay GPIO pins  e.g. RELAY 2,4,12,15
SENSOR <pins>          Set sensor GPIO pins e.g. SENSOR 34,36
STATUS                 Show device info
SAVE                   Write config to EEPROM
RESET                  Restore factory defaults
GATEWAY ON             Enable gateway mode (raw packet forwarding)
GATEWAY OFF            Disable gateway mode
PKT,<hex>              Inject raw packet into mesh (gateway mode only)
AUTOPOLL <id> <sec>    Start auto-polling   e.g. AUTOPOLL FFFF 300
AUTOPOLL OFF           Stop auto-polling
PINMODE <pin> <mode>   Set sensor mode      e.g. PINMODE 34 PULSE (or AUTO)
PINMODE <pin> PULSE <ms> Pulse mode + sample window  e.g. PINMODE 5 PULSE 3000
EXPAND ON              Enable IO expansion board on UART2
EXPAND OFF             Disable IO expansion board
SOLAR ON               Enable solar/low-power mode (SX1262 boards only)
SOLAR OFF              Disable solar mode, restore normal operation
BEACON,SCAN            Scan for nearby BLE beacons (2 seconds)
BEACON,ADD,...         Add a beacon detection rule (see iBeacon Scanner)
BEACON,LIST            List all active beacon rules
BEACON,CLEAR           Delete all beacon rules
SETPOINT,...           Add a cross-node setpoint rule (see Setpoints)
SETPOINT,LIST          List all active setpoint rules
SETPOINT,CLEAR         Delete all setpoint rules
REBOOT                 Restart the node (settings preserved)
EEPROM,RESET           Factory reset — wipe all EEPROM and restart
GPSPOS                 Query current GPS position
GPS,<tx>,<rx>          Set GPS UART pins e.g. GPS,38,39

# STATUS response includes:
#   ID, BOARD, POWER:NORMAL|SOLAR, SF:9, RELAY pins, SENSOR pins

12. Quick Phrase System

The T-Deck's phrase picker lets you compose messages from pre-defined phrases without typing. Phrases are sent as hex IDs (e.g. $0A|$1E) and expanded on receipt — extremely bandwidth-efficient.

Wire format example: Selecting "I AM OK" + "AT CAMP" + "NEED WATER" sends: $00|$16|$0B (6 bytes instead of 30)

13. GPIO Remote Control Protocol

GPIO commands are encrypted and routed through the mesh like regular messages. A T-Deck or phone app can control relays on any reachable node.

Command Format (inside encrypted payload)

14. Relay Timers

Up to 4 concurrent relay timers can be set via BLE, serial, or mesh command. Timers are ephemeral (not saved to EEPROM) and lost on reboot.

Timer Commands

Behaviour

• Setting a timer on a pin that already has one overwrites the existing timer.
• When a timer fires, the node sends TIMER,FIRED,<pin>,ON|OFF over BLE.
• When a repeating pulse completes, it sends TIMER,DONE,<pin>.
• Timers work via both BLE and mesh (CMD,TIMER,...).

Example: Irrigation Pump

# Turn on pump (GPIO 4) for 30 minutes, then off
TIMER,4,ON,0             # ON immediately
TIMER,4,OFF,1800          # OFF after 30 min

# Pulse: 5 min on, 10 min off, repeat 3 times
TIMER,4,PULSE,300,600,3

15. Cross-Node Setpoint Rules

Setpoints are conditional automation rules that run on the node itself — no gateway needed. The node reads its own sensor, evaluates the condition locally, and only uses the radio when the condition triggers. This is far more efficient than gateway-polled rules.

Two Action Types

Operators

Optional Suffixes: Scale & Debounce

Append these to any setpoint command to add signal processing on the node:

Safety Features

• Hysteresis: After triggering, the sensor must move past the threshold by 10% in the opposite direction before re-triggering.
• Cooldown: 10-second minimum between triggers per rule.
• One TX per loop cycle: If multiple setpoints trigger simultaneously, only one radio transmission happens per loop iteration. This prevents back-to-back transmissions that could interfere with packet reception.
• Local relay shortcut: When the target node is the same as the sensor node, digitalWrite() is called directly — no radio packet is generated at all.
• When a setpoint fires, the node sends SETPOINT,FIRED,<sensorPin>,<value> over BLE for monitoring.

Examples

# Gate monitor: broadcast "Gate open" / "Gate closed" on digital input change
SETPOINT,5,EQ,1,MSG,Gate open,Gate closed

# Wind alarm: Scale raw pulse rate to m/s, alarm if >= 15 m/s, debounce 3s
SETPOINT,5,GE,15.0,0010,2,1,SCALE,0.4524,0,DEBOUNCE,3000

# Frost protection: Scale ADC to °C, trigger heater when < 3°C
SETPOINT,34,LT,3.0,0010,4,1,SCALE,0.0244,-10.0

# Local relay: target is self (same node), no radio needed
SETPOINT,34,GT,2000,0001,4,1
# (where 0001 is this node's own ID)

16. Sensor Monitoring & Auto-Poll (SDATA)

Nodes can read local analog/digital sensors and broadcast bundled sensor data (SDATA) across the mesh for remote monitoring.

SDATA Format

SDATA,<nodeID>,<pin1>:<value1>,<pin2>:<value2>,...

# Example: Node 0010 reporting 3 sensors
SDATA,0010,34:2048,36:1200,39:4095

Reading Sensors

Auto-Poll (Periodic Broadcasting)

Auto-Poll sends SDATA to a target node at a regular interval. Ideal for unattended sensor stations that periodically report readings.

Sensor Pin Types

Default Sensor Pins per Board

Farming & Environmental Monitoring

The sensor system is designed for unattended outdoor monitoring. Typical setup:

• Wind speed: Analog anemometer (0-3.3V output) → GPIO 34 or 36
• Temperature: NTC thermistor with voltage divider → GPIO 39
• Soil moisture: Capacitive sensor (0-3.3V) → GPIO 36
• Rain gauge: Tipping bucket (digital pulse) → any digital GPIO

Connect sensors to a solar-powered repeater node (see Section 24: Solar Mode), configure AUTOPOLL to send readings every 5 minutes to a gateway node, and monitor via the PC gateway GUI, hub GUI, or web map — all with sparkline charts.

Viewing Sensor Data

• Android app: Control screen shows live sparkline charts per sensor pin with min/max labels.
• PC Gateway GUI — Sensors tab: Full sensor dashboard with circular gauge widgets (colour gradient, needle, min/max tracking), matplotlib line charts with configurable history length, and a toolbar for pause/resume, clear, and CSV export (saved to gateway/exports/).
• Hub GUI: Sensor Monitor canvas with sparklines for all sensors across all gateway-connected nodes.
• Web Map: Sensor bar at the bottom of the map page. Enter your 16-char AES key to decrypt sensor data client-side — the hub never sees plaintext. Sparkline cards auto-update every 5 seconds.

17. Pulse Counter Mode (Wind Speed, Flow Meters)

Sensor pins can be switched from analog/digital read mode to pulse counter mode, where hardware interrupts count rising-edge pulses. The firmware calculates pulses per second over a configurable sample window, so SDATA and setpoint rules work with rate values, not raw counts.

How It Works

• Up to 4 sensor pins can be set to pulse mode simultaneously.
• Each pin uses a dedicated hardware interrupt (IRAM_ATTR ISR, <1μs execution).
• The firmware calculates pulses per second using a configurable sample window (default 5 seconds). The SDATA response returns rate × 100 (centipulses per second) for integer precision.
• Pulse counters do not interfere with radio reception — the ISR is a single atomic increment that completes in nanoseconds, while LoRa packet reception takes milliseconds.
• Use a setpoint with SCALE to convert the rate to engineering units on the node itself (e.g., pulses/sec → m/s for wind speed).

Commands

Rate Calculation

Every sample window (default 5 seconds), the firmware reads the pulse count, calculates the delta since last read, and divides by elapsed time to get pulses per second. The SDATA value for pulse pins is rate × 100 — so a reading of 470 means 4.70 pulses per second.

Example: Wind Speed from Anemometer

# Configure sensor pin 5 for pulse counting (3-second window)
PINMODE 5 PULSE 3000

# SDATA response shows rate × 100 (centipulses/sec):
# SDATA,0010,5:470,36:2048
#   pin 5: 470 = 4.70 pulses/sec
#   pin 36: 2048 (analog read, temperature sensor)

# On-node setpoint: scale pulse rate to m/s, alarm at 15 m/s
# For an anemometer with 7.2cm arm, 1 PPR:
#   speed_ms = pulses_per_sec × 2π × 0.072 = rate × 0.4524
# But SDATA gives rate×100, so scaleFactor = 0.4524 / 100 = 0.004524
SETPOINT,5,GE,15.0,0010,2,1,SCALE,0.004524,0

18. SOS Emergency Alert

The mesh network includes a built-in SOS emergency system. When triggered, an SOS alert is broadcast to all nodes on the mesh with the sender's GPS location (if available), and forwarded to Telegram.

Sending an SOS

• Android App: Press the red SOS button in the Chat screen header bar. A confirmation dialog prevents accidental triggers. The app automatically attaches your phone's GPS coordinates.
• T-Deck Plus: SOS can be sent as a broadcast message: SOS,lat,lon

SOS Message Format

# With GPS fix:
SOS,51.481583,-3.178500

# Without GPS:
SOS

What Happens When SOS Is Received

• All nodes display the SOS alert with the sender's ID.
• The Android app plays a notification sound and shows the message in chat.
• If Telegram is configured, the app forwards the SOS with a Google Maps link to the configured chat.
• Gateways relay the SOS to all connected mesh islands via the hub.

19. EEPROM Memory Map

512 bytes of EEPROM store persistent configuration. Layout is identical across all boards.

20. Building & Flashing

Prerequisites

• PlatformIO CLI or PlatformIO IDE (VSCode extension)
• USB driver for your board (CP2102 for LoRa32, CH340 for Heltec V3, native USB for T-Deck & Heltec V4)

Build Commands

# Build all 4 targets
pio run

# Build specific target
pio run -e tdeck-plus
pio run -e lora32
pio run -e heltec-v3
pio run -e heltec-v4

# Flash specific target (with board connected)
pio run -e heltec-v4 --target upload

# Open serial monitor
pio device monitor -b 115200

# Clean build
pio run -e lora32 --target clean

Build Isolation

PlatformIO uses build_src_filter to ensure each target only compiles its firmware:

Android App

# Open in Android Studio:
android-app/

# Build: compileSdk 34, minSdk 26
# Dependencies: Jetpack Compose BOM 2024.01, BLE

21. Gateway Bridge — Internet-Linked Mesh Islands

The gateway feature connects geographically separated LoRa mesh networks over the internet. Each gateway node is a repeater connected via USB to a PC running the Python bridge server. Packets remain AES-128-GCM encrypted end-to-end — the servers never decrypt them.

Hub Architecture (Recommended)

The simplest way to connect multiple mesh islands is using a central hub server. Each location runs a gateway that connects to the hub. Gateways only need the hub's address — no complex peer-to-peer configuration.

  ISLAND A              CENTRAL HUB              ISLAND B
                       (cloud server or VPS)

  [Node 0001]                                         [Node 0005]
       |                                                   |
  [Repeater 0003]                                    [Repeater 0007]
       |                                                   |
  USB Serial                                          USB Serial
       |                                                   |
  ┌──────────────┐     ┌──────────────┐     ┌──────────────┐
  │ Gateway A    │────>│ Gateway Hub  │<────│ Gateway B    │
  │ "Base Camp"  │     │ (relay only) │     │ "Ridge Post" │
  └──────────────┘     └──────┬───────┘     └──────────────┘
  laptop at camp              │            PC at ridge post
                              │
                     ┌──────────────┐
                     │ Gateway C    │
                     │ "Town HQ"    │
                     └──────────────┘
                     office in town

System Components

How It Works — Step by Step

1. A node on Island A sends an encrypted message destined for a node on Island B
2. The repeater on Island A receives the packet over LoRa radio — MeshCore processes it normally (routing, forwarding)
3. Because gateway mode is enabled, the repeater also outputs the raw packet bytes over USB serial as PKT,<hex>
4. The Python gateway client (gateway.py) reads this line and sends it to the central hub via WebSocket
5. The hub (gateway_hub.py) relays the packet to all other connected gateways
6. Gateway Client B receives the packet and injects it into Island B's mesh via PKT,<hex> over serial
7. The repeater on Island B transmits the raw packet over LoRa radio
8. The destination node receives and decrypts the message — end-to-end encryption preserved

Security Model

Serial Protocol (Repeater ↔ Gateway Client)

WebSocket Protocol

All WebSocket messages are JSON. The hub understands three message types:

Authentication (Gateway → Hub)

// Python gateway (PC-based)
{
  "type":       "auth",
  "gateway_id": "3f8a1b2c",       // Unique ID (auto-generated)
  "name":       "Base Camp",      // Friendly name (--name flag)
  "key":        "MySecretKey"     // Hub auth key (--hub-key flag)
}

// ESP WiFi gateway (includes location for map)
{
  "type":    "auth",
  "key":     "MySecretKey",
  "id":      "AA:BB:CC:DD:EE:FF",  // WiFi MAC
  "name":    "Ridge Top",
  "lat":     51.5074,              // GPS latitude
  "lon":     -3.1791,              // GPS longitude
  "antenna": 2,                    // 0=indoor 1=external 2=rooftop
  "height":  10.0                  // Antenna height in metres
}

Auth Response (Hub → Gateway)

{
  "type":    "auth_result",
  "success": true,
  "peers":   2                   // Number of other gateways online
}

Packet Relay (bidirectional)

{
  "type":   "pkt",
  "data":   "A50012...",        // Hex-encoded raw radio packet
  "origin": "3f8a1b2c"          // Source gateway ID (prevents echo loops)
}

Peer Events (Hub → Gateway)

{
  "type": "peer_joined",        // or "peer_left"
  "name": "Ridge Post",
  "peers": 3                    // Total gateways now online
}

Deduplication

Both the hub and each gateway maintain time-expiring hash sets to prevent packets from bouncing in loops:

Additionally, the origin field in each packet prevents a gateway from re-processing packets it originally sent.

Complete Setup Guide

Step 1: Flash the Repeaters

Each location needs a repeater board (LoRa32 or Heltec V3) connected to a PC via USB.

# Flash a LoRa32 as a repeater
pio run -e lora32 --target upload

# Configure via serial (115200 baud):
ID 0003                      # Unique node ID for this repeater
KEY MySecretKey12345         # Must match ALL nodes in the mesh
SAVE

Step 2: Set Up the Hub Server

The hub runs on any always-on machine with a public IP or port forwarding. It does not need a LoRa radio — it's purely a network relay.

# On your server/VPS:
cd gateway/
pip install -r requirements.txt

# Start hub (open, no authentication)
python gateway_hub.py --listen 9000

# Start hub WITH authentication (recommended)
python gateway_hub.py --listen 9000 --key MySecretMeshKey

Step 3: Connect Gateways to the Hub

At each location, run gateway.py pointing to the hub:

# At Location A:
python gateway.py --port COM3 --hub ws://your-server.com:9000 \
    --hub-key MySecretMeshKey --name "Base Camp"

# At Location B:
python gateway.py --port COM5 --hub ws://your-server.com:9000 \
    --hub-key MySecretMeshKey --name "Ridge Post"

# At Location C:
python gateway.py --port /dev/ttyUSB0 --hub ws://your-server.com:9000 \
    --hub-key MySecretMeshKey --name "Town HQ"

That's it. The gateway automatically:

• Opens the serial port and sends GATEWAY ON to the repeater
• Connects to the hub and authenticates
• Forwards radio packets to the hub, and injects hub packets into the local mesh
• Reconnects automatically if the hub or serial connection drops
• Sends GATEWAY OFF on graceful shutdown (Ctrl+C)

Step 4: Network Configuration

Advanced: Direct Peer-to-Peer Mode

For two-site setups or when you don't want a central hub, gateways can connect directly to each other:

# Site A (listens for inbound connections)
python gateway.py --port COM3 --listen 9000

# Site B (connects to Site A)
python gateway.py --port COM5 --listen 9001 --peers ws://siteA-ip:9000

In this mode, each gateway must know every other gateway's address. For 3+ sites, the hub mode is strongly recommended.

Topology Options

CLI Reference

gateway.py (runs at each site)

gateway_hub.py (runs once, centrally)

OLED Gateway Indicator

When gateway mode is active, the repeater OLED displays GW in the top-right status area instead of the BLE indicator. The STATUS serial command and BLE status response also include the gateway state.

Gateway File Structure

gateway/
  gateway.py              # Gateway client — headless (Linux/Windows CLI)
  gateway_gui.py       ★ # Gateway client — Windows GUI (topology view + packet waterfall)
  gateway_hub.py          # Central hub server — headless (Linux/Windows CLI)
  gateway_hub_gui.py      # Central hub server — Windows GUI (live dashboard)
  automation_engine.py ★ # Logic Builder evaluation engine — rule model, persistence, anti-flood
  automation_canvas.py ★ # Logic Builder visual canvas — drag, connect, configure blocks
  telegram_bot.py      ★ # Telegram bot bridge — exposes rules as chat commands
  meshtastic_bridge.py ★ # TiggyOpenMesh ↔ Meshtastic bidirectional bridge
  sensor_dashboard.py  ★ # Sensor gauges, line chart, CSV export (Sensors tab)
  rules.json              # Auto-generated Logic Builder rules (JSON persistence)
  requirements.txt        # Python dependencies: pyserial, websockets, aiohttp, customtkinter
  gateways.json           # Auto-generated gateway registry (location persistence)
  web/
    map.html              # Live gateway coverage map (Leaflet.js, served by hub)

Gateway GUI — Feature Overview

The Windows GUI client (gateway_gui.py) provides a comprehensive dashboard with four main tabs:

Additional GUI integrations above the tabs:

• Telegram Bot: Enter bot token and chat ID, click Start Bot. See Section 40.
• Meshtastic Bridge: Select a second serial port and click Start Bridge. See Section 39.
• Hub connection: Enter wss:// URL, gateway name, hub key, lat/lon, and antenna height. All settings are saved between sessions.

22. Logic Builder — Visual Automation for the Gateway GUI

The Logic Builder is a PLC-style visual automation system built into the PC gateway GUI. It lets you create cross-node automation rules by dragging and connecting blocks on a canvas — like ladder logic or Scratch, but for your mesh network. Rules evaluate sensor data received from the mesh and fire actions (relay control, messages) back through the mesh.

Opening the Logic Builder

Click the Logic tab at the bottom of the gateway GUI (alongside Packets and Sensors tabs). The automation canvas appears below the mesh topology map. Rules continue evaluating in the background regardless of which tab is active.

Creating a Rule

1. Click [+ New] in the toolbar to create a new rule. Give it a descriptive name (e.g., “Wind alarm”, “Gate monitor”).
2. Use the [+ Input], [+ Transform], [+ Condition], and [+ Action] dropdown buttons to add blocks to the canvas.
3. Double-click any block to configure it (choose node ID, pin number, operator, etc.).
4. Connect blocks by clicking an output port (right side, coloured dot) then clicking a compatible input port (left side) on another block.
5. Set the Check every interval and Min action gap (see below).
6. Tick Enabled to activate the rule.

Block Types

Input Blocks (cyan border)

Input blocks read data from the mesh or provide constant values.

Transform Blocks (green border)

Transform blocks convert raw sensor values into meaningful units.

Condition Blocks (yellow border)

Condition blocks evaluate true/false logic to decide when actions should fire.

Action Blocks (red border)

Action blocks send commands to the mesh when their trigger input transitions from false to true (rising edge).

Connecting Blocks (Wires)

Blocks have ports — small coloured dots on the left (inputs) and right (outputs) of each block:

• Cyan dot = number value (sensor reading, scaled value, constant)
• Yellow dot = boolean value (true/false from comparisons, gates)
• White dot = string value (text)

To connect: click an output port on one block, then click a compatible input port on another block. A smooth Bezier curve wire appears between them. Live values are displayed on wires during evaluation (e.g., “23.4”, “True”).

Toolbar Settings

Canvas Interactions

Safety & Anti-Flood Features

With many rules across many nodes, actions could flood the LoRa channel. The Logic Builder includes multiple layers of protection:

• Command queue with spacing: Actions do not send immediately. They are placed in a global command queue that drains one command every 3 seconds. This prevents multiple rules from firing back-to-back and overwhelming the LoRa channel. The queue holds up to 20 pending commands; excess commands are dropped with a warning.
• Rising-edge detection: Action blocks only fire when their trigger changes from false to true. A sustained “true” condition does not keep firing repeatedly.
• Per-rule action gap: After an action fires, the same rule cannot fire again until the min action gap elapses (default 10 seconds). Prevents oscillation when a sensor value bounces around a threshold.
• Global rate limit: Maximum 12 commands per minute to the mesh, across all rules. A hard safety backstop on top of the queue spacing.
• Queue status display: The event log shows how many commands are pending (e.g., “Queue: 3 pending”). The text turns yellow when the queue exceeds 5 items, giving early warning of congestion.
• Stale data warning: If a sensor reading is older than 5 minutes, the Sensor Read block shows a “Stale” warning. Action blocks never fire when any input in the chain has no data (None propagation).
• Auto-poll coordination: The engine automatically sends POLL requests to nodes referenced by active rules if their data is stale, at most once every 30 seconds per node.
• Encryption preserved: The gateway never decrypts mesh packets for automation. It sends plaintext serial commands to the locally connected node, which encrypts them before transmission over LoRa.

Deploy to Node (Firmware Setpoints)

For rules that match the firmware setpoint format, you can push the rule directly to a node so it runs autonomously without the gateway. Click the [Deploy] button to attempt this. Deployed rules use zero radio for monitoring — they only transmit when the condition triggers.

A rule can be deployed as a firmware setpoint if it contains:

1. One Sensor Read block
2. One Compare block (any operator: >, <, =, ≥, ≤, ≠)
3. One action: Set Relay or Broadcast Message
4. Optionally one Scale block (factor + offset applied before comparison)
5. Optionally one Debounce block (hold time before firing)
6. One Constant block (the threshold value)

The gateway builds an expanded SETPOINT command with optional suffixes:

SETPOINT,<pin>,<op>,<threshold>,<target>,<relayPin>,<action>[,SCALE,<f>,<o>][,DEBOUNCE,<ms>]
SETPOINT,<pin>,<op>,<threshold>,MSG,<msgTrue>[,<msgFalse>][,SCALE,<f>,<o>][,DEBOUNCE,<ms>]

Smart Deploy

The [Deploy] button analyses your rule chain and picks the best deploy strategy automatically:

Node Management (Right-Click Menu)

Right-click any node card in the Discovered Nodes panel to access management commands:

Example Rules

Example 1: Wind Speed Alarm

Sound an alarm relay on a base-station node when wind speed exceeds 15 m/s.

[Sensor Read] ──→ [Scale] ──→ [Compare] ──→ [Set Relay]
  A1B2:pin5          ×0.0278     > 15.0          C3D4:pin2=HIGH
  "Anemometer"       m/s         ↑
                              [Constant: 15]

Sensor Read gets the raw pulse count from node A1B2 pin 5. Scale converts pulses to m/s. Compare checks if the speed exceeds the constant 15. Set Relay activates pin 2 on node C3D4.

Example 2: Gate Monitor with Messages

Broadcast “Gate open” or “Gate closed” based on a digital input.

[Sensor Read] ──→ [Compare] ──→ [Send Broadcast]
  F1E2:pin5           = 1           "Gate open" / "Gate closed"
  "Gate Sensor"       ↑
                  [Constant: 1]

Sensor Read gets the digital value (0 or 1) from node F1E2 pin 5. Compare checks if it equals 1. Send Broadcast sends “Gate open” when true, “Gate closed” when the trigger goes false.

Example 3: Frost Protection with Debounce

Only activate a heater if temperature stays below threshold for 30 seconds (avoids reacting to brief cold gusts).

[Sensor Read] ──→ [Scale] ──→ [Compare] ──→ [Debounce] ──→ [Set Relay]
  0010:pin34         ×0.1-40      < 3.0           30 sec          0010:pin4=HIGH
  "Temp Sensor"      °C           ↑               hold            "Heater"
                              [Constant: 3.0]

Scale converts raw ADC (0–4095) to degrees Celsius. Compare checks if temp is below 3°C. Debounce waits 30 seconds of continuous “true” before allowing the Set Relay to fire.

Persistence

All rules are automatically saved to gateway/rules.json whenever you make changes. Rules are reloaded when you restart the gateway GUI. The file stores block positions, configurations, wire connections, and rule settings.

Event Log

The bottom of the Logic Builder panel shows a one-line event log with timestamped status messages:

• Evaluation results: e.g., 14:23 eval OK — 3 blocks
• Action firings: e.g., 14:23 SET_RELAY C3D4:pin2=1
• Errors: e.g., 14:23 ERROR: node A1B2 data stale

23. WiFi ESP Gateway — No PC Required

The WiFi gateway firmware turns any ESP32 board into a standalone internet bridge. Unlike the PC-based gateway, it needs no computer — just power. Flash it, configure once via the Android app over BLE, mount it outside with a solar panel, and it runs forever.

Old method:  LoRa nodes → ESP repeater → USB cable → PC → WebSocket → Hub
New method:  LoRa nodes → ESP gateway → WiFi → WebSocket → Hub

Supported Boards

Step 1 — Flash the Gateway Firmware

Use the web flasher, select your board under WiFi Gateway, and click Flash.

Step 2 — Configure via Android App

Open the Android app, tap Connect to pair with the gateway over BLE, then send these commands from the terminal/config screen:

WIFI,YourSSID,YourPassword       Set WiFi network
HUBURL,ws://hub.example.com:9000 Hub WebSocket address
HUBKEY,your-secret-key           Hub auth key (must match hub)
GWNAME,Ridge Top Gateway         Friendly name shown on hub
GWLOC,51.5074,-3.1791            Lat/lon (optional, for map)
GWANTENNA,1                      0=indoor  1=external  2=rooftop
GWHEIGHT,10                       Antenna height in metres (0-500)
SAVE                              Write to flash and reboot

The gateway reboots, connects to WiFi, and begins bridging. The OLED shows the WiFi IP and hub connection status.

GWSTATUS — Check Connection

GWSTATUS   Returns: name, WiFi IP, hub connected/disconnected, RX/TX counts, HEIGHT

Solar Deployment Guide

Total BOM for a self-powered tree-mounted gateway:

Power draw: ESP32S3 active ~160mA @ 3.3V = 0.53W. A 2W panel fully charges a 2000mAh cell in ~4 hours of sun. Runs 15+ hours overnight on the cell alone.

Hub Setup (Linux / Tailscale)

The hub runs on any always-on Linux machine (Debian, Ubuntu, Raspberry Pi, etc). The automated setup script handles everything — Python, systemd service, and Tailscale Funnel:

# Download and run the setup script (Debian/Ubuntu)
curl -fsSL https://raw.githubusercontent.com/MichaelGaylor/Tiggy_Lora_Mesh/main/gateway/setup-hub-linux.sh -o setup.sh
bash setup.sh

The script will:

1. Install Python and aiohttp (the hub's HTTP/WebSocket server library)
2. Optionally install Tailscale and connect to your account
3. Create a systemd service that auto-starts on boot (tiggyopenmesh-hub.service)
4. Optionally enable Tailscale Funnel for a public wss:// URL

Manual Setup (without the script)

If you prefer to set things up manually or the script doesn't suit your distro:

# 1. Install dependencies
sudo apt-get install -y python3 python3-pip
pip3 install --break-system-packages aiohttp

# 2. Copy gateway files to your home directory
#    You need: gateway_hub.py, gateway_hub_gui.py, gui_common.py
#    And: web/map.html (create a web/ folder next to gateway_hub.py)
cp gateway_hub.py gateway_hub_gui.py gui_common.py ~/
mkdir -p ~/web && cp web/map.html ~/web/

# 3. Test it works
python3 ~/gateway_hub.py --listen 8443
# Open http://localhost:8443/ in a browser — you should see the map

# 4. Create systemd service for auto-start on boot
sudo tee /etc/systemd/system/tiggyopenmesh-hub.service > /dev/null <<EOF
[Unit]
Description=TiggyOpenMesh Gateway Hub
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
User=$USER
WorkingDirectory=$HOME
ExecStart=/usr/bin/python3 $HOME/gateway_hub.py --listen 8443
Restart=always
RestartSec=10
StandardOutput=journal
StandardError=journal

[Install]
WantedBy=multi-user.target
EOF

sudo systemctl daemon-reload
sudo systemctl enable tiggyopenmesh-hub
sudo systemctl start tiggyopenmesh-hub

To enable Funnel manually after setup:

# Enable Tailscale Funnel on port 8443 (runs persistently in background)
sudo tailscale funnel --bg 8443

# Check the public URL assigned to your machine
tailscale funnel status
# → https://your-machine.tail1234.ts.net

Configure each gateway via BLE with:

HUBURL,wss://your-machine.tail1234.ts.net
SAVE

No port forwarding, no dynamic DNS, free SSL certificate. The hub service and Funnel both survive reboots automatically.

Accessing the Map and GUI

The headless hub serves the Live Gateway Map as a web page on the same port as the WebSocket relay. Multiple users can open it simultaneously — it's a read-only page that refreshes every 10 seconds:

If your Linux box has a desktop environment (XFCE, GNOME, KDE, etc), you can create desktop shortcuts for quick access:

Desktop shortcut: Open Map in browser

cat > ~/Desktop/TiggyOpenMesh-Map.desktop <<'EOF'
[Desktop Entry]
Version=1.0
Type=Application
Name=TiggyOpenMesh Map
Comment=Open the live gateway coverage map in your browser
Exec=xdg-open http://localhost:8443/
Icon=applications-internet
Terminal=false
Categories=Network;
EOF
chmod +x ~/Desktop/TiggyOpenMesh-Map.desktop

Desktop shortcut: GUI Dashboard

The GUI version (gateway_hub_gui.py) shows a full desktop dashboard with live packet flow visualisation, connected gateway table, and statistics. It requires customtkinter:

pip3 install --break-system-packages customtkinter

Since the GUI and headless hub both use the same port, the launcher script stops the headless service before starting the GUI, then restarts it when the GUI window is closed:

# Create launcher script
cat > ~/start_hub_gui.sh <<'EOF'
#!/bin/bash
sudo systemctl stop tiggyopenmesh-hub 2>/dev/null
sleep 1
cd ~/
python3 ~/gateway_hub_gui.py
sudo systemctl start tiggyopenmesh-hub 2>/dev/null
EOF
chmod +x ~/start_hub_gui.sh

# Create desktop shortcut
cat > ~/Desktop/TiggyOpenMesh-Hub.desktop <<'EOF'
[Desktop Entry]
Version=1.0
Type=Application
Name=TiggyOpenMesh Hub
Comment=Gateway Hub Dashboard - stops headless service, opens GUI
Exec=bash ~/start_hub_gui.sh
Icon=network-workgroup
Terminal=false
Categories=Network;
EOF
chmod +x ~/Desktop/TiggyOpenMesh-Hub.desktop

Hub Management

# View live logs
sudo journalctl -u tiggyopenmesh-hub -f

# Restart hub (e.g. after updating gateway_hub.py)
sudo systemctl restart tiggyopenmesh-hub

# Check status
sudo systemctl status tiggyopenmesh-hub

# Update hub files from the repo
cd ~/
curl -fsSL https://raw.githubusercontent.com/MichaelGaylor/Tiggy_Lora_Mesh/main/gateway/gateway_hub.py -o gateway_hub.py
curl -fsSL https://raw.githubusercontent.com/MichaelGaylor/Tiggy_Lora_Mesh/main/gateway/web/map.html -o web/map.html
sudo systemctl restart tiggyopenmesh-hub

24. Solar / Low-Power Repeater Mode

Remote repeater nodes on hilltops or rooftops often need to run indefinitely from a small solar panel and an 18650 battery. Solar mode dramatically reduces power consumption by putting the ESP32-S3 into light sleep between radio events, while keeping the radio in continuous RX so no packets are lost.

Power Budget

With a 3000 mAh 18650: ~11 days on battery alone.
With a 1W solar panel: indefinite operation.

How It Works

• OLED disabled — Vext is powered off, turning off the OLED display. Press the PRG button to temporarily show status for 10 seconds.
• BLE deinitialised — Bluetooth is fully shut down, saving ~15 mA and freeing ~60 KB RAM. The phone app cannot connect in solar mode.
• ESP32-S3 light sleep — between radio events, the CPU enters light sleep (~0.8 mA). All RAM is preserved and GPIO config stays active. The CPU wakes instantly on:
• DIO1 interrupt (radio packet received)
• PRG button press (shows OLED status temporarily)
• 60-second timer (for heartbeat transmission)
• Serial input (for SOLAR OFF command)
• Radio stays in continuous RX — no packets are lost. The SX1262 fires DIO1 when a preamble is detected, instantly waking the CPU to process the packet.
• Reduced heartbeat — heartbeats are sent every 60 seconds (vs 30s in normal mode), with longer jitter, reducing TX duty cycle.

Activation

Via Serial (USB)

# Enable solar mode (persists across reboots)
SOLAR ON

# Disable solar mode and restore normal operation
SOLAR OFF

# Check status (works in solar mode)
STATUS

Via BLE (Android App)

# Enable solar mode (SX1262 boards only)
POWER,SOLAR     → OK,POWER,SOLAR (BLE then disconnects!)

# Disable solar mode
POWER,NORMAL    → OK,POWER,NORMAL

Via Android App Settings Screen

The app's Settings tab shows a Power Mode card for SX1262-based repeater boards. It displays the current mode from the STATUS response and provides a toggle with a confirmation dialog.

Solar mode is persisted to EEPROM — the node will boot directly into solar mode after a power cycle. No need to re-send the command.

Behaviour in Solar Mode

Recommended Hardware Setup

• Board: Heltec V4 (28 dBm TX power, native solar input, 16 MB flash)
• Battery: 18650 Li-Ion, 3000+ mAh (protected cell recommended)
• Solar panel: 5V, 1W minimum (e.g. 110×60mm panel). Connect to the Heltec V4's solar input pad.
• Enclosure: IP65 waterproof box with cable glands for antenna and solar panel.
• Antenna: External antenna with SMA pigtail for best range.

25. Message Delivery Tracking

Every message sent through the mesh now has end-to-end delivery confirmation. The sender knows exactly whether the message was transmitted, delivered, or failed — with visual status indicators on both the T-Deck and the Android app.

Delivery States

How It Works

1. Sender transmits message — state set to SENDING
2. Radio confirms transmission complete — firmware sends SENT,<mid> to BLE, state becomes SENT
3. Recipient decrypts the message successfully and sends back a directed plain ACK,<from>,<mid> packet to the original sender
4. Sender receives the ACK — state becomes DELIVERED
5. If no ACK arrives within 3 seconds, state becomes FAILED (the message may still have been received — the ACK could have been lost)

Visual Indicators

BLE Protocol

26. Spreading Factor Change Protocol

LoRa Spreading Factor (SF) controls the trade-off between range and speed. Changing SF requires all nodes to switch simultaneously — a node on SF7 cannot hear one on SF12. The two-phase CFG protocol ensures safe, coordinated changes across the entire mesh.

SF Values

Two-Phase Change Protocol

Phase 1: Propose & Collect ACKs

Phase 2: Commit

Auth Tags

CFG and CFGGO packets include an 8-hex-char auth tag computed using AES-128-GCM:

authTag = truncate(GCM_tag(key, IV=SHA(changeId), AAD=changeId), 4 bytes)
// Deterministic IV derived from changeId for reproducible verification

Receiving nodes verify the tag before accepting any CFG or CFGGO packet. This prevents:

• Unauthorized changes — an attacker without the AES key cannot forge a valid tag
• Cross-mesh interference — adjacent meshes with different keys ignore each other's CFG packets

Packet Formats

BLE Commands

Timing & Safety

• 2-second delay after CFGGO before applying — ensures packet propagates across multi-hop mesh
• SF persisted to EEPROM (address 431) — survives reboot
• Runtime SF stored in mesh.currentSF — may differ from compile-time LORA_SF
• Reversible: send another SF,9 + SFGO,9 to change back

27. Node ID Collision Detection

Node IDs are 4-hex-char values (0001–FFFE) — 65534 possible addresses. As networks grow, or when default IDs are used, collisions become likely. Two nodes with the same ID cause routing chaos — messages get misdelivered, heartbeats overwrite routes, and the mesh becomes unreliable.

Detection Mechanism

Collision detection piggybacks on the existing heartbeat system (no new packets, no extra airtime):

1. Every node broadcasts HB,<nodeID> every ~30 seconds
2. In processPacket(), if the heartbeat's node ID matches our own localID, a collision is detected
3. The onIdConflict callback fires with the conflicting ID and RSSI
4. The heartbeat is not processed as a normal peer (not added to routing table)

// In MeshCore::processPacket() — heartbeat handler
if (hbFrom == String(localID)) {
    idConflictDetected = true;
    if (onIdConflict) onIdConflict(hbFrom, lastRSSI);
    return;  // Don't add ourselves as a peer
}

Alert Behaviour

First-Boot Conflict Scan

Both repeaters and T-Deck devices perform an automatic conflict scan on first boot:

28. Display Auto-Sleep (T-Deck Plus)

The T-Deck's 2.8" TFT backlight draws significant power. Display auto-sleep turns off the backlight after a configurable idle period, extending battery life for portable use.

Behaviour

Configuration

Set via the T-Deck Settings menu → Display Timeout. Cycles through:

Special Cases

• SOS Mode: Screen never sleeps during an active SOS — the emergency display stays on at full brightness regardless of the timeout setting.
• First press wakes only: When the screen is asleep, the first key press or trackball movement wakes the display but does not trigger any menu action. This prevents accidental sends or button presses.
• Persisted: Saved to EEPROM address 432. Survives reboot.
• Validation: Values 0 (off) or 10–255 seconds accepted. Invalid values default to 60s.

Power Impact

With a 60-second timeout and typical usage patterns, display sleep can reduce average power consumption by 30–50%, significantly extending battery life.

29. Live Gateway Coverage Map

The hub server hosts a live web map showing registered gateways, their online/offline status, and estimated coverage areas. It is an optional planning and monitoring tool — the radio mesh itself works without it.

Accessing the Map

The hub serves both WebSocket and HTTP on the same port — no extra port needed:

# If hub runs on port 9000:
Map:       http://your-hub-address:9000/
API:       http://your-hub-address:9000/api/gateways
WebSocket: ws://your-hub-address:9000/       (gateways connect here)

# Tailscale Funnel exposes ONE port — everything works through it:
https://your-machine.tail1234.ts.net/

Map Features

Coverage Ring Calculations

Approximate coverage radius based on antenna type and height (tuned for SF9 / 868 MHz):

These are rough estimates. Real-world coverage depends on terrain, buildings, and antenna quality.

Gateway Configuration for the Map

Each ESP gateway must have location configured via BLE before it appears on the map:

GWLOC,51.5074,-3.1791     Latitude and longitude
GWANTENNA,2                0=indoor  1=external  2=rooftop
GWHEIGHT,10                Antenna height in metres
SAVE

Gateways with lat=0, lon=0 (not configured) are hidden from the map.

HTTP API

API Response Format

[{
  "id":            "AA:BB:CC:DD:EE:FF",
  "name":          "Base Camp",
  "lat":           51.5074,
  "lon":           -3.1791,
  "antenna_type":  2,
  "antenna_height":10.0,
  "online":        true,
  "uptime":        3600,
  "packets":       150
}]

Gateway Registry Persistence

The hub stores gateway locations in gateway/gateways.json. This means:

• Offline gateways still appear on the map (with a red marker) — useful for seeing full network topology
• Hub restart preserves locations — no need to reconfigure gateways
• Registry updates on each auth — gateway location changes take effect immediately

Hub Auth Message (Updated)

The gateway firmware now includes location data in the WebSocket auth message:

{
  "type":    "auth",
  "key":     "MySecretKey",
  "id":      "AA:BB:CC:DD:EE:FF",  // WiFi MAC address
  "name":    "Base Camp",
  "lat":     51.5074,
  "lon":     -3.1791,
  "antenna": 2,                  // 0=indoor, 1=external, 2=rooftop
  "height":  10.0                 // metres
}

30. Telegram Alerts (Android App)

The Android app can forward group mesh messages and SOS emergencies to a Telegram chat via a bot. This lets family members, a base-camp coordinator, or anyone with Telegram receive real-time alerts — even if they are miles away with no LoRa hardware.

How it works

• Every group in the mesh uses a shared AES key (for example MyHikingGroup!).
• When the Android app receives a packet it decrypts it locally using that key.
• If decryption succeeds and the message is a group broadcast or SOS, it is forwarded to your Telegram bot via a standard HTTPS POST.
• Direct node-to-node messages are never forwarded — they stay private.
• Deduplication: if several group members have mobile signal and all receive the same packet, only one phone actually sends to Telegram (the first one wins; the others detect the message is already there and skip).

What gets forwarded

Step-by-step setup

Step 1 — Create a Telegram bot

1. Open Telegram and search for @BotFather.
2. Send /newbot and follow the prompts to name your bot.
3. BotFather will reply with a bot token that looks like:
   123456789:ABCdefGHIjklMNOpqrSTUvwxYZ
   Copy this — you will need it in the app.

Step 2 — Get your Chat ID

1. Add your bot to a Telegram group, or start a private chat with it and send any message.
2. In a browser, open:
   https://api.telegram.org/bot<YOUR_TOKEN>/getUpdates
3. Look for "chat":{"id": in the JSON response. That number is your Chat ID.
4. For a group it will be a negative number, e.g. -1001234567890.

Step 3 — Configure in the app

1. Open the Android app → Settings tab.
2. Toggle Telegram Alerts on.
3. Enter your bot token and chat ID.
4. Tap Save then Test — a confirmation message should appear in your Telegram chat immediately.

T-Deck and other standalone devices

Devices running the firmware directly (T-Deck, LoRa32, Heltec) are completely unaffected by the Telegram feature. They send and receive mesh messages as normal. If a group member with an Android phone happens to receive the same message and has mobile signal, the forwarding happens transparently — the T-Deck user never knows and nothing changes on their device.

31. Colour Theme Reference

Consistent colour palette used across the TFT display, OLED, and Android app.

TFT Display Colours (RGB565)

Android App Colours

Signal Strength Colour Coding

32. IO Expansion Board (UART2 Daisy-Chain)

You can daisy-chain a second ESP32 to any repeater node as an IO expansion board, adding up to 16 additional sensor inputs and relay outputs. The expansion board connects via UART (serial) and has no LoRa radio — it is a simple IO slave controlled by the main mesh node.

Wiring

Connect 3 wires between the main node and the expansion ESP32:

UART2 Pins per Board

Enabling

# Enable IO expansion (opens UART2 at 115200 baud)
EXPAND ON

# Disable IO expansion
EXPAND OFF

Virtual Pins

Once enabled, the expansion board's sensors appear as virtual pins 100–115 on the main node. You can use these in setpoint rules, auto-poll SDATA, and the Logic Builder just like regular GPIO pins.

# Setpoint using expansion board sensor on virtual pin 100
SETPOINT,100,GT,2000,0010,4,1

# The main node polls the expansion board every 2 seconds
# and caches the values. readSensorPin(100) returns the cached value.

Serial Protocol

The main node and expansion board communicate over a simple ASCII line protocol at 115200 baud:

Expansion Board Firmware

The expansion board runs a separate, minimal firmware (io-expansion build target). It has no LoRa, no BLE, no mesh — just serial IO. Flash it using the web flasher or PlatformIO:

pio run -e io-expansion -t upload

Edit the pin arrays at the top of src/io_expansion.cpp to match your wiring:

const int SENSOR_PINS[] = {34, 35, 36, 39, 32, 33};  // Analog/digital inputs
const int RELAY_PINS[]  = {2, 4, 5, 12, 13, 14};      // Digital outputs

33. Known Issues & Board-Specific Caveats

Board-Specific Issues

Protocol Notes

• Hard protocol break: The AES-128-GCM encryption is incompatible with older firmware using AES-128-CTR. All nodes in a mesh must run the same firmware version.
• Message ID is 6 characters: Increased from 4 characters in v3.x. Dedup ring buffer is 128 entries.
• Setpoints and timers are ephemeral: Stored in RAM only. Lost on reboot. Auto-poll is the only sensor feature that persists (saved to EEPROM).
• ADC resolution: 12-bit (0-4095). Sensor values are raw ADC counts, not calibrated units. Calibration is done on the monitoring end (PC/phone/hub).
• Max 4 timers and 4 setpoints per node. Setting a timer on a pin that already has one overwrites the existing timer.
• Auto-poll minimum interval: 30 seconds. Shorter intervals risk channel congestion on busy meshes.

Gateway / Hub Notes

• Tailscale Funnel hostname: May time out from some networks. Use the Tailscale IP address directly if the hostname fails (check tailscale status).
• Hub port conflict: If running multiple hub services (e.g. tiggyopenmesh-hub and lora-mesh-hub), only one can bind the port. Disable the conflicting service: sudo systemctl disable <service-name>.
• Sensor data in hub: SDATA packets must be decrypted to extract sensor readings. Enter the mesh AES key in the hub GUI's AES Key field.
• Hub requires pycryptodome: Install with pip3 install pycryptodome for AES-GCM decryption of sensor data.

34. GPS Support

Nodes with a GPS receiver can broadcast their position over the mesh and share location data with the Android app. GPS is supported on any board with a spare UART — the GPS TX/RX pins are configurable per-board via BLE or serial command.

Supported Boards

GPS BLE Commands

Position Broadcasting

• When GPS has a valid fix, the node periodically broadcasts a POS,<lat>,<lng> packet over the mesh.
• Broadcast interval: every 60 seconds (only when position changes by >10 metres).
• Position data is encrypted with the mesh AES key like all other packets.
• The gateway GUI and hub receive POS packets and can display node locations on the live map.

Android App — Map View

• The Map tab in the Android app shows all nodes with known GPS positions on an OpenStreetMap view.
• Share My Position button sends the phone's GPS coordinates to the mesh as a POS broadcast.
• Tap a node marker to see its ID, last position, and distance from your phone.
• Positions auto-refresh every 5 seconds — useful for site surveys and repeater placement walks.

EEPROM Storage

GPS pins are saved at EEPROM address 441 (2 bytes: TX pin, RX pin). Value 0xFF means disabled. On boards without a default GPS, the pins remain disabled until explicitly configured via BLE. Pin values are validated against the isPinSafe() forbidden list to prevent conflicts with UART0, I2C, SPI, or USB pins.

35. Device Management (Reboot & Factory Reset)

Nodes can be rebooted or factory-reset remotely via BLE or LoRa. This is useful when a node is deployed in a hard-to-reach location or when EEPROM corruption prevents serial access.

BLE Commands

LoRa Mesh Commands

Android App

The Settings screen has a Device Management card with two buttons:

• Reboot (orange) — sends REBOOT over BLE. The node restarts with all settings intact.
• Factory Reset (red) — sends EEPROM,RESET over BLE. Wipes all stored settings and restarts with defaults. Use this if a node is stuck due to EEPROM corruption (e.g. bad GPIO pin config killing USB/UART).

Security

• BLE: Requires being within BLE range (~30m) and paired. Worst case: an attacker can only reboot your node or reset it to defaults — no data leakage, no firmware modification.
• LoRa: All mesh commands are AES-encrypted. Only devices with your mesh key can send a reboot command.

36. Signal Strength & Route Visibility

All platforms show signal strength and routing information for discovered nodes, making it easy to optimise repeater placement and diagnose connectivity issues.

Gateway GUI

• Signal bars: Each node card shows 4 coloured bars based on RSSI — green (>-60 dBm), orange (-60 to -90 dBm), red (<-90 dBm), grey (offline).
• RSSI value: The exact dBm reading is displayed next to the bars.
• Route info: Shows "Direct" for single-hop nodes or "2hop via 0003" for multi-hop routes, so you can see the actual mesh path.
• Topology canvas: Edges between nodes are coloured and sized by RSSI. Weak links are highlighted in red with thin lines.
• Connection settings: Serial port, hub URL, gateway name, and hub key are saved between sessions — no need to re-enter each time.

Android App

• Nodes screen: Each node card shows hop count and route path ("2 hops via 0003" or "Direct").
• Auto-refresh: Node list updates every 5 seconds — useful when walking a site to find optimal repeater positions.

T-Deck Plus

• Known Nodes screen: Shows "via <nextHop>" for multi-hop nodes so you can see the routing chain.

38. iBeacon Scanner — BLE Proximity Triggers

Repeater nodes can scan for iBeacon BLE tags alongside the normal GATT server (dual-role BLE). When a configured beacon enters range (based on RSSI threshold), the node can trigger a relay or broadcast a mesh message — all without any phone or gateway connection.

How It Works

1. The node runs a non-blocking BLE scan every 5 seconds (1-second scan duration).
2. Each detected device is checked against up to 8 beacon rules.
3. Matching is by iBeacon UUID (contains dashes) or MAC address (contains colons).
4. If the beacon's RSSI is above the configured threshold, the rule's action fires.
5. A cooldown prevents re-triggering too quickly (default 10 seconds).
6. For relay actions, an optional auto-revert turns the relay off when the beacon has not been seen for a configurable duration.

Beacon Commands (BLE / Serial)

Examples

# Scan for nearby beacons
BEACON,SCAN
# Response: BEACONSCAN,3,aa:bb:cc:dd:ee:ff:-62dBm,11:22:33:44:55:66:-88dBm:MyTag,...

# Gate opener: turn on relay pin 4 when tag is within ~3m (-65 dBm)
# Auto-revert relay after tag gone for 30 seconds
BEACON,ADD,aa:bb:cc:dd:ee:ff,Gate,-65,RELAY,4,1,10000,REVERT,30000

# Alert: broadcast "COW_OUT" when iBeacon UUID detected
BEACON,ADD,FDA50693-A4E2-4FB1-AFCF-C6EB0764...,Daisy,-80,MSG,COW_OUT,60000

# List configured rules
BEACON,LIST
# Response: BEACONS,0:Gate:aa:bb:cc:dd:ee:ff:-65dBm:RELAY4:REVERT30000ms,1:Daisy:FDA50693...:MSG

Events

When a beacon rule fires, the node sends a notification over BLE/serial:

# Relay triggered
BEACON,TRIGGERED,Gate,RELAY,4

# Message broadcast triggered
BEACON,TRIGGERED,Daisy,MSG,COW_OUT

# Relay auto-reverted (tag gone)
BEACON,REVERTED,Gate

Persistence

Beacon rules are saved to EEPROM (address 512+, 128 bytes per rule, up to 8 rules = 1024 bytes). Rules persist across reboots. The runtime state (lastSeen, triggered) is not persisted — all rules start in the untriggered state after reboot.

Logic Builder Integration

The gateway GUI Logic Builder includes a Beacon Detect input block that can trigger automation rules based on beacon proximity events received from the mesh. Beacon events (BEACON,TRIGGERED / BEACON,REVERTED) from any node in the mesh are parsed by the gateway and fed into the block evaluation engine.

39. Meshtastic Bridge

The gateway GUI includes a built-in Meshtastic bridge that connects TiggyOpenMesh and Meshtastic networks via two USB serial ports. Messages, position reports, and SOS alerts are translated bidirectionally between the two mesh protocols.

Setup (GUI)

1. Connect your TiggyOpenMesh repeater to a USB port (the normal gateway serial connection).
2. Connect a Meshtastic device to a second USB port.
3. In the gateway GUI, find the Meshtastic row below the Telegram row.
4. Click Detect to list available serial ports, select the Meshtastic device port.
5. Click Start Bridge.

What Gets Bridged

Standalone CLI Mode

The bridge can also run standalone without the GUI:

python meshtastic_bridge.py --tom COM18 --mesh COM4 --key DebdaleLodge2401

Deduplication

A 256-entry hash ring with 30-second TTL prevents packets from bouncing between the two networks. The origin field and [TOM ] / [Mesh ] prefixes provide additional loop detection.

Node ID Mapping

Meshtastic 32-bit node IDs are mapped to TOM 16-bit hex IDs using a persistent mapping file (bridge_nodes.json). Meshtastic nodes appear as Fxxx IDs on the TOM mesh.

40. Telegram Bot (Gateway GUI)

The gateway GUI includes a built-in Telegram bot that exposes your automation rules as chat commands. Unlike the Android app's Telegram forwarding (which forwards broadcast messages), this bot lets remote users query sensor values and trigger relay actions from anywhere via Telegram.

Setup

1. Create a bot via @BotFather on Telegram. Send /newbot, follow prompts, and copy the bot token.
2. Get your Chat ID by messaging the bot and checking https://api.telegram.org/bot<TOKEN>/getUpdates.
3. In the gateway GUI, enter the Bot Token and Chat ID in the Telegram row.
4. Click Start Bot.

Rule-as-Command

Any automation rule whose name starts with # becomes a Telegram command. The bot matches the command to the rule and executes it:

Built-In Commands

Security

The bot only responds to messages from the configured Chat ID. Messages from other chats or users are silently ignored. The bot token should be kept private.

Alert Sending

The automation engine can also push alerts to Telegram when rules trigger. The send_alert_threadsafe() method lets any rule fire a Telegram notification without blocking the GUI or radio threads.

41. Sensor Dashboard

The gateway GUI's Sensors tab provides a full sensor monitoring dashboard with real-time visualisation of all SDATA values received from the mesh.

Dashboard Widgets

Controls

Data Flow

The dashboard shares the same sensor_data dictionary used by the Logic Builder engine. Both update in real time from the same data source.

42. Hardware Timer Watchdog

All three firmware targets (repeater, T-Deck, WiFi gateway) include a hardware timer watchdog that automatically reboots the device if the main loop hangs. This is completely independent of the RTOS task watchdog and catches low-level lockups that RTOS watchdogs miss (e.g., radio driver deadlocks, SPI bus hangs).

How It Works

Why Not RTOS WDT?

The RTOS task watchdog (TWDT) monitors whether tasks yield to the scheduler. But if the main loop is stuck inside a blocking radio call or SPI transaction, the RTOS scheduler still runs (it just can't preempt the stuck call on the same core). The hardware timer is independent of all software — if loop() does not pet it within 30 seconds, the ESP32 reboots unconditionally.

Implications

• The main loop must complete a full iteration (receive check, heartbeat, forward, GPIO, display) within 30 seconds. Under normal operation this takes ~50ms.
• Blocking operations (long delay(), synchronous WiFi, etc.) must be avoided in the main loop.
• If a device reboots unexpectedly, check the serial log for the boot reason — rst:0x3 (SW_RESET) or timer-related resets indicate a watchdog trigger.

43. Heltec WiFi LoRa 32 V4 — USB & FEM Notes

The Heltec V4 uses the ESP32-S3's native USB (HWCDC) instead of an external UART chip like the V3's CP2102. This has important implications:

Key Differences from V3

Forbidden Pins

The following pins are hardcoded into the isPinSafe() forbidden list and cannot be configured as sensor or relay pins:

Troubleshooting

• No COM port after flashing: Hold BOOT → press RESET → release BOOT to enter download mode. Erase flash with esptool.py erase_flash, then reflash.
• COM port appears but no data: The HWCDC interface can take up to 60 seconds to fully enumerate on first use. Wait, or disconnect and reconnect the serial monitor.
• Port shows in Device Manager but won't open: Kill any python.exe processes holding the port, or reboot the PC. Windows Fast Startup can persist stale USB state — use shutdown /s /t 0 for a full shutdown.

44. Web Gauge — Live Sensor Sharing

Share any sensor reading as a live web page. Anyone with the URL sees an auto-refreshing gauge on their phone — no app, no login, no limit on viewers.

URL Format

https://<hub-address>/gauge/<node-id>/<pin>?label=<name>&unit=<unit>&min=<min>&max=<max>

Parameters

Examples

/gauge/5041/15?label=Barn+Temperature&unit=°C&min=0&max=50
/gauge/5041/19?label=Wind+Speed&unit=km/h&min=0&max=100
/gauge/263A/3?label=Water+Level&unit=%25&min=0&max=100

How It Works

1. Gateway GUI decodes sensor data (SDATA) from nodes via LoRa.
2. GUI forwards decoded values to the hub via WebSocket: {"type": "sensor", "node": "5041", "pin": "15", "value": 423}
3. Hub stores latest value per node/pin in memory.
4. /gauge/<node>/<pin> serves a live HTML gauge page with auto-refresh every 5 seconds.
5. /api/sensor/<node>/<pin> returns JSON for programmatic access.

API Endpoint

GET /api/sensor/<node>/<pin>
Response: {"node": "5041", "pin": "15", "value": 423, "ts": 1711234567}

Requirements

• Hub server must be running (gateway_hub.py).
• Gateway GUI must be connected and receiving sensor data.
• Hub must be restarted after updating to pick up the /gauge endpoint.

Sharing

• Text or email the URL to anyone.
• Generate a QR code and stick it on a wall.
• Embed in an <iframe> on your website.
• No limit on concurrent viewers — it’s just a web page.

45. Licensing & Tiers

TiggyOpenMesh uses a free core + paid tiers model. The firmware, CLI gateway, Android app, and hub map are free and open-source. Premium GUI features are licensed per-seat with an offline activation key.

Activation

1. Purchase your licence key at tiggyengineering.com.
2. Launch gateway_gui.py. On first run a licence dialog appears.
3. Paste your key and click Activate.
4. The key is validated offline — no internet connection is required after purchase.