udmi

UDMI / Docs / Specs / BACnet Discovery

BACnet Discovery Specification

This document specifies how an on-premise UDMI discovery node (Spotter / Gateway) performs active BACnet discovery (config.discovery.families.bacnet) and formats the resulting events_discovery messages across each valid scan depth.

For static BACnet URI addressing rules (bacnet://<device_id>/<object_type>/<object_instance>[#property_identifier]), see the BACnet Specification and Family Providers Specification. For general, protocol-agnostic discovery scheduling (generation, scan_interval_sec, scan_duration_sec), see Discovery and Discovery Generation.

1. Active Scan depth Levels

A BACnet active discovery scan is controlled by config.discovery.families.bacnet.depth. There are 4 valid active scan depth levels, ordered cumulatively from coarsest network topology discovery to full object property enumeration:

Ordinal depth Value Scope BACnet Service / Property Operations Cumulative events_discovery Payload Fields
1 buckets Available BACnet networks & UDP ports Who-Is-Router-To-Network / I-Am-Router-To-Network + BACnet/IP UDP port probe (47808 / 0xBAC0, etc.) Base envelope + family: "bacnet" + network + families.ipv4.port
2 entries Discovered BACnet devices & MAC/IP bindings Who-Is / I-Am (global, network-filtered, or unicast addrs) buckets + addr (Device Instance) + per-device families (ipv4 addr/port, ethmac, mstp)
3 system Device Object (DO/0) identity properties ReadPropertyMultiple on device,<addr> (object-name, vendor-name, model-name, serial-number, etc.) entries + system (name, description, serial_no, hardware, ancillary)
4 details BACnet object references & properties ReadProperty / ReadPropertyMultiple on device,<addr> object-list + per-object (object-type, instance) properties system + refs map ("<TYPE>/<INSTANCE>" $\rightarrow$ populated RefDiscovery fields: name, description, type, units, possible_values, writable, ancillary)

Each level is strictly additive: requesting a deeper level produces all fields required by the preceding level plus the additional fields defined for that depth.

2. Scan Targeting & Scope Filters

Before executing the depth-specific operations below, the discovery node scopes the BACnet probe using config.discovery.families.bacnet:

3. Detailed depth Specifications & Cumulative JSON Payloads

3.1 buckets — Available BACnet Networks & BACnet/IP UDP Ports

At the buckets depth, the discovery node discovers the available BACnet network segments and their correlated BACnet/IP UDP ports (e.g., standard 47808 [0xBAC0], 47809 [0xBAC1], etc.) without enumerating individual devices on those networks.

Base JSON Payload (depth: "buckets")

{
  "version": "1.5.7",
  "timestamp": "2026-09-22T14:50:05Z",
  "generation": "2026-09-22T14:50:00Z",
  "family": "bacnet",
  "network": "9288",
  "event_no": 1,
  "families": {
    "ipv4": {
      "port": 47808
    }
  }
}

3.2 entries — Discovered BACnet Devices & MAC/Transport Addresses

At the entries depth, the discovery node identifies individual BACnet devices on each network bucket and correlates each device’s BACnet instance with its specific transport IP/UDP port and MAC address.

JSON Additions Relative to buckets (depth: "entries")

{
  "addr": "291842",
  "families": {
    "ipv4": {
      "addr": "192.168.10.45",
      "port": 47808
    },
    "ethmac": {
      "addr": "82:CC:18:9A:45:1C"
    }
  }
}

3.3 system — Device Object (DO/0) Properties

At the system depth, the discovery node queries the BACnet Device Object (object-type = device, instance = <addr>) of each discovered device to populate hardware and identity metadata.

JSON Additions Relative to entries (depth: "system")

{
  "system": {
    "name": "AHU-1",
    "description": "Main North Wing Air Handler",
    "serial_no": "SN-99482104",
    "hardware": {
      "make": "Delta Controls",
      "model": "DSC-1616E"
    },
    "ancillary": {
      "firmware-revision": "4.10r3",
      "application-software-version": "1.2.0",
      "location": "Mechanical Room 2B",
      "vendor-identifier": 8
    }
  }
}

3.4 details — BACnet Object References & Properties

At the details depth, the discovery node enumerates the device’s object-list on device,<addr> and reads the descriptive and operational BACnet properties for each object.

JSON Additions Relative to system (depth: "details")

{
  "refs": {
    "AI/2": {
      "name": "ZN-T",
      "description": "Zone Space Temperature",
      "type": "analog-input",
      "units": "degrees-celsius",
      "writable": false,
      "ancillary": {
        "present-value": 21.5,
        "status-flags": [false, false, false, false],
        "event-state": "normal",
        "out-of-service": false,
        "cov-increment": 0.1
      }
    },
    "AV/12": {
      "name": "ZN-SP",
      "description": "Zone Temperature Setpoint",
      "type": "analog-value",
      "units": "degrees-celsius",
      "writable": true,
      "ancillary": {
        "present-value": 22.0,
        "status-flags": [false, false, false, false],
        "out-of-service": false
      }
    },
    "BO/21": {
      "name": "SF-CMD",
      "description": "Supply Fan Start/Stop Command",
      "type": "binary-output",
      "possible_values": ["Off", "On"],
      "writable": true,
      "ancillary": {
        "present-value": "On",
        "status-flags": [false, false, false, false],
        "out-of-service": false
      }
    },
    "MSV/1": {
      "name": "OCC-MODE",
      "description": "Zone Occupancy Mode",
      "type": "multi-state-value",
      "possible_values": ["Occupied", "Unoccupied", "Standby", "Bypass"],
      "writable": true,
      "ancillary": {
        "present-value": 1,
        "status-flags": [false, false, false, false]
      }
    }
  }
}
This site is open source. Improve this page.