Overview¶

Deployment Options¶

There are several ways to deploy NF:

• Docker on most Linux environments (recommended)
• Azure IoT Edge module
• Fedora IoT on bare metal
• Access an existing installation via Normal Portal or its native APIs

System Architecture¶

Normal Framework runs as one instance per site -- on a gateway appliance, a virtual machine, or a container in your own datacenter -- and sits between the building systems on the floor and the enterprise systems that consume their data. Everything it collects lands in a single normalized point database with a common equipment model, so northbound consumers see the same structure no matter which protocol the data came from.

Southbound, drivers discover devices and poll or subscribe to them over the native protocol. NF speaks BACnet, Modbus, and Fox directly, and can act as a BACnet server so existing systems see it as just another device on the network.

In between, modeling turns raw protocol objects into equipment. Workflows run continuously: they watch for new or changed points, extract equipment instances, apply tagging and normalization rules, and stage the result for review before it is written to the model layer. Ontologies such as Haystack and Brick supply the vocabulary. This is the layer that lets a consumer ask for every discharge air temperature sensor at a site instead of chasing per-device point names, and it is what makes the northbound interfaces below look the same across a fleet of buildings that were never commissioned alike.

Northbound, the same data is available several ways, and more than one can run at once: replicate it into Postgres/TimescaleDB, publish it to an MQTT broker as Sparkplug B, serve it to SCADA systems and historians over OPC-UA, exchange it with a UDMI backend, or read it directly from the REST and gRPC APIs. For custom integrations, the log-based data adapter pattern gives you exactly-once replication without having to reason about backfill.

On the instance, the Applications SDK runs managed JavaScript next to the data. Applications are installed from a git repository and are built from hooks -- serverless functions triggered by a schedule, an API call, or new data on the points they query -- and they can ship their own dashboards. Use them for control sequences, analytics, and integrations that are better run at the edge than in the cloud.

Normal Online¶

Normal Online is the cloud side of the system. It handles licensing and activation, gives you a fleet view across sites, provides browser-based remote access to on-site consoles without a VPN, and hosts the MCP server, through which Claude and other AI assistants explore, model, and control connected sites.

Instances connect out to Normal Online over HTTPS, so no inbound ports or firewall changes are required. Collection and control do not depend on that connection -- an instance keeps running when the link is down -- and your time-series data stays on site unless you configure one of the northbound integrations above.

Inside an instance¶

NF is a layered system with well-defined interfaces between components. It provides access at different levels of abstraction so application writers can use high-level APIs in most cases, but drop down into protocol-level details when needed.

NF's services communicate natively over gRPC. Envoy serves as a frontend proxy, providing URL routing, authentication (using JWTs), grpc-web support, and JSON transcoding for an equivalent REST API.

State is stored in a local Redis instance with RediSearch and RedisTimeSeries.