bacnet-stack

When implementing objects with a Priority_Array (like Output objects), follow these rules to ensure stability and prevent race conditions:

1. Level 6 Reservation: Never use Priority Level 6 for any purpose other than the Minimum On/Off Time algorithm. It is reserved by the BACnet standard.
2. Immediate Re-evaluation: When the Present_Value of an object containing a Priority_Array is written, you must re-evaluate the array and update the Present_Value before the next service is processed. Ideally, this should happen before the write is acknowledged to avoid race conditions where a subsequent ReadProperty request returns stale data.
3. Fallback for Resource-Constrained Devices: If a device cannot afford the memory/overhead of a priority array for an "Output" object, use a "Value" object (e.g., a Binary Value instead of a Binary Output) which is not required to have a priority array.

When implementing Change of Value (COV) services, follow these rules to ensure interoperability and prevent resource exhaustion:

• Avoid Indefinite Lifetimes: Do not issue SubscribeCOV or SubscribeCOVProperty requests with a Lifetime parameter set to zero. This prevents permanent allocation of storage for removed devices and ensures subscriptions can be recovered after resets.
• Use Non-Zero Lifetimes: Issue subscriptions with a non-zero Lifetime (e.g., the duration acceptable for operating with out-of-date data) and refresh them periodically.
• Handle Failures: If a COV subscription fails, the client should fall back to polling for data and/or notifying the operator.
• Server Lifetime Support: COV servers must support all lifetime values between 1 and 28,800 seconds (8 hours).
• Client Lifetime Support: COV clients must be able to subscribe with a lifetime within the 1 to 28,800 second range.
• Proprietary Object Notifications: COV notifications from proprietary objects should include Present_Value and Status_Flags for consistency with standard objects.

When implementing a BACnet device or client, follow these interoperability guidelines to ensure compatibility with other BTL-listed devices:

• Avoid Assumptions: Do not assume a peer supports optional properties, services, or protocol revisions. Always be prepared to communicate with devices using earlier protocol revisions.
• Implement Fallbacks: If an optional feature (like COV subscription) is unavailable or rejected, fall back to a required feature (like polling).
• Handle Service Forms: If a device supports a service, it must support all forms of that service (including all parameter variations) unless specifically exempted by the standard.
• Don't Give Up on Communication: If a confirmed service request fails after all retries, do not stop attempting to communicate. If using dynamic binding (Who-Is/Who-Has), periodically re-initiate these requests to re-locate the device or object.
• Handle Future Changes: Implement parsers that can handle expanded ASN.1 choices or new enumeration values (like BACnetPropertyIdentifier) without crashing.

The gateway operates by mapping Modbus RTU registers/coils to BACnet objects (AI, AO, BI, BO).

Startup Sequence:

1. Parse CLI arguments (config path, device instance override).
2. Load gateway_config.json containing BACnet/Modbus settings and the point table.
3. Initialize the BACnet datalink (MSTP, BIP, BIP6, Ethernet, or BSC) via dlenv_init.
4. Create BACnet objects based on the point table.
5. Initialize the Modbus RTU port.
6. Broadcast the BACnet 'I-Am' message.
7. Perform the initial Modbus poll.

Main Loop:

• BACnet Communication: Calls datalink_receive() to process incoming frames via npdu_handler().
• Timers: Manages 1-second BACnet timers (dcc_timer, tsm_timer, Device_Timer).
• Modbus Polling: Every poll_interval_sec, the gateway reads registers/coils for each enabled point. It updates the BACnet Present_Value. If a Modbus read fails, the gateway sets the BACnet object's Out-of-Service property to true.

[Startup]
  │
  ├─ Parse CLI arguments (config path, device instance override)
  ├─ Load gateway_config.json  →  BACnet & Modbus settings + point table
  ├─ Initialize BACnet datalink  (mstp / bip / bip6 / ethernet / bsc via dlenv_init)
  ├─ Create BACnet objects from point table  (AI / AO / BI / BO)
  ├─ Initialize Modbus RTU port
  ├─ Broadcast I-Am
  ├─ Initial Modbus poll
  │
  └─ [Main loop] ────────────────────────────────────────────────┐
       │                                                         │
       ├─ datalink_receive()                                    │
       │     Receive BACnet frames → npdu_handler()             │
       │                                                         │
       ├─ 1-second BACnet timers                                 │
       │     dcc_timer / tsm_timer / Device_Timer                │
       │                                                         │
       └─ Modbus poll  (every poll_interval_sec seconds)         │
             Read registers/coils for each enabled point         │
             → Update BACnet Present_Value                       │
             → On failure: set Out-of-Service = true ────────────┘