Niagara 4 / Open source module
BASidekick Stream
Connect external tools to live Niagara station data through one authenticated WebSocket stream, with station permissions governing access and writes.
- Status
- Active
- Year
- 2026
- Role
- Design + development
- Built with
- Java · Niagara 4 · WebSocket · MessagePack · TypeScript
The problem
Niagara contains the operational truth for many buildings, but useful external tools often need a practical way to browse that structure and stay current as values change.
BASidekick Stream creates that bridge as a station-hosted runtime module. Niagara remains in control of identity and permissions while clients get one consistent protocol for discovery, point values, subscriptions, writes, alarms, schedules, histories, tags, relations, and model changes.
What it does
Discover the station
Browse station structure, describe objects, and search bounded branches for devices, equipment, points, schedules, histories, and alarms.
Keep values live
Read point snapshots and subscribe to changing values, with lease renewal and connection-scoped cleanup built into the stream.
Control safely
Describe writable capabilities before presenting controls, then route set, override, auto, and emergency actions through Niagara permissions.
Work with the model
Read direct and implied tags, edit direct tags and relations, browse hierarchy roots, and receive branch-scoped model-change hints when supported by the deployed API.
Reach operational records
Filter and acknowledge alarms, read and edit weekly schedules, and load history records or time-bucketed rollups for charts, with every change recorded in the station's audit history.
Support real clients
Use the protocol directly, build on the TypeScript SDK, work from the terminal with the bask CLI and its live dashboard, test through the companion app and Python tools, or build panels with the read-only Grafana data source.
Updates
bask releases and API 1.7
The bask CLI now installs with one command, gained a point finder and a connection doctor, and the protocol moved to API 1.7.
bask now ships as a single executable for Windows, macOS, and Linux, built and checksummed by a release workflow on GitHub. It installs with one command and needs no Node or admin rights, so it can go on a service laptop in a minute.
Version 0.2 adds a point finder that searches the whole station from inside the dashboard, and bask doctor, which walks through each step of a connection, from reaching the station to its login page, session, service, and WebSocket, and says how to fix the first one that fails.
The protocol now reports API 1.7, marking the history rollups, alarm filters, schedule editing, metrics, and audit records added since 1.6. The MCP server and its AI client plugins were removed from the repository to keep the focus on the module, the SDK, and bask.
Hardening, an SDK, and a terminal dashboard
After hierarchy support, the work shifted to making the stream trustworthy, then building the first clients on a shared protocol spec.
API 1.6 added station model editing with preview and apply, and most of the work since then has gone into trust rather than new operations. Every alarm, history, write action, and related object is now checked against the connected user's Niagara permissions, and anything the user cannot see comes back redacted instead of leaking through metadata.
Underneath, the session was split apart: one operation registry with write and model-edit gates, a machine-readable protocol spec with a contract test, a per-session event queue that asks slow clients to resync instead of backing up, and limits that return clear errors instead of dropping connections. Those changes were checked live against a BACnet simulator with about 32 VAVs, AHUs, and water plants.
With that in place, the protocol gained history rollups for charting, alarm filters with newest-first reads and filtered acknowledge, schedule event listing and audited schedule edits, OpenMetrics counters, and audit records for tag and relation changes.
The first clients built on the spec are a TypeScript SDK that handles login, reconnects, and live subscriptions, and bask, a command-line tool with a full-screen terminal dashboard for browsing a station, watching values, following alarms, and charting history. Both are read-only by default and ask before changing anything.
API 1.5 and the first product integration
The current source adds model-editing operations and a read-only Grafana data source built on the existing stream.
API 1.5 adds read_tags, write_tags, and write_relations, along with hierarchy browsing for stations that use Niagara hierarchies. Clients still begin with capabilities and adapt to the API version actually deployed on the target station rather than assuming the repository and station are identical.
The repository now also includes the first product integration: a read-only Grafana backend data source with History, Snapshot, and Live query modes. It uses the existing health endpoint and WebSocket operations, so the integration expands what can be built around BASidekick Stream without changing the station protocol for one client.
Core station scope
The protocol grew beyond point reads to cover the station surfaces an external operator tool needs most often.
The useful boundary is wider than point reads. A real external interface needs to understand the station hierarchy, know what can be commanded, keep subscriptions healthy, and reach histories, schedules, and alarms without inventing a different transport for each one.
BASidekick Stream is being shaped around that boundary: one authenticated connection, explicit capabilities, bounded requests, and cleanup that belongs to the connection that created it.