BACnet

Capabilities

Capability	Support	Comment
BACnet object explorer (Discovery Widget)		Provides interactive exploration of BACnet devices and exposed objects through the discovery widget. This feature relies on automatic device and object introspection. See Discovery and BACnet Device Global Configuration.
BACnet script-level operations		Provides a script interface to read/write properties, acknowledge events, and perform device-level operations with precise control. See BACnet Script Controller.
BACnet client		OnSphere always operates as a BACnet client device, initiating discovery, read, write, subscription, and notification requests. The client-only model is described in Concept.
BACnet server		The module exposes a BACnet Device object to the network, allowing basic identification and discovery. It is not possible to add custom properties to this object. It is also not possible to expose additional BACnet objects. The module cannot be used as a full BACnet server.
Using multiples listening port		Each BACnet module instance listens on a single UDP port. To expose multiple listening ports, deploy multiple osp-bacnet modules, each configured with its own port. See Networking.
BACnet secure		This feature is currently not supported. In case of interest please contact us at info@sdn.ch
Register to a FDT		Supports registration as a foreign device to a BBMD using a Foreign Device Table (FDT). Required when devices are located on different IP subnets. See FDT registration and Networking.
BDT Table statically filled		This feature is currently not supported. In case of interest please contact us at info@sdn.ch
Register to multiples FDT		Only one active FDT (BBMD registration) is supported per module instance. Multiple BBMDs can be configured as fallback using a round-robin strategy. See FDT registration. For parallel domains, deploy multiple osp-bacnet modules.
Use module as BBMD		This feature is currently not supported. In case of interest please contact us at info@sdn.ch
Connect to BACnet device given BACnet ID		Device connection and targeting are performed exclusively using the BACnet Device Identifier. This identifier is the core addressing mechanism. See Device Identification and Targeting.
Connect to BACnet device given specific IP		This feature is currently not supported. In case of interest please contact us at info@sdn.ch
Connection state monitoring of BACnet device		Exposes the device connectivity and supervision state as a boolean OnSphere value, enabling health monitoring and automation logic. See Device Supervision and Health Monitoring.
Reading value by object subscription (COV)		Supports Change of Value (COV) subscriptions at the object level, allowing passive and event-driven acquisition. See Reading values with subscription (COV).
Reading value by property subscription (COV)		Supports Change of Value (COV) subscriptions at the property level for fine-grained monitoring. See Reading values with subscription (COV).
Reading value by single polling or multi-polling		Supports both single-property polling and optimized multi-property polling depending on device capabilities. See Reading values with polling.
Use client based COV increment instead of device COV		Allows overriding the device-defined COV increment at the client level to control update granularity and network load. See COV increment.
Acquisition rules for property monitoring		Allows defining rules to observe BACnet properties with associated actions, using flexible selection expressions and multiple strategies (COV or polling). See Properties acquisition rules.
NotificationClass (Alarms and events) handling		Supports subscription to BACnet NotificationClass objects for alarms and events, including dynamic auto-subscription and linked actions. See Notifications subscription and Properties acquisition rules.
Linked action execution		Acquisition rules and notifications can trigger linked actions automatically. See Linked action.
Write property using callback		Supports writing BACnet properties through output values and linked actions, using type adapters and priorities. See Writing values.
Write proprietary object types		Proprietary object and property types are supported using numeric identifiers and RAW adapters. See Proprietary object type / property, Proprietary / vendor property and Writing values.
Relinquish the priority		Supports priority-based write semantics and value relinquishment according to BACnet priority arrays. See Writing values.

Examples

• Read a BACnet value by subscription

• Read a BACnet value by polling

• Write a BACnet value

Concept

The connection to BACnet devices is always done as a client, in generally it’s recommended to be in the same network than the BACnet devices dues to the limitation of the protocol. Otherwise see the dedicated chapter for details how to configure BACnet as a FDT device.

The module supports the standard usage of values, input, and output configuration files as with other modules.

