Niagara 4 / Open source module
BASk 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
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.
BASk 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
Read and subscribe to alarms, inspect schedules, and load history records so external tools can build complete operational views.
Support real clients
Use the protocol directly, test through the standalone companion app and Python tools, connect optional AI workflows through the local MCP server, or build panels with the read-only Grafana data source.
Updates
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 BASk 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.
BASk Stream is being shaped around that boundary: one authenticated connection, explicit capabilities, bounded requests, and cleanup that belongs to the connection that created it.