BACnet Stack on Ubuntu: Metadata, Read & Write API Details

This page is a technical companion to the case study: BACnet Stack on Ubuntu to provide a Self-Configuring BACnet Server . It explains how a REST API can be mapped into a BACnet/IP device using the CAS BACnet Stack.

Tool Spotlight: CAS BACnet Explorer

When commissioning or troubleshooting a BACnet server, a reliable BACnet client tool makes validation fast. CAS BACnet Explorer is commonly used to:

• Discover BACnet devices and browse objects/properties
• Read key properties like Present Value and Reliability
• Perform controlled tests using WriteProperty (setpoints, relays, overrides)

If you have questions about commissioning or mapping strategy, please CONTACT US.

Endpoint 1: Metadata (GET /metadata)

The metadata endpoint is used to initially set up the BACnet interface. Device properties, object definitions, and object properties are described in JSON. The server uses this data to:

• Create/register the BACnet device and its objects
• Build an internal memory database for properties and values
• Optionally re-poll metadata to discover newly added sensors/devices

Minimal Example

{
  "result": "OK",
  "value": {
    "bacnetNetwork": 0,
    "udpPort": 47808,
    "device": {
      "instance": 1,
      "name": "DeviceName",
      "location": "",
      "description": "",
      "objectList": [
        { "instance": 2, "objectType": "analogInput", "name": "E00C - Temperature", "units": "degreesCelsius" },
        { "instance": 3, "objectType": "analogInput", "name": "E00C - Humidity", "units": "percentRelativeHumidity" }
      ]
    },
    "metadataPollInterval": 900000,
    "sensorPollInterval": 300000
  }
}

Field Reference

Endpoint 3: Write (BACnet WriteProperty → POST /write)

The write functionality allows a BACnet client (BMS, workstation, or commissioning tool) to send commands that are forwarded to the REST API. In typical mappings:

• Analog Output objects map to setpoints (numeric commands)
• Binary Output objects map to relays or enable/disable commands (boolean commands)

When the BACnet server receives a WriteProperty request, it attempts the REST write. If the REST call succeeds, the server updates its internal memory database and reflects the new Present Value. If it fails, the server converts the failure into an appropriate BACnet error response.

Example Write Request/Response

// Request (example shape)
{
  "instance": 8,
  "value": 22.0
}

// Response (example shape)
{
  "result": "OK"
}

If the write fails, return a clear error message in JSON (e.g., permission denied, invalid value, device offline). The BACnet layer should translate that into a BACnet error so clients can display a meaningful failure.

FAQ (AI Searchability)

What does “self-configuring” mean in this BACnet server?
The server learns the BACnet device model from /metadata and automatically creates objects and properties, rather than relying on a fixed static database.

How are BACnet objects created?
Objects are created using the device.objectList[] definitions in metadata. Each entry specifies object type (AI/AO/BI/BO), instance number, name, and (when applicable) units.

How does the server handle unreliable sensors?
The read endpoint provides a reliability indicator per object. The server maps that value to BACnet’s Reliability property so BACnet clients can clearly identify bad or missing data.

What happens if the REST platform returns only changed values?
The read request can include a last-seen timestamp. The REST platform can then return only deltas, and the server updates only those object instances.

How are BACnet WriteProperty commands mapped to REST writes?
Writes to mapped AO/BO objects are forwarded to /write. A successful REST response updates the server’s internal value. Failures are translated into BACnet errors for clear diagnostics.