In addition, it supports automatic subscription of values and notification classes to linked actions. This approach allows you to declare only the points of interest on the device, while automatically registering to any relevant points. As a result, the device itself can serve as the source of information without requiring adjustments to the OnSphere configuration. This is particularly useful for storing values in analytics or for retrieving all notifications as alarms. See auto-subscriptions for more details. This mechanism is especially relevant when the device is the trusted source, and all alarms are generated and defined on the device itself.

Since BACnet uses complex types and OnSphere relies on a standardized format (see values), conversions must be performed in both directions.

• For writing values to an external device, refer to Writing values.

• For reading values from a device into OnSphere, refer to Reading Values.

Proprietary object type / property

In the BACnet protocol, proprietary object types allow vendors to extend the standard set of object types.

• Standard object type identifiers range from 0 to 127 and include officially recognized objects such as analogInput, binaryInput, or multiStateValue.

• Identifiers from 128 to 1023 are reserved for vendor-defined, proprietary objects.

Within the configuration:

• Standard objects are available with system-provided validation and strong naming.

• To use proprietary objects or specific adapters (e.g., for writing purposes), the RAW type can be used to define an object type based on its numeric identifier.

Proprietary / vendor property

In the BACnet protocol, proprietary properties serve as a mechanism for vendors to extend the standard set of properties.

Warning

The conversion of the proprietary properties is done as describe on Type conversion.

• The standard reserves property identifiers in the range 0 - 511 for officially recognized properties (such as present value, description …).

• Identifiers in the range 512 - 4194303 are explicitly reserved for vendor-defined, proprietary property.

Proprietary properties are supported, but can only be referenced via their id (512 - 4194303). This is done by setting the object field to RAW on owner.bacnet.

OnSphere device ID

Each module has a dedicated device ID. This number must be chosen carefully, as BACnet devices can use filters to respond only to specific device IDs.

Networking

From a networking perspective, the BACnet module operates slightly differently due to its protocol implementation. This protocol uses a subnet broadcast mechanism to discover the IP address corresponding to a specific device ID. However, since broadcast messages cannot be routed across subnets, all devices must reside within the same subnet. Once the device ID and IP address pair have been resolved, communication continues over UDP at the transport layer, using configured port 47808 (default).

This broadcast method does not work well with generic Docker orchestrator networks (such as overlay networks). In most cases, using the host network is required to ensure that broadcast messages are correctly forwarded to the osp-bacnet module. See Remote connectors to show how to connect.

Another method to address this limitation, special devices known as BACnet Broadcast Management Devices (BBMDs) are used. In simple terms, a BBMD forwards broadcast requests within a subnet and responds with the IP address associated with the requested device ID. For more details, refer to this website.

FDT registration

An FDT is required when the IP subnet of the osp-bacnet module differs from that of the BACnet device. The FDT acts as a table where onsphere registers using a dedicated device ID and then forwards broadcast messages as unicast UDP packets directly to the osp-bacnet module.

A key limitation of the BACnet protocol is that the FDT determines the IP of the foreign device from the source IP of the received UDP datagram. This design can cause issues in complex network architectures, such as when using orchestrators like Kubernetes, where the output IP may differ from the input IP. One way to work around this limitation is to use the host network.

Hint

The local device attempts to register with BBMDs by employing a round-robin loop. This mechanism sequentially tries to register with each BBMD provided in the configuration.

• If a BBMD accepts the registration, the registration process is considered successful, and the value state is updated to reflect this.

• If no BBMD accepts the registration, the value state will be set to false, indicating that the registration was unsuccessful.

Warning

The current osp-bacnet module supports only a single BBMD registration (commonly referred to as Foreign Device Table, or FDT). To address this limitation, it is possible to create multiple modules that are all registered onto a separate BBMD.

Network Impact

The network impact of the BACnet module can be significant due to the number of values being subscribed to. Each value requires an individual subscription. As a result, when the module starts, a large number of subscription requests are generated on the network.

