calcslive-mqtt-tools

MQTT CLI tools for CalcsLive Physical Quantity (PQ) integrations.

Publish and subscribe to PQ messages ({"value": ..., "unit": ...}) on any MQTT broker — with interactive prompts, LAN and Cloudflare Tunnel (WSS) support. Useful for testing CalcsLive calculation pages that interact with edge devices (Raspberry Pi, ESP32, etc.) via MQTT.

Context

CalcsLive calculation articles can embed an MQTT node that exchanges PQ data with physical devices. These tools let you:

• Publish test sensor data to a broker without physical hardware
• Subscribe and observe what topics and payloads a device (or the CalcsLive page) is sending

The --ws / WebSocket mode mirrors exactly what the CalcsLive browser component does when connecting through a Cloudflare Tunnel.

Requirements

• Node.js >= 18
• An MQTT broker accessible on the network
• For --ws: Mosquitto with a WebSocket listener (port 9001) and a Cloudflare Tunnel routing to it

Install

npm install -g calcslive-mqtt-tools

Or clone and run locally:

npm install
node mqtt-pq.js          # combined entry point

calcslive-mqtt — Combined entry point

The primary command. Routes to the publisher or subscriber, or shows an interactive menu when called bare.

calcslive-mqtt            # interactive menu: Publish / Subscribe / Help / Quit
calcslive-mqtt pub [...]  # run publisher with optional flags
calcslive-mqtt sub [...]  # run subscriber with optional flags
calcslive-mqtt help       # show this summary

The individual mqtt-pub and mqtt-sub commands remain available as direct aliases.

mqtt-pub — Publisher

Publishes PQ messages to a broker. Supports manual entry, auto-repeat, replay of a fixed dataset, and synthetic signal generation.

Usage

calcslive-mqtt pub         # interactive mode menu
mqtt-pub                   # same, direct alias
mqtt-pub --help            # flag reference

Modes

| Mode | Description | |----------|-------------| | Manual | Prompt for topic / value / unit before each publish. Enter . to quit. | | Auto | Set topic / value / unit once, then publish the same payload repeatedly at the configured interval. Simulates a fixed-reading edge device. | | Replay | Loop through a fixed HVAC dataset at the configured interval. | | Generate | Publish synthetic values using sine, random, or ramp profile. |

CLI flags

| Flag | Default | Description | |---------------|------------|-------------| | --mode | (menu) | Skip menu: manual, auto, replay, generate | | --broker | localhost | MQTT broker host | | --port | 1883 | MQTT broker port | | --topic | test/pq | Topic for Auto, Generate, and Replay fallback | | --interval | 3000 | Milliseconds between publishes | | --profile | sine | Generate profile: sine, random, ramp | | --min | 0.5 | Generate minimum value | | --max | 5.0 | Generate maximum value | | --value | (prompt) | Auto mode value — skips prompt when set | | --unit | mm | Unit string | | --loops | 0 | Replay loop count (0 = infinite) | | --user | | MQTT username | | --password | | MQTT password |

Examples

# Manual publish to local broker
calcslive-mqtt pub --mode manual

# Auto-repeat a fixed value every second
calcslive-mqtt pub --mode auto --topic test/pq --value 20 --unit mm --interval 1000

# Replay dataset twice then stop
calcslive-mqtt pub --mode replay --loops 2

# Generate sine wave on a custom topic
calcslive-mqtt pub --mode generate --profile sine --topic test/pq --interval 500

# Publish to Pi on LAN with auth
calcslive-mqtt pub --broker 192.168.86.42 --mode manual --user admin --password secret

mqtt-sub — Subscriber

Subscribes to PQ topics on a broker. Shows a Connect / Help / Back entry menu, then prompts for connection settings; topic filter can be changed interactively while running.

Usage

calcslive-mqtt sub         # entry menu then subscribe
mqtt-sub                   # same, direct alias
mqtt-sub --help            # flag reference

Startup prompts

On launch the tool shows an entry menu, then prompts step by step — CLI flags pre-fill the defaults:

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  MQTT PQ Subscriber
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
? Choose: › Connect — set up broker and subscribe
? Connect via WebSocket/TLS (wss://) — for Cloudflare Tunnel? (y/N)
? Broker host: (localhost)
? Broker port: (1883)
? Topic filter (# and + wildcards supported): (test/#)

Port is skipped when WSS is selected. When WSS is selected and no --broker flag was passed, hostname defaults to mqtt.calcslive.com.

CLI flags

| Flag | Default | Description | |-------------|------------|-------------| | --broker | localhost | MQTT broker hostname or IP (pre-fills the prompt) | | --port | 1883 | Broker port — TCP only, ignored with --ws | | --topic | test/# | Initial topic filter (pre-fills the prompt) | | --ws | (off) | Pre-selects WebSocket/TLS mode (wss://) | | --user | | MQTT username | | --password| | MQTT password |

Interactive resubscribe

While running, type a new topic filter and press Enter to switch without restarting:

test/pq                                  {"value":20,"unit":"mm"}

> sensors/#
Unsubscribed test/#
Subscribed to sensors/#

Press Ctrl+C to disconnect cleanly.

Examples

# Subscribe to all test topics on local broker
calcslive-mqtt sub

# Subscribe on a Pi over LAN
calcslive-mqtt sub --broker 192.168.86.42 --topic "test/#"

# Connect via Cloudflare Tunnel — same path as the CalcsLive web component
calcslive-mqtt sub --ws --broker mqtt.calcslive.com --topic "test/#"

Topic filter syntax

| Pattern | Matches | |---------|---------| | test/# | All topics under test/ at any depth | | sensors/+/temp | Single-level wildcard, e.g. sensors/hvac/temp | | test/pq | Exact topic only |

Payload format

{"value": 20, "unit": "mm"}

Values are rounded to 5 decimal places on publish.

Changelog

0.2.0

• calcslive-mqtt combined entry point — routes to pub/sub with an interactive menu; help subcommand
• Auto mode in publisher — set topic/value/unit once, repeat at configurable interval; simulates a fixed-reading edge device
• --help flag on both tools and on the combined entry point
• --user / --password auth flags on both publisher and subscriber
• Default topic changed to test/pq (pub) / test/# (sub)
• Default unit changed to mm

0.1.0

• Initial release: mqtt-pub and mqtt-sub CLI tools
• Manual, Replay, and Generate publish modes
• TCP and WSS (Cloudflare Tunnel) transport