API Examples¶

The nf-sdk repository contains Python examples demonstrating how to use the Normal Framework REST and gRPC APIs. These examples complement the API Reference and Protobuf documentation with runnable code.

Source code: github.com/normalframework/nf-sdk/tree/master/examples

Setup¶

All Python examples use a shared HTTP client in helpers.py that handles OAuth2 and Basic authentication. Configure these environment variables:

Variable	Description
`NFURL`	Base URL of your Normal installation (e.g. tunnel URL or `http://localhost:8080`)
`NF_CLIENT_ID`	OAuth2 client ID from Settings > API Keys
`NF_CLIENT_SECRET`	OAuth2 client secret from Settings > API Keys

Install dependencies:

pip3 install requests

BACnet v1 API¶

Examples using the query-parameter-based BACnet API at /api/v1/bacnet/. Proto docs: normalgw.bacnet.v1.

Example	Description
`device-scan.py`	Discover BACnet devices on the network via Who-Is
`object-scan.py`	Scan objects on a specific device
`object-scan-list.py`	Batch scan multiple devices from device-address-bindings
`read-property-multiple.py`	Read multiple properties from a device
`read-property-device-address-bindings.py`	Read device address bindings
`write-property.py`	Write a value to a BACnet object property
`create-multi-state-value.py`	Create a local multi-state-value object with state text
`update-multi-state-value.py`	Update properties on a multi-state object
`delete-local-objects.py`	Delete local BACnet objects

BACnet v2 API¶

Examples using the protobuf-based BACnet v2 API at /api/v2/bacnet/confirmed-service. See also: V2 API docs and proto docs: normalgw.bacnet.v2.

Example	Description
`read-property.py`	Read a single property with proper type handling
`read-property-multiple.py`	ReadPropertyMultiple in a single request
`read-range.py`	ReadRange for trend log data
`read-property-schedule.py`	Read a BACnet schedule's weekly schedule
`write-property.py`	Write with ApplicationDataValue types
`write-property-bo.py`	Write to a binary output
`write-property-schedule.py`	Update schedule entries
`subscribe-cov.py`	Subscribe to COV notifications and listen for value changes
`get-alarms.py`	Query persisted alarms, get device event info, acknowledge alarms

Points & Historical Data¶

Examples for querying points and time-series data via /api/v1/point/. See also: Points concept and proto docs: normalgw.hpl.v1.

Example	Description
`get-points.py`	Query points using structured filters
`get-points-device-id.py`	Filter points by device ID
`get-points-device-id-fieldmask.py`	Query with field masking to reduce response size
`get-data.py`	Fetch historical time-series data with resampling
`download-csv.py`	Download multi-point historical data as CSV
`update-period.py`	Set the polling period on points

Command Service¶

Examples for the simplified read/write API at /api/v2/command/. See also: Commands concept and proto docs: normalgw.hpl.v2.

Example	Description
`read.py`	Read current values from multiple points
`write.py`	Write to multiple points with type conversion
`write-with-context.py`	Write with automatic relinquishment on timeout
`get-commands.py`	List active command contexts

Equipment¶

Proto docs: normalgw.ontology.v1.

Example	Description
`get-equipment.py`	Load equipment instances and their associated points

Application Management¶

Proto docs: normalgw.automation.v1.

Example	Description
`applications.py`	List installed applications
`read-file.py`	Read files from an application's filesystem

Platform Configuration¶

Proto docs: normalgw.platform.v1.

Example	Description
`branding.py`	Upload and set custom branding images
`configure-sparkplug.py`	Configure Sparkplug MQTT integration (AWS IoT, Azure IoT, HTTP)

Sparkplug¶

Examples for interacting with Sparkplug MQTT directly. Requires paho-mqtt and sparkplug_b packages.

Example	Description
`dcmd-write.py`	Send DCMD write commands to a Sparkplug device
`initiate-recovery.py`	Request data recovery from a specific time via NCMD

Utilities¶

Example	Description
`decode-wal/decode.py`	Parse snappy-compressed WAL data segments offline
`graph/db.py`	Load NF point and equipment data into a Kuzu graph database