In a standard scenario, four requests are required to establish a subscription. The total number of requests therefore increases quickly depending on the number of configured values. Each subscription request has a size of 53 to 86 bytes, which must be taken into account when evaluating bandwidth usage during startup.

Subscriptions must also be renewed regularly to remain active. Depending on the renewal interval defined in the configuration, the same volume of subscription requests will be generated on a recurring basis.

To optimize network load, it is recommended to configure different renewal intervals for different subscriptions. This approach spreads requests over time and helps to avoid traffic peaks.

How to minimize network load for properties subscription :

1. Use a COV increment appropriate for internal usage (for example, there is no need to capture every small temperature change).

2. Use multiple module instances to avoid generating excessive network load during a restart.

3. Adjust the COV registry interval to balance between handling device restarts and minimizing network load.

4. Introduce device-specific connection delays, based on criticality, during the first connection to avoid startup overload. See how to below

How to avoid peak

The supervision method can be configured with an initial delay before the first request. This allows device prioritization and helps avoid load peaks. For example, in large configurations, using multiple delay intervals (such as 5 groups with 30 seconds between each group) prevents a significant load spike when the module starts.

BACnet Device Global Configuration

Device Identification and Targeting

The device identifier uniquely identifies the remote BACnet device on the network.

Conceptually:

• The identifier is defined on the BACnet device itself

• It must be unique on the BACnet network

• It cannot be modified through configuration

The configuration uses this identifier to:

• Address requests to the correct device

• Associate incoming responses and notifications to the expected device

This parameter acts purely as a targeting mechanism and does not influence device behavior.

Device Introspection and Capability Discovery

When a device connection is established, the system can automatically retrieve:

• The list of supported BACnet protocol services

• The list of objects exposed by the device

This discovery phase enables the system to adapt its behavior dynamically based on device capabilities.

Key characteristics:

• Object list retrieval is required for acquisition rules and notification rules

• Supported protocol discovery enables advanced and more efficient request strategies

• Both mechanisms improve robustness and reduce unnecessary network traffic

These features may be disabled only when a device reports incorrect capabilities or causes communication errors. See device.bacnet for details.

Request Optimization and Aggregation

BACnet allows grouping multiple operations into a single request when supported by the device. This configuration controls whether such optimizations are used.

Conceptually, the system can:

• Read multiple properties in a single request

• Poll multiple values at once

• Subscribe to multiple COV properties in a single operation

When enabled, these optimizations:

• Reduce network traffic

• Improve acquisition latency

• Scale better on devices with many properties

Some devices incorrectly report support for these features. In such cases, the configuration allows forcing simpler, single-property requests to preserve stability.

Automatic Request Strategy Selection

The system can automatically choose the most efficient request strategy based on the capabilities reported by the device. The connection state between the BACnet module and a device can be read as a BOOLEAN value from the BACnet device in the OnSphere hierarchy (i.e. root.bacnet.device_123456 for example).

This includes decisions such as:

• Single-property versus multi-property reads

• Simple COV subscriptions versus grouped subscriptions

When automatic selection is disabled, the system falls back to conservative request patterns that do not rely on declared device capabilities.

This mechanism provides a balance between performance and compatibility with misconfigured or partially compliant devices.

Device Supervision and Health Monitoring

Supervision defines how the system determines whether a device is reachable and operational.

Its objectives are:

• Detect loss of connectivity

• Identify device restarts

• Detect configuration changes indirectly

Supervision operates independently from acquisition and notification rules and focuses solely on device health.

Supervision Methods

Different supervision methods are available, each with a distinct semantic meaning:

Check method

Name	Support detection of configuration change	BACnet request	Information
FORCE_CONNECTED	None		The device is always considered reachable. This mode is intended for devices that cannot be reliably checked. The delay configured via sleepBeforeFirstConnection is still applied to allow batching.
OBJECT_NAME	PropertyIdentifier.objectName		A lightweight BACnet read request is used to verify basic connectivity.
TIME_OF_DEVICE_RESTART	PropertyIdentifier.timeOfDeviceRestart		The supervision detects device restarts by observing changes in the reported restart time.

