# calcslive-mqtt-tools

> MQTT CLI tools for CalcsLive Physical Quantity (PQ) integrations — pub/sub with interactive prompts, LAN and Cloudflare Tunnel (WSS) support

Latest version **0.1.0** (published 2026-09-23) · MIT license · 0 weekly downloads

## Install

```sh
npm install calcslive-mqtt-tools
pnpm add calcslive-mqtt-tools
yarn add calcslive-mqtt-tools
bun add calcslive-mqtt-tools
```

Provides the commands `mqtt-pub`, `mqtt-sub`.

## Health

**Score 60/100 (C)** — status: active.

Positive: esm support; no vulnerabilities; recently updated; high maintenance score.

Warnings: low downloads; no types; pre 1.0.

## Facts

| | |
|---|---|
| Version | 0.1.0 |
| Published | 2026-09-23 |
| First published | 2026-09-23 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | ESM |
| Dependencies | 2 |
| Unpacked size | 19.4 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 0 |
| Maintainers | e3d |

## Links

- npm: https://www.npmjs.com/package/calcslive-mqtt-tools
- Repository: https://github.com/CalcsLive/calcslive-mqtt-tools
- Homepage: https://github.com/CalcsLive/calcslive-mqtt-tools#readme
- Issues: https://github.com/CalcsLive/calcslive-mqtt-tools/issues
- npm.io page: https://npm.io/package/calcslive-mqtt-tools

## Dependencies (2)

- [mqtt](https://npm.io/package/mqtt.md) ^5.0.0
- [inquirer](https://npm.io/package/inquirer.md) ^9.0.0

## Recent versions

- 0.1.0 (latest) — 2026-09-23

## README

# calcslive-mqtt-tools

MQTT CLI tools for [CalcsLive](https://calcslive.com) 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

```bash
npm install
npm link        # registers mqtt-pub and mqtt-sub as global commands
```

Or install globally from npm (once published):

```bash
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

```bash
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

```bash
# 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

```bash
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

```bash
# 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

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

Values are rounded to 5 decimal places on publish.

---
_Source: https://npm.io/package/calcslive-mqtt-tools · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._