@ternion/bitstream

@ternion/bitstream is a command-line toolkit for embedded systems and IoT development. It helps you manage firmware MQTT/Wi-Fi configuration, run local MQTT infrastructure, and simulate MCU telemetry workflows.

Table of Contents

• Who This Is For
• Requirements
• Install
• Quick Start
• Common Workflows
• Configuration
• Port Conflict Management
• Command Reference
• Troubleshooting

Who This Is For

This package is designed for:

• students and developers working on MQTT-enabled embedded firmware,
• teams using a local frontend dashboard plus MQTT broker,
• users who need repeatable CLI workflows across Windows, macOS, and Linux.

Requirements

• Node.js 20+
• Docker Desktop / Docker Engine is optional (needed only for bitstream backend ... commands)
• Embedded MQTT broker (bitstream broker ...) works without Docker

Install

Choose one run mode:

• No global install: use npx @ternion/bitstream ...
• Global install: use bitstream ... directly (no npx needed)

Use without global installation:

npx @ternion/bitstream --help

Or install globally:

npm install -g @ternion/bitstream
bitstream --help

After global install, run commands as:

bitstream broker start --daemon
bitstream backend up
bitstream simulator start

Quick Start

# Start embedded MQTT broker (daemon mode)
npx @ternion/bitstream broker start --daemon
npx @ternion/bitstream broker status

# Start HTTP API used by frontend integrations
npx @ternion/bitstream serve

# Verify command groups
npx @ternion/bitstream --help

Common Workflows

1) Firmware config updates

npx @ternion/bitstream mqtt-broker docker
npx @ternion/bitstream mqtt-broker base-topic lab/kit-1
npx @ternion/bitstream mqtt-broker client-id kit-01
npx @ternion/bitstream wifi set --ssid MyAP --password "secret"

2) Docker Mosquitto lifecycle

npx @ternion/bitstream backend up
npx @ternion/bitstream backend logs
npx @ternion/bitstream backend down

Docker compose assets are bundled with this package under docker/, so backend commands work after npm installation. Use Docker only when you prefer containerized Mosquitto; otherwise use the embedded broker commands.

3) MCU telemetry simulation

npx @ternion/bitstream simulator start
npx @ternion/bitstream simulator status
npx @ternion/bitstream simulator stop

Configuration

Firmware header paths are machine-specific. Set them with environment variables or per-command flags.

Monorepo ROOT (optional)

If your current directory is a ROOT that contains both firmware/ and frontend/:

cd /path/to/ROOT
npx @ternion/bitstream init default

This writes ./bitstream.config.json with relative paths. When you run Bitstream from that same ROOT, you can usually skip manual BITSTREAM_*_PATH exports. Use --pull-snapshot to refresh mqtt_client_config.snapshot.json from the header and sync the frontend .env without modifying mqtt_client_config.h (init from existing #defines only). Add --push-header only when you intentionally want the header patched from that snapshot. For firmware-only trees, bitstream mqtt-broker snapshot (no --push) does the same pull-only init.

Windows (PowerShell)

$env:BITSTREAM_CONFIG_PATH = "C:/path/to/mqtt_client_config.h"
$env:BITSTREAM_WIFI_CONFIG_PATH = "C:/path/to/wifi_config.h"
npx @ternion/bitstream serve

macOS / Linux (bash/zsh)

export BITSTREAM_CONFIG_PATH="/path/to/mqtt_client_config.h"
export BITSTREAM_WIFI_CONFIG_PATH="/path/to/wifi_config.h"
npx @ternion/bitstream serve

Per-command path override

npx @ternion/bitstream serve --config "/path/to/mqtt_client_config.h" --wifi-config "/path/to/wifi_config.h"

Port Conflict Management

Embedded broker and Docker Mosquitto both use 1883 and 9001 by default.

If those ports are busy:

npx @ternion/bitstream port status 1883
npx @ternion/bitstream port free 1883 9001

You can also stop known runtimes directly:

npx @ternion/bitstream broker stop
npx @ternion/bitstream backend down

Command Reference

Key command groups:

• broker - embedded MQTT broker lifecycle
• backend - Docker Mosquitto lifecycle
• simulator - telemetry simulator lifecycle (start, status, stop; mcu deprecated)
• mqtt-broker - firmware MQTT config updates
• wifi - firmware Wi-Fi config updates
• port - listener inspection and cleanup
• init - workspace setup (init default for standard monorepo ROOT)
• config - runtime config init/show/validate
• fw - firmware make wrappers

For full help:

npx @ternion/bitstream --help
npx @ternion/bitstream help broker
npx @ternion/bitstream help mqtt-broker

Troubleshooting

• command not found: bitstream
  • Use npx @ternion/bitstream ... or install globally.
• Port already in use
  • Run port status / port free commands shown above.
• Firmware header not found
  • Set BITSTREAM_CONFIG_PATH and BITSTREAM_WIFI_CONFIG_PATH, or pass --config / --wifi-config.
• Docker command errors
  • Ensure Docker Desktop/Engine is running and accessible from your shell.