The selected method defines how connectivity and configuration changes are interpreted by the system.

Supervision Timing and Retry Model

Supervision timing controls how aggressively the system monitors the device.

Key aspects:

• Monitoring frequency defines how often connectivity checks occur

• An initial delay can stagger connection attempts when many devices start simultaneously

• Retry delays and retry limits define tolerance to transient network failures

Once retry limits are exceeded, the device is reported in an error state.

Reading Values

Warning

In this documentation, a “value” refers to a BACnet property on a given point (ObjectType + PropertyType + InstanceId) and is distinct from a Notification Class.

The osp-bacnet module supports multiple methods for reading values from a BACnet device:

• Using a COV registry (recommended)

• Using periodic requests (polling)

Reading method

1. Each BACnet property corresponds to a single OnSphere value, consistent with other modules.

2. Auto-subscriptions are used with a linked action and does not create individual values, but are useful when the data or notification class is intended for database ingestion or alarm generation without declaring all the values in the configuration.

The conversion from BACnet types to internal states is described here.

Reading values with subscription (COV)

Concept

The subscription to BACnet object change notifications (COV) is a mechanism designed to prevent network overload. In this mode, the client is passive and receives notifications of value changes from the server.

There is two types of subscription, they are both linked to only one value.ospp :

• PROPERTY_SUBSCRIPTION: Updated only when the specified property field changes.

• OBJECT_SUBSCRIPTION: Updated when any Change of Value (COV)-enabled field of the object changes. The properties that trigger COV notifications are configured on the device and cannot be controlled by the client. If the specified field does not support COV, OBJECT_SUBSCRIPTION will silently do nothing and no COV notification will be triggered.

Handle disconnection

The subscription mechanism relies on periodic re-subscription with a defined validity period. When a device reboots, its subscription table is typically cleared, requiring the client to re-subscribe.

The OnSphere BACnet connector automatically refreshes subscriptions at a configurable strategyFrequency. Each subscription sent to the device (server) is assigned a validity period equal to twice the refresh frequency, ensuring that the module detects a read error and reports it within at most strategyFrequency.

Hint

Setting this value involves a trade-off between the time it takes to reconnect after a device reboot and the resulting network load.

COV increment

In COV mode, a value is published only when it changes by a sufficient amount. For example, using a COV increment of 1° to avoid sending updates for minor fluctuations. In PROPERTY_SUBSCRIPTION mode, the covIncrement can be overridden from the value configured on the device, allowing it to be tailored to OnSphere’s requirements rather than relying solely on the device configuration.

Example

• Read a BACnet value by subscription

Reading values with polling

Concept

• MULTIPLE_POLLING : Values using this strategy on the same device are polled together in a single read request and returned in a single response, reducing network overhead.

• SINGLE_POLLING : Each value is polled individually with its own read request and response.

Example

• Read a BACnet value by polling

Writing values

Concept

Hint

The conversion from a value.ospp to a dedicated BACnet type is described here.

BACnet provides strong type definitions. Since values are limited to one of four supported types (TEXT, DECIMAL, INTEGER, BOOLEAN), a conversion must be performed for each write request. This conversion is handled by an ADAPTER.

Most types are automatically converted to standard BACnet types. See the list of available adapters for details. The adapter used for each value type is described directly in output.bacnet and is available via auto-completion.

Currently the system support most of the BACnet types but some types are not yet supported see this list for details.

Warning

This feature is deprecated as BACnet is allowing usage of null value to erase previously configured state. This feature is kept in system but will diseappear soon.

As BACnet supporting to release our write value, a output can use a control value to set the writing value to NULL see chapter below for details.

Priority

