calcslive-mqtt-tools

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
npm link        # registers mqtt-pub and mqtt-sub as global commands

Or install globally from npm (once published):

npm install -g calcslive-mqtt-tools

---

mqtt-pub — Publisher

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

Usage

mqtt-pub                           # interactive menu
node mqtt-pq-publisher.js          # local invocation
npm run pub                        # same

Modes

Mode	Description
Manual	Prompt for topic / value / unit before each publish. Enter . to quit.
Replay	Loop through a fixed HVAC dataset at the configured interval.
Generate	Publish synthetic values using sine, random, or ramp profile.

CLI flags (all optional)

Flag	Default	Description
--mode	(menu)	Skip menu: manual, replay, generate
--broker	localhost	MQTT broker host
--port	1883	MQTT broker port
--topic	sensors/hvac/pressure	Topic for 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
--unit	psi	Unit for Generate mode
--loops	0	Replay loop count (0 = infinite)

Examples

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

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

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

# Publish to Pi on LAN
mqtt-pub --broker 192.168.86.42 --mode manual

---

mqtt-sub — Subscriber

Subscribes to PQ topics on a broker. Prompts for connection settings at startup; topic filter can be changed interactively while running.

Usage

mqtt-sub                           # interactive setup then subscribe
node mqtt-pq-subscriber.js         # local invocation
npm run sub                        # same

Startup prompts

On launch, the tool prompts step by step — CLI flags pre-fill the defaults:

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

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 (all optional)

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

Interactive resubscribe

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

actuators/hvac/fan               {"value":1,"unit":"bool"}
actuators/light/main             {"value":255,"unit":"pwm"}

> sensors/#
Unsubscribed actuators/#
Subscribed to sensors/#

Press Ctrl+C to disconnect cleanly.

Examples

# Subscribe to all actuator topics on local broker
mqtt-sub

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

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

Topic filter syntax

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

---

Payload format

{"value": 22.4, "unit": "deg"}

Values are rounded to 5 decimal places on publish.