When writing a value a priority is set to the action. In most installation each system has a priority value. For example OnSphere will use the priority 8 and the security switch on the device the 0, the lower value means the higher priority.

If multiples devices are writing a value to the same device, the value of the device is equal to the request with the higher priority. When the device stop to write the value (in our example the security switch), then the value of the property will be set to next priority (the value of OnSphere).

Warning

This feature is deprecated because BACnet now allows the use of a null value to clear a previously configured state. It is still present in the system for now but will be removed in the near future.

To control the write value (release/write) a value.ospp with a BOOLEAN type must be attached with the behavior defined as :

• Set the control to true: Set the property with the value of the output

• Set the control to false: Set the property to NULL (release)

• Set the control to undefined: Set the property to NULL (release)

Note : The default priority is 16.

Example

• Write a BACnet value

Notifications subscription

Purpose of Notification Configuration

Notification configuration defines how a BACnet device sends event and alarm notifications to the platform. It focuses exclusively on subscription behavior and does not define event conditions themselves, which remain fully controlled by the BACnet device.

This configuration serves to:

• Define how the platform subscribes to BACnet Notification Classes

• Control subscription refresh and lifecycle

• Define how received notifications are handled and forwarded to actions

Notifications can be configured in two ways:

• Using notification.bacnet, which allows static configuration.

• Using subscriptionRules, which enables subscribing to NotificationClass objects present on the device without prior knowledge of them. This feature reads the device’s object configuration and generates rules based on the current setup.

Notification Scope and Triggering

Notifications are emitted by BACnet Notification Classes configured on the device.

For each notification class:

• The device decides when a notification is emitted

• The platform only receives notifications for subscribed transitions

• Each received notification is processed independently

Both events and alarms can be emitted by the same notification class.

Subscription Model

Subscriptions define how the platform registers itself to receive notifications from the device.

Supported subscription methods:

• RECIPIENT_LIST_REGISTER: the platform dynamically registers itself in the notification class recipient list

• NONE: no dynamic subscription is performed, the device is statically configured to send notifications

The subscription method applies at the device level.

Process Identifier Management

Each subscription rule defines a processIdentifier.

Rules:

• The processIdentifier must be unique per device and per notification class

• The value is chosen by the integrator

• The platform does not generate or manage process identifiers automatically

Notification Transitions

Subscriptions explicitly define which BACnet transitions should trigger notifications.

Examples:

• TO_FAULT

• TO_NORMAL

• TO_OFF_NORMAL

Important behaviors:

• Only transitions enabled on the device can generate notifications

• Subscribing to a disabled transition results in no notifications

• Transition filtering is purely declarative, the device remains authoritative

Alarm and Event Acknowledgement

Each notification received can be classified as either:

• an event

• an alarm

Acknowledgement behavior:

• Events are typically acknowledged automatically

• Alarms are typically acknowledged manually through a user action

This behavior is controlled through:

• autoAcknowledgeEvents

• autoAcknowledgeAlarms

If automatic acknowledgement is disabled, acknowledgement must be performed explicitly, usually through user-triggered actions such as scripts.

Subscription Lifecycle and Refresh

There are two ways to subscribe to a Notification Class on a BACnet device. The first is by updating the recipient list, and the second is by statically configuring the BACnet device with the OSP-BACnet information.

To receive NotificationClass notifications, a client device must be in the recipientList. However, BACnet does not provide an add method. To support auto-subscribe for NotificationClass, the following sequence is performed:

1. Request 1: GetRecipients

2. Add ourselves to the list

3. Push the updated list

As described, if the same operation is performed simultaneously by another client, conflicts may occur. Periodic checks are performed to verify that OnSphere is still present in the recipientList.

To use this feature, the device must allow requests to writeRecipientList.

Warning

Support for NotificationClass is limited, as many manufacturers do not implement it correctly or fully. Sometimes the device accepts the updated list but ignores its content. In such cases, the only solution is to manually configure the module deviceId using the manufacturer’s tools.

Subscription Parameters

Subscription parameters define when notifications are allowed to be emitted.

Parameters include:

• active days of the week

• time windows

• allowed BACnet transitions

Two levels exist:

• default subscription parameters: applied when no rule-specific parameters are defined

• specific subscription parameters: override defaults for a given subscription rule

Only one parameter set is active per rule.

Instance and Object Selection

Subscription rules define which objects are associated with a notification class using instance identifiers.

Selection syntax supports:

• single values: 4

• ranges: 3..7

• open ranges: ..

• combined expressions: 2,4..7,43,76,89..

This syntax is identical to acquisition rules and allows precise or broad selection.

Post-Notification Property Fetching

When a notification is received, the platform may automatically read additional properties from the object that triggered the notification.

This is controlled through:

• onTriggerObjectPropertiesToFetch

Fetched properties are attached to the notification context and can be consumed by linked actions.

Hint

If an error occurs while fetching the parameters, an entry named “error” will contain the exception.

Linked action

The link action feature allows you to define the action to be done when a notification arrive.

For detailed parameters and examples in code or JSON format, see NotificationTo.

Acknowledgment

A BACnet controller may trigger a Notification Class requiring an acknowledgment. There is two type of notification that can required an acknowledgement.

• Event

  In this case, it is automatically performed as recommended by the BACnet stack.

• Alarm

  An alarm must be acknowledged by a human as define by the BACnet stack.

  It is possible to perform the BACnet-type acknowledgment from the BACnet controller through the script module. The necessary acknowledgment information is available for the linked action under the key bacnetAcknowledgeData.

  Hint

  To enable human acknowledgement of the BACnet event, an alarm can be created with the content of bacnetAcknowledgeData place in the additionalData of the alarm. A script can then use this information to acknowledge the BACnet alarm with a menu on the alarm table.

For detailed parameters and examples in code or JSON format, see AcknowledgeData.

Example

• Process a BACnet event

Properties acquisition rules

Purpose of Acquisition Rules

Acquisition rules provide a structured way to observe BACnet device properties and emit events when certain conditions are met. They separate three distinct responsibilities:

• Data selection - deciding which objects and properties are relevant.

• Acquisition strategy - defining how changes are detected.

• Data consumption - specifying how events are handled.

This separation allows the acquisition logic to remain stable even as devices evolve or actions change.

Rule Evaluation and Action Execution

Each acquisition rule is evaluated independently against the BACnet properties exposed by the device.

• When a property matches a rule, the linked action is executed.

• If the same property matches several rules, each rule triggers its own action.

• If a rule contains multiple include blocks, a match on any include block triggers the action.

As a result, a single property may generate multiple independent action executions when it is selected by multiple rules.

Includes as a Selection Model

Include blocks define which properties are relevant.

Conceptually:

• Each property selected by a rule is associated with its linked action.

• Whenever the property is acquired, the action is executed.

• A single property can be selected by multiple rules, resulting in multiple independent action triggers.

This model highlights that selection is property-centric, not rule-centric: every selected property defines an independent event path from acquisition to action.

Selection Expressions

Instance identifiers, object types, and property identifiers support flexible selection expressions.

The following forms are supported:

• Single values Example: "4", "12"

• Ranges Example: "3..7" selects all values from 3 to 7 inclusive.

• Open ranges Example: ".." selects all available values.

• Combined expressions Example: "2,4..7,43,76,89.."

These expressions can be freely combined to build precise or broad selection scopes.

When using names instead of numeric identifiers, only standard BACnet-defined names are accepted. This constraint ensures consistency with the BACnet specification and enables reliable text completion.

Acquisition Strategies

Acquisition strategies define how changes are detected and how data is acquired. Four strategies exist:

• PROPERTY_SUBSCRIPTION Observes changes at the property level using BACnet COV. A notification is triggered when the property value changes beyond a defined threshold.

• OBJECT_SUBSCRIPTION Observes changes at the object level. Any relevant change within the object triggers a notification.

• SINGLE_POLLING Requests a single property per acquisition. Each acquisition retrieves one property at a time.

• MULTIPLE_POLLING Requests multiple properties in a single acquisition if the device supports it, allowing more efficient batch reading.

Multiple strategies can coexist on the same device or property. Each strategy operates independently, and actions are triggered separately for each match.

Subscription Constraints and Limitations

Subscription-based strategies rely on BACnet COV support.

Important considerations:

• If a property is not COV-subscribable, the subscription request succeeds but no values are ever reported.

• No error is returned in this case, which can make the issue difficult to detect.

In most devices, the following properties are commonly COV-subscribable:

• Present Value

• Status Flags

• Out of Service

However, this behavior is device-dependent and not guaranteed by the standard. It is therefore necessary to verify COV support on the target devices before relying on subscription-based acquisition.

Subscription Lifecycle and Refresh

Subscriptions have a finite lifetime and must be actively maintained.

• Each subscription has a validity period.

• Subscriptions must be periodically refreshed.

• If a subscription is not refreshed before its validity expires, the device removes it automatically.

To ensure stability, the refresh frequency should be at least three times shorter than the subscription validity. This allows the system to retry refresh operations in case of temporary failures without requiring a full re-subscription on the device.

Polling strategies are stateless and do not depend on subscriptions.

Action Linking and Event Semantics

Acquisition rules emit events but do not store or process data themselves. Each rule can link to one or more actions:

• Each action is invoked independently when a matching property is acquired.

• Expiration defines the temporal relevance of events.

• Failed actions do not affect other rules or actions.

This design enables flexible, parallel processing of BACnet properties with minimal configuration overhead.

Default Behavior

Rules may omit specific configuration:

• Default linked action - used when no action is explicitly defined for a rule.

• Default mode - used when no strategy or frequency is defined.

Defaults simplify configuration for common use cases while allowing detailed customization where needed.

BACnet Script Controller

Purpose

The BACnet Script Controller provides a script-level interface to interact explicitly with a remote BACnet device. It is intended for integrators who need deterministic, on-demand BACnet actions that cannot be fully covered by acquisition or notification rules.

The controller exposes a coherent set of functions to read properties, write values, and acknowledge objects, always targeting a specific remote device identified by its deviceIdentifier.

This controller is typically used inside osp-scripts to react to business logic, user actions, or complex workflows.

Conceptual Thread

The BACnet Script Controller follows a single guiding principle:

Every operation represents an explicit interaction with a remote BACnet device, executed at a precise moment and under the control of the script.

Unlike acquisition rules or notification rules:

• nothing is scheduled automatically,

• nothing is inferred implicitly,

• every action is intentional and contextual.

This makes the controller suitable for:

• manual overrides,

• contextual acknowledgements,

• conditional read/write sequences,

• post-notification processing.

Target Device Identification

All controller operations require a deviceIdentifier.

The deviceIdentifier:

• identifies the remote BACnet device on which the action is executed

• corresponds to the BACnet Device Object -> Object Identifier -> Instance number

• is provided explicitly by the caller for every operation

The controller does not perform device discovery or resolution. It assumes that the remote device exists and is reachable through the configured BACnet infrastructure.

Functional Families

The controller functions are grouped into four major families:

• Property reading

• Property writing

• Event and alarm acknowledgement

• Device-level operations

Each family follows consistent addressing and execution semantics.

Property Reading

Property read functions allow fetching BACnet properties synchronously.

All read operations require:

• the target object type identifier

• the object instance number

• the property identifier

Typed read variants are provided:

• string

• boolean

• integer

• decimal

These variants exist to:

• simplify script usage

• ensure type consistency

• avoid manual decoding of raw BACnet values

Read operations are commonly used to:

• retrieve context before taking a decision

• validate a device state

If the read fails, the error is returned directly in the execution result.

Property Writing

Property write functions allow writing values to a remote BACnet device.

Write operations follow the same addressing model as reads, with additional parameters:

• value to write,

• optional array index,

• write priority,

• adapter identifier.

Typed write variants are provided for:

• boolean values,

• text values,

• integer values,

• decimal values.

These variants reduce ambiguity and align the script intent with the BACnet value type.

The controller does not enforce priority array semantics or relinquish rules. These behaviors are fully controlled by the remote device.

Event and Alarm Acknowledgement

Acknowledging events and alarms is a central use case of the BACnet Script Controller.

BACnet devices may impose strict rules on acknowledgement:

• valid event timestamps,

• matching process identifiers,

• notification identifiers,

• specific acknowledgement states.

For this reason, multiple acknowledgement variants are exposed.

Acknowledgement Using Full Event Context

One acknowledgement variant accepts a complete acknowledgement object encoded as JSON.

This approach is designed for event-driven scenarios where:

• the acknowledgement is triggered directly by a BACnet notification,

• all event data is already available,

• the original event timestamp must be preserved.

Typical usage includes acknowledgements triggered by linkedAction executions.

In this mode:

• the event timestamp comes from the notification itself,

• the process identifier is already known,

• no additional read on the remote device is required.

This is the most precise and normative way to acknowledge an alarm when the event context is available.

Acknowledgement Using Minimal Parameters

Another acknowledgement variant accepts a reduced set of parameters such as:

• device identifier,

• object identifier and instance,

• event state,

• optional process identifier.

This variant is intended for manual or delayed acknowledgements where the original notification payload is no longer available.

In this case:

• the controller retrieves the event timestamp from the remote device,

• the timestamp is validated according to BACnet requirements before acknowledgement.

This allows acknowledging alarms while remaining compliant with the BACnet standard.

Notification Identifier Handling

Some BACnet devices require a specific notification or process identifier to acknowledge an alarm.

The controller supports this requirement by allowing the process identifier to be specified explicitly when needed.

If the device does not enforce this constraint, the identifier can be omitted.

Device-Level Operations

The controller also exposes device-level operations such as configuration refresh.

These operations allow:

• forcing a resynchronization with the remote device,

• updating cached device information.

They do not alter the device configuration itself.

Execution Semantics

All controller operations:

• execute synchronously from the script perspective,

• issue exactly one logical BACnet request,

• return an execution result containing success or error information.

If an error occurs, it is reported in the execution result. No automatic retry is performed.

Positioning

The BACnet Script Controller complements, but does not replace:

• acquisition rules

• notification subscriptions

• automatic processing mechanisms

It should be used when explicit, contextual, and deterministic control over BACnet interactions is required.

Type conversion

Writing to Devices

The conversion from a value.ospp to a BACnet value (i.e., writing) is performed by an adapter. See the adapter list.

Some values are complex (e.g., StatusFlags, which aggregates four boolean states). These complex types are handled using a JSON string INPUT. The schema for these types is documented in the adapter list.

Reading from Devices

The conversion from device properties to value.ospp is performed with the same adapters the adapter list to value TYPE.

For example, the STATUS_FLAGS property produces a value like:

owner.bacnet

{
    "readStrategy": {
        "strategy": "SINGLE_POLLING",
        "frequency": {
            "value": 5,
            "unit": "SECONDS"
        }
    },
    "linkedDevice": "root.bacnet",
    "object": {
        "type": "ANALOG_VALUE",
        "instance": 0,
        "property": "STATUS_FLAGS"
    }
}

value.ospp

{
    "name": "State control",
    "description": "",
    "type": "BOOLEAN",
    "inputType": "TEXT",
    "preTransform": {
        "transform": "asBoolean(regex(value, '\"inAlarm\"\\s*:\\s*(true|false)'))",
        "transformType": "BOOLEAN"
    }
}

Hint

More complex case can be handle by scripting.

BACnet raw tables

• BACnet objects types
• BACnet properties types
• BACnet type adapter
• References