Client API

High-Level Client

Simplified BACnet client combining application and client layers.

Provides a single Client async context manager for common client-only use cases. For advanced features (server handlers, custom service registration, router mode), use BACnetApplication and BACnetClient directly.

Typical usage:

from bac_py import Client, DeviceConfig

async with Client(DeviceConfig(instance_number=999)) as client:
    value = await client.read("192.168.1.100", "ai,1", "pv")
    await client.write("192.168.1.100", "av,1", "pv", 72.5, priority=8)
class bac_py.client.Client(config=None, *, instance_number=999, interface='0.0.0.0', port=47808, broadcast_address='255.255.255.255', bbmd_address=None, bbmd_ttl=60, ipv6=False, multicast_address='', vmac=None, sc_config=None, ethernet_interface=None, ethernet_mac=None)[source]

Bases: object

Simplified BACnet client for common use cases.

Combines BACnetApplication and BACnetClient into a single async context manager. All BACnetClient methods are available directly on this class.

For advanced use (server handlers, custom service registration, router mode), use BACnetApplication and BACnetClient directly.

Usage:

async with Client(DeviceConfig(instance_number=999)) as client:
    value = await client.read("192.168.1.100", "ai,1", "pv")
Parameters:
property app: BACnetApplication

The underlying BACnetApplication.

Raises:

RuntimeError – If the client has not been started.

add_route(network, router_address)[source]

Pre-populate the router cache for a remote network.

Allows sending to a remote network without broadcast-based router discovery. Useful in Docker or test environments.

Parameters:

  • network (int) – The remote network number.

  • router_address (str) – IP address of the router (e.g. "172.30.1.150" or "172.30.1.150:47808").

Return type:

None

async read(address, object_identifier, property_identifier, array_index=None)[source]

Read a property and return a decoded Python value.

See read() for details.

Return type:

object

Parameters:
async write(address, object_identifier, property_identifier, value, priority=None, array_index=None)[source]

Write a Python value to a property.

See write() for details.

Return type:

None

Parameters:
async read_multiple(address, specs)[source]

Read multiple properties from multiple objects.

See read_multiple() for details.

Return type:

dict[str, dict[str, object]]

Parameters:
async write_multiple(address, specs, priority=None, timeout=None)[source]

Write multiple properties to multiple objects.

See write_multiple() for details.

Return type:

None

Parameters:
async get_object_list(address, device_instance, timeout=None)[source]

Read the complete object list from a device.

See get_object_list() for details.

Return type:

list[ObjectIdentifier]

Parameters:
async subscribe_cov_ex(address, object_identifier, process_id, confirmed=True, lifetime=None, callback=None, timeout=None)[source]

Subscribe to COV notifications with string arguments.

See subscribe_cov_ex() for details.

Return type:

None

Parameters:
async unsubscribe_cov_ex(address, object_identifier, process_id, unregister_callback=True, timeout=None)[source]

Cancel a COV subscription with string arguments.

See unsubscribe_cov_ex() for details.

Return type:

None

Parameters:
async discover_extended(low_limit=None, high_limit=None, destination=None, timeout=3.0, expected_count=None, enrich_timeout=5.0)[source]

Discover devices and enrich with profile metadata (Annex X).

Like discover(), but also reads Profile_Name, Profile_Location, and Tags from each device.

Parameters:

  • low_limit (int | None (default: None)) – Optional lower bound of device instance range.

  • high_limit (int | None (default: None)) – Optional upper bound of device instance range.

  • destination (str | BACnetAddress | None (default: None)) – Broadcast address. Accepts an IP string (e.g. "192.168.1.255"), a BACnetAddress, or None for global broadcast.

  • timeout (float (default: 3.0)) – Seconds to wait for Who-Is responses.

  • expected_count (int | None (default: None)) – Return early once this many devices respond.

  • enrich_timeout (float (default: 5.0)) – Per-device timeout for RPM enrichment.

Return type:

list[DiscoveredDevice]

Returns:

List of DiscoveredDevice with profile metadata.

async get_alarm_summary(address, timeout=None)[source]

Get a summary of active alarms from a device.

Parameters:

  • address (str | BACnetAddress) – Target device address (IP string or BACnetAddress).

  • timeout (float | None (default: None)) – Optional caller-level timeout in seconds.

Return type:

GetAlarmSummaryACK

Returns:

Decoded GetAlarmSummaryACK with alarm entries.

async get_enrollment_summary(address, acknowledgment_filter, event_state_filter=None, event_type_filter=None, priority_min=None, priority_max=None, notification_class_filter=None, timeout=None)[source]

Get a filtered summary of event enrollments from a device.

Parameters:

  • address (str | BACnetAddress) – Target device address (IP string or BACnetAddress).

  • acknowledgment_filter (AcknowledgmentFilter) – Filter by acknowledgment state.

  • event_state_filter (EventState | None (default: None)) – Optional filter by event state.

  • event_type_filter (EventType | None (default: None)) – Optional filter by event type.

  • priority_min (int | None (default: None)) – Optional minimum priority (0–255).

  • priority_max (int | None (default: None)) – Optional maximum priority (0–255).

  • notification_class_filter (int | None (default: None)) – Optional notification class filter.

  • timeout (float | None (default: None)) – Optional caller-level timeout in seconds.

Return type:

GetEnrollmentSummaryACK

Returns:

Decoded GetEnrollmentSummaryACK.

async get_event_information(address, last_received_object_identifier=None, timeout=None)[source]

Get event state information from a device.

Parameters:

  • address (str | BACnetAddress) – Target device address (IP string or BACnetAddress).

  • last_received_object_identifier (str | tuple[str | ObjectType | int, int] | ObjectIdentifier | None (default: None)) – Optional object identifier for pagination (e.g. "ai,1"). Pass the last object from a previous response when more_events is True.

  • timeout (float | None (default: None)) – Optional caller-level timeout in seconds.

Return type:

GetEventInformationACK

Returns:

Decoded GetEventInformationACK with event summaries.

async acknowledge_alarm(address, acknowledging_process_identifier, event_object_identifier, event_state_acknowledged, time_stamp, acknowledgment_source, time_of_acknowledgment, timeout=None)[source]

Acknowledge an alarm on a remote device.

Parameters:

  • address (str | BACnetAddress) – Target device address (IP string or BACnetAddress).

  • acknowledging_process_identifier (int) – Process ID of the acknowledger.

  • event_object_identifier (str | tuple[str | ObjectType | int, int] | ObjectIdentifier) – Object whose event is being acknowledged (e.g. "ai,1").

  • event_state_acknowledged (EventState) – Event state being acknowledged.

  • time_stamp (BACnetTimeStamp) – Time stamp of the event being acknowledged.

  • acknowledgment_source (str) – Character string identifying the source.

  • time_of_acknowledgment (BACnetTimeStamp) – Time stamp of the acknowledgment.

  • timeout (float | None (default: None)) – Optional caller-level timeout in seconds.

Return type:

None

async send_text_message(destination, message, *, confirmed=True, message_priority=None, message_class_numeric=None, message_class_character=None, timeout=None)[source]

Send a text message to a device or broadcast address.

Parameters:

  • destination (str | BACnetAddress) – Target address (IP string or BACnetAddress).

  • message (str) – Text message content.

  • confirmed (bool (default: True)) – True for confirmed delivery (default), False for unconfirmed (fire-and-forget).

  • message_priority (MessagePriority | None (default: None)) – Message priority. Defaults to NORMAL.

  • message_class_numeric (int | None (default: None)) – Optional numeric message class.

  • message_class_character (str | None (default: None)) – Optional character message class.

  • timeout (float | None (default: None)) – Optional caller-level timeout (confirmed only).

Return type:

None

async backup(address, password=None, poll_interval=1.0, timeout=None)[source]

Back up a remote BACnet device’s configuration.

Executes the full backup procedure (Clause 19.1): start backup, poll state, download config files, end backup.

Parameters:

  • address (str | BACnetAddress) – Target device address (IP string or BACnetAddress).

  • password (str | None (default: None)) – Optional password for ReinitializeDevice.

  • poll_interval (float (default: 1.0)) – Seconds between state polls.

  • timeout (float | None (default: None)) – Optional overall timeout in seconds.

Return type:

BackupData

Returns:

BackupData with downloaded configuration files.

async restore(address, backup_data, password=None, poll_interval=1.0, timeout=None)[source]

Restore a remote BACnet device from backup data.

Executes the full restore procedure (Clause 19.1): start restore, poll state, upload config files, end restore.

Parameters:

  • address (str | BACnetAddress) – Target device address (IP string or BACnetAddress).

  • backup_data (BackupData) – BackupData from a previous backup().

  • password (str | None (default: None)) – Optional password for ReinitializeDevice.

  • poll_interval (float (default: 1.0)) – Seconds between state polls.

  • timeout (float | None (default: None)) – Optional overall timeout in seconds.

Return type:

None

async query_audit_log(address, audit_log, query_parameters, start_at_sequence_number=None, requested_count=100, timeout=None)[source]

Query audit log records from a device.

Parameters:
Return type:

AuditLogQueryACK

Returns:

Decoded AuditLogQueryACK.

async subscribe_cov_property(address, object_identifier, property_identifier, process_id, confirmed=True, lifetime=None, property_array_index=None, cov_increment=None, timeout=None)[source]

Subscribe to property-level COV notifications.

Like subscribe_cov_ex() but monitors a specific property rather than the default COV properties for the object type.

Parameters:

  • address (str | BACnetAddress) – Target device address (IP string or BACnetAddress).

  • object_identifier (str | tuple[str | ObjectType | int, int] | ObjectIdentifier) – Object to monitor (e.g. "ai,1").

  • property_identifier (str | int | PropertyIdentifier) – Property to monitor (e.g. "pv").

  • process_id (int) – Subscriber process identifier (caller-managed).

  • confirmed (bool (default: True)) – True for confirmed notifications.

  • lifetime (int | None (default: None)) – Subscription lifetime in seconds, or None.

  • property_array_index (int | None (default: None)) – Optional array index within the property.

  • cov_increment (float | None (default: None)) – Optional COV increment override.

  • timeout (float | None (default: None)) – Optional caller-level timeout in seconds.

Return type:

None

async read_property(address, object_identifier, property_identifier, array_index=None, timeout=None)[source]

Read a single property from a remote device.

See read_property().

Return type:

ReadPropertyACK

Parameters:
async write_property(address, object_identifier, property_identifier, value, priority=None, array_index=None, timeout=None)[source]

Write a property value to a remote device.

See write_property().

Return type:

None

Parameters:
async read_property_multiple(address, read_access_specs, timeout=None)[source]

Read multiple properties from one or more objects.

See read_property_multiple().

Return type:

ReadPropertyMultipleACK

Parameters:
async write_property_multiple(address, write_access_specs, timeout=None)[source]

Write multiple properties to one or more objects.

See write_property_multiple().

Return type:

None

Parameters:
async read_range(address, object_identifier, property_identifier, array_index=None, range_qualifier=None, timeout=None)[source]

Read a range of items from a list or array property.

See read_range().

Return type:

ReadRangeACK

Parameters:
async who_is(low_limit=None, high_limit=None, destination=None, timeout=3.0, expected_count=None)[source]

Discover devices via Who-Is broadcast.

See who_is().

Parameters:

  • low_limit (int | None (default: None)) – Optional lower bound of device instance range.

  • high_limit (int | None (default: None)) – Optional upper bound of device instance range.

  • destination (str | BACnetAddress | None (default: None)) – Broadcast address. Accepts an IP string (e.g. "192.168.1.255"), a BACnetAddress, or None for global broadcast.

  • timeout (float (default: 3.0)) – Seconds to wait for responses.

  • expected_count (int | None (default: None)) – When set, return early once this many responses have been collected.

Return type:

list[IAmRequest]

async discover(low_limit=None, high_limit=None, destination=None, timeout=3.0, expected_count=None)[source]

Discover devices via Who-Is and return enriched results.

See discover().

Parameters:

  • low_limit (int | None (default: None)) – Optional lower bound of device instance range.

  • high_limit (int | None (default: None)) – Optional upper bound of device instance range.

  • destination (str | BACnetAddress | None (default: None)) – Broadcast address. Accepts an IP string (e.g. "192.168.1.255"), a BACnetAddress, or None for global broadcast.

  • timeout (float (default: 3.0)) – Seconds to wait for responses.

  • expected_count (int | None (default: None)) – When set, return early once this many devices have been discovered.

Return type:

list[DiscoveredDevice]

async subscribe_cov(address, object_identifier, process_id, confirmed=True, lifetime=None, timeout=None)[source]

Subscribe to COV notifications.

Parameters:

  • address (str | BACnetAddress) – Target device address (IP string or BACnetAddress).

  • object_identifier (str | tuple[str | ObjectType | int, int] | ObjectIdentifier) – Object to monitor (e.g. "ai,1").

  • process_id (int) – Subscriber process identifier.

  • confirmed (bool (default: True)) – True for confirmed notifications.

  • lifetime (int | None (default: None)) – Subscription lifetime in seconds, or None.

  • timeout (float | None (default: None)) – Optional caller-level timeout in seconds.

Return type:

None

async unsubscribe_cov(address, object_identifier, process_id, timeout=None)[source]

Cancel a COV subscription.

Parameters:

  • address (str | BACnetAddress) – Target device address (IP string or BACnetAddress).

  • object_identifier (str | tuple[str | ObjectType | int, int] | ObjectIdentifier) – Object whose subscription to cancel (e.g. "ai,1").

  • process_id (int) – Subscriber process identifier.

  • timeout (float | None (default: None)) – Optional caller-level timeout in seconds.

Return type:

None

async device_communication_control(address, enable_disable, time_duration=None, password=None, timeout=None)[source]

Send DeviceCommunicationControl-Request.

Parameters:

  • address (str | BACnetAddress) – Target device address (IP string or BACnetAddress).

  • enable_disable (str | EnableDisable) – State to set. Accepts a string ("enable", "disable", "disable-initiation") or EnableDisable enum.

  • time_duration (int | None (default: None)) – Optional duration in minutes.

  • password (str | None (default: None)) – Optional password.

  • timeout (float | None (default: None)) – Optional caller-level timeout in seconds.

Return type:

None

async reinitialize_device(address, reinitialized_state, password=None, timeout=None)[source]

Send ReinitializeDevice-Request.

Parameters:

  • address (str | BACnetAddress) – Target device address (IP string or BACnetAddress).

  • reinitialized_state (str | ReinitializedState) – State to set. Accepts a string ("coldstart", "warmstart", "start-backup", etc.) or ReinitializedState enum.

  • password (str | None (default: None)) – Optional password.

  • timeout (float | None (default: None)) – Optional caller-level timeout in seconds.

Return type:

None

time_synchronization(destination, date, time)[source]

Send TimeSynchronization-Request.

Parameters:
Return type:

None

utc_time_synchronization(destination, date, time)[source]

Send UTCTimeSynchronization-Request.

Parameters:
Return type:

None

async atomic_read_file(address, file_identifier, access_method, timeout=None)[source]

Send AtomicReadFile-Request.

Parameters:
Return type:

AtomicReadFileACK

async atomic_write_file(address, file_identifier, access_method, timeout=None)[source]

Send AtomicWriteFile-Request.

Parameters:
Return type:

AtomicWriteFileACK

async create_object(address, object_type=None, object_identifier=None, timeout=None)[source]

Send CreateObject-Request.

Parameters:

  • address (str | BACnetAddress) – Target device address (IP string or BACnetAddress).

  • object_type (str | ObjectType | None (default: None)) – Object type to create. Accepts a string alias (e.g. "av" or "analog-value") or ObjectType.

  • object_identifier (str | tuple[str | ObjectType | int, int] | ObjectIdentifier | None (default: None)) – Specific object identifier to create (e.g. "av,1"). If provided, object_type is ignored.

  • timeout (float | None (default: None)) – Optional caller-level timeout in seconds.

Return type:

ObjectIdentifier

Returns:

ObjectIdentifier of the newly created object.

async delete_object(address, object_identifier, timeout=None)[source]

Send DeleteObject-Request.

Parameters:
Return type:

None

async add_list_element(address, object_identifier, property_identifier, list_of_elements, array_index=None, timeout=None)[source]

Send AddListElement-Request.

Parameters:
Return type:

None

async remove_list_element(address, object_identifier, property_identifier, list_of_elements, array_index=None, timeout=None)[source]

Send RemoveListElement-Request.

Parameters:
Return type:

None

async who_has(object_identifier=None, object_name=None, low_limit=None, high_limit=None, destination=None, timeout=3.0, expected_count=None)[source]

Discover objects via Who-Has broadcast.

See who_has().

Parameters:

  • object_identifier (str | tuple[str | ObjectType | int, int] | ObjectIdentifier | None (default: None)) – Object to search for by identifier (e.g. "ai,1").

  • object_name (str | None (default: None)) – Object to search for by name.

  • low_limit (int | None (default: None)) – Optional lower bound of device instance range.

  • high_limit (int | None (default: None)) – Optional upper bound of device instance range.

  • destination (str | BACnetAddress | None (default: None)) – Broadcast address. Accepts an IP string, a BACnetAddress, or None for global broadcast.

  • timeout (float (default: 3.0)) – Seconds to wait for responses.

  • expected_count (int | None (default: None)) – When set, return early once this many responses have been collected.

Return type:

list[IHaveRequest]

async confirmed_private_transfer(address, vendor_id, service_number, service_parameters=None, timeout=None)[source]

Send ConfirmedPrivateTransfer-Request.

Parameters:

  • address (str | BACnetAddress) – Target device address (IP string or BACnetAddress).

  • vendor_id (int) – Vendor identifier.

  • service_number (int) – Vendor-specific service number.

  • service_parameters (bytes | None (default: None)) – Optional service parameters.

  • timeout (float | None (default: None)) – Optional caller-level timeout in seconds.

Return type:

ConfirmedPrivateTransferACK

unconfirmed_private_transfer(destination, vendor_id, service_number, service_parameters=None)[source]

Send UnconfirmedPrivateTransfer-Request.

Parameters:

  • destination (str | BACnetAddress) – Target address (IP string or BACnetAddress).

  • vendor_id (int) – Vendor identifier.

  • service_number (int) – Vendor-specific service number.

  • service_parameters (bytes | None (default: None)) – Optional service parameters.

Return type:

None

async traverse_hierarchy(address, root, *, max_depth=10, timeout=None)[source]

Walk the Structured View hierarchy from a root object.

Parameters:

  • address (str | BACnetAddress) – Target device address (IP string or BACnetAddress).

  • root (str | tuple[str | ObjectType | int, int] | ObjectIdentifier) – Root object identifier (e.g. "structured-view,1").

  • max_depth (int (default: 10)) – Maximum recursion depth (default 10).

  • timeout (float | None (default: None)) – Optional caller-level timeout in seconds.

Return type:

list[ObjectIdentifier]

Returns:

Flat list of all ObjectIdentifier found.

async subscribe_cov_property_multiple(address, process_id, specifications, confirmed=True, lifetime=None, max_notification_delay=None, timeout=None)[source]

Subscribe to property-level COV for multiple objects at once.

Parameters:

  • address (str | BACnetAddress) – Target device address (IP string or BACnetAddress).

  • process_id (int) – Subscriber process identifier.

  • specifications (list[COVSubscriptionSpecification]) – List of subscription specifications.

  • confirmed (bool (default: True)) – True for confirmed notifications.

  • lifetime (int | None (default: None)) – Subscription lifetime in seconds, or None.

  • max_notification_delay (int | None (default: None)) – Optional max delay in seconds.

  • timeout (float | None (default: None)) – Optional caller-level timeout in seconds.

Return type:

None

write_group(destination, group_number, write_priority, change_list)[source]

Send WriteGroup-Request (unconfirmed).

Parameters:

  • destination (str | BACnetAddress) – Target address (IP string or BACnetAddress).

  • group_number (int) – Group number to write to.

  • write_priority (int) – Write priority (1–16).

  • change_list (list[GroupChannelValue]) – Channel values to write.

Return type:

None

async discover_unconfigured(destination=None, timeout=5.0)[source]

Discover unconfigured devices via Who-Am-I (Clause 19.7).

Parameters:

  • destination (str | BACnetAddress | None (default: None)) – Broadcast address. Accepts an IP string, a BACnetAddress, or None for global broadcast.

  • timeout (float (default: 5.0)) – Seconds to wait for responses.

Return type:

list[UnconfiguredDevice]

Returns:

List of UnconfiguredDevice found.

async register_as_foreign_device(bbmd_address, ttl=60)[source]

Register as a foreign device with a BBMD.

See register_as_foreign_device().

Return type:

None

Parameters:

  • bbmd_address (str)

  • ttl (int)

async deregister_foreign_device()[source]

Deregister from the BBMD and stop re-registration.

See deregister_foreign_device().

Return type:

None

property is_foreign_device: bool

Whether this device is currently registered as a foreign device.

property foreign_device_status: ForeignDeviceStatus | None

Current foreign device registration status.

async wait_for_registration(timeout=10.0)[source]

Wait for foreign device registration to complete.

See wait_for_registration().

Parameters:

timeout (float (default: 10.0)) – Maximum seconds to wait.

Return type:

bool

Returns:

True if registered, False if timeout expired.

async read_bdt(bbmd_address, timeout=5.0)[source]

Read the Broadcast Distribution Table from a remote BBMD.

See read_bdt().

Return type:

list[BDTEntryInfo]

Parameters:
async read_fdt(bbmd_address, timeout=5.0)[source]

Read the Foreign Device Table from a remote BBMD.

See read_fdt().

Return type:

list[FDTEntryInfo]

Parameters:
async write_bdt(bbmd_address, entries, timeout=5.0)[source]

Write a Broadcast Distribution Table to a remote BBMD.

See write_bdt().

Return type:

None

Parameters:
async delete_fdt_entry(bbmd_address, entry_address, timeout=5.0)[source]

Delete a Foreign Device Table entry on a remote BBMD.

See delete_fdt_entry().

Return type:

None

Parameters:

  • bbmd_address (str)

  • entry_address (str)

  • timeout (float)

async who_is_router_to_network(network=None, destination=None, timeout=3.0, expected_count=None)[source]

Discover routers and reachable networks.

See who_is_router_to_network().

Parameters:

  • network (int | None (default: None)) – Optional specific network to query. If None, discovers all reachable networks.

  • destination (str | BACnetAddress | None (default: None)) – Target for the query. Accepts an IP string, a BACnetAddress, or None for local broadcast.

  • timeout (float (default: 3.0)) – Seconds to wait for responses.

  • expected_count (int | None (default: None)) – When set, return early once this many distinct routers have responded.

Return type:

list[RouterInfo]

Protocol-Level Client

High-level BACnet client API per ASHRAE 135-2020.

class bac_py.app.client.DiscoveredDevice(address, instance, vendor_id, max_apdu_length, segmentation_supported, profile_name=None, profile_location=None, tags=None)[source]

Bases: object

Device discovered via Who-Is / I-Am.

Provides parsed convenience properties from the I-Am response along with the source address of the responding device.

Returned by BACnetClient.discover():

devices = await client.discover(timeout=3.0)
for dev in devices:
    print(dev.instance, dev.address_str)
Parameters:
address: BACnetAddress

Network address the I-Am response was received from.

instance: int

Device instance number.

vendor_id: int

Vendor identifier.

max_apdu_length: int

Maximum APDU length accepted by the device.

segmentation_supported: Segmentation

Segmentation support level.

profile_name: str | None

Profile name from extended discovery (Annex X), or None.

profile_location: str | None

Profile location from extended discovery (Annex X), or None.

tags: list[dict[str, Any]] | None

Tags from extended discovery (Annex X), or None.

property address_str: str

Human-readable address string.

class bac_py.app.client.UnconfiguredDevice(address, vendor_id, model_name, serial_number)[source]

Bases: object

An unconfigured device discovered via Who-Am-I (Clause 19.7).

Returned by BACnetClient.discover_unconfigured().

Parameters:
address: BACnetAddress

Network address the Who-Am-I was received from.

vendor_id: int

Vendor identifier.

model_name: str

Model name string.

serial_number: str

Serial number string.

class bac_py.app.client.DeviceAssignmentEntry(vendor_id, serial_number, device_identifier, device_mac_address, device_network_number=None)[source]

Bases: object

A mapping from (vendor_id, serial_number) to a device identity.

Used by DeviceAssignmentTable for auto-responding to Who-Am-I with You-Are.

Parameters:
vendor_id: int
serial_number: str
device_identifier: ObjectIdentifier
device_mac_address: bytes
device_network_number: int | None
class bac_py.app.client.DeviceAssignmentTable[source]

Bases: object

Supervisor-side table for automatic device identity assignment.

When a Who-Am-I is received, the table looks up the device by (vendor_id, serial_number) and provides the You-Are response data.

add(entry)[source]

Add or update an assignment entry.

Return type:

None

Parameters:

entry (DeviceAssignmentEntry)

remove(vendor_id, serial_number)[source]

Remove an assignment entry.

Return type:

None

Parameters:

  • vendor_id (int)

  • serial_number (str)

lookup(vendor_id, serial_number)[source]

Look up assignment for a device.

Return type:

DeviceAssignmentEntry | None

Parameters:

  • vendor_id (int)

  • serial_number (str)

class bac_py.app.client.BackupData(device_instance, configuration_files)[source]

Bases: object

Data from a backup of a remote BACnet device (Clause 19.1).

Contains the configuration files downloaded during a backup procedure.

Parameters:
device_instance: int

Device instance number of the backed-up device.

configuration_files: list[tuple[ObjectIdentifier, bytes]]

List of (file_object_id, file_data) tuples.

bac_py.app.client.decode_cov_values(notification)[source]

Decode COV notification property values to a Python dict.

Extracts and decodes the list_of_values from a COVNotificationRequest into a human-readable dictionary mapping property names to decoded Python values.

Parameters:

notification (COVNotificationRequest) – A decoded COV notification request.

Return type:

dict[str, object]

Returns:

Dict mapping property name strings (hyphenated, lowercase) to decoded Python values.

Example:

def on_change(notification, source):
    values = decode_cov_values(notification)
    print(values)
    # {"present-value": 72.5, "status-flags": BitString(...)}
class bac_py.app.client.BDTEntryInfo(address, mask)[source]

Bases: object

Human-readable Broadcast Distribution Table entry.

Returned by BACnetClient.read_bdt().

Parameters:
address: str

BBMD address string (e.g. "192.168.1.1:47808").

mask: str

Broadcast distribution mask (e.g. "255.255.255.255").

class bac_py.app.client.FDTEntryInfo(address, ttl, remaining)[source]

Bases: object

Human-readable Foreign Device Table entry.

Returned by BACnetClient.read_fdt().

Parameters:
address: str

Foreign device address string (e.g. "10.0.0.50:47808").

ttl: int

Registration time-to-live in seconds.

remaining: int

Seconds remaining before this entry expires.

class bac_py.app.client.RouterInfo(address, networks)[source]

Bases: object

Router discovered via Who-Is-Router-To-Network.

Returned by BACnetClient.who_is_router_to_network().

Parameters:
address: str

Router address string (MAC as hex).

networks: list[int]

Network numbers reachable through this router.

class bac_py.app.client.BACnetClient(app)[source]

Bases: object

High-level async BACnet client API.

Wraps a BACnetApplication to provide typed methods for common BACnet services: ReadProperty, WriteProperty, ReadPropertyMultiple, WritePropertyMultiple, ReadRange, and Who-Is/I-Am.

Parameters:

app (BACnetApplication)

async read_property(address, object_identifier, property_identifier, array_index=None, timeout=None)[source]

Read a single property from a remote device.

Parameters:

  • address (BACnetAddress) – Target device address.

  • object_identifier (ObjectIdentifier) – Object to read from.

  • property_identifier (PropertyIdentifier) – Property to read.

  • array_index (int | None (default: None)) – Optional array index for array properties.

  • timeout (float | None (default: None)) – Optional caller-level timeout in seconds.

Return type:

ReadPropertyACK

Returns:

Decoded ReadPropertyACK containing the property value.

Raises:
async write_property(address, object_identifier, property_identifier, value, priority=None, array_index=None, timeout=None)[source]

Write a property value to a remote device.

Parameters:

  • address (BACnetAddress) – Target device address.

  • object_identifier (ObjectIdentifier) – Object to write to.

  • property_identifier (PropertyIdentifier) – Property to write.

  • value (bytes) – Application-tagged encoded property value bytes.

  • priority (int | None (default: None)) – Optional write priority (1–16).

  • array_index (int | None (default: None)) – Optional array index for array properties.

  • timeout (float | None (default: None)) – Optional caller-level timeout in seconds.

Raises:
Return type:

None

async read_property_multiple(address, read_access_specs, timeout=None)[source]

Read multiple properties from one or more objects.

Parameters:

  • address (BACnetAddress) – Target device address.

  • read_access_specs (list[ReadAccessSpecification]) – List of read access specifications, each containing an object identifier and list of property references to read.

  • timeout (float | None (default: None)) – Optional caller-level timeout in seconds.

Return type:

ReadPropertyMultipleACK

Returns:

Decoded ReadPropertyMultipleACK with per-property results.

Raises:
async write_property_multiple(address, write_access_specs, timeout=None)[source]

Write multiple properties to one or more objects.

Parameters:

  • address (BACnetAddress) – Target device address.

  • write_access_specs (list[WriteAccessSpecification]) – List of write access specifications, each containing an object identifier and list of property values to write.

  • timeout (float | None (default: None)) – Optional caller-level timeout in seconds.

Raises:
Return type:

None

async read(address, object_identifier, property_identifier, array_index=None, timeout=None)[source]

Read a property and return a decoded Python value.

Convenience wrapper around read_property() that parses addresses and identifiers from strings and decodes the returned application-tagged bytes into native Python types.

Parameters:
Return type:

object

Returns:

Decoded Python value (float, int, str, bool, etc.). Returns a list if the property contains multiple application-tagged values.

Example:

value = await client.read("192.168.1.100", "ai,1", "pv")
name = await client.read("192.168.1.100", "ai,1", "object-name")
async write(address, object_identifier, property_identifier, value, priority=None, array_index=None, timeout=None)[source]

Write a Python value to a property.

Convenience wrapper around write_property() that parses addresses and identifiers from strings and automatically encodes the value to the appropriate BACnet application-tagged format based on the Python type and target property.

Type mapping:

  • float -> Real

  • int -> Unsigned (or Real for analog PV, Enumerated for binary PV, Unsigned for multi-state PV)

  • str -> Character String

  • bool -> Enumerated (1/0)

  • None -> Null (relinquish a command priority)

  • IntEnum -> Enumerated

  • bytes -> pass-through (already-encoded)

Parameters:

  • address (str | BACnetAddress) – Target device (e.g. "192.168.1.100").

  • object_identifier (str | tuple[str | ObjectType | int, int] | ObjectIdentifier) – Object to write (e.g. "analog-value,1" or "av,1").

  • property_identifier (str | int | PropertyIdentifier) – Property to write (e.g. "present-value" or "pv").

  • value (object) – Python value to write (auto-encoded).

  • priority (int | None (default: None)) – Optional write priority (1–16).

  • array_index (int | None (default: None)) – Optional array index.

  • timeout (float | None (default: None)) – Optional caller-level timeout in seconds.

Return type:

None

Example:

await client.write("192.168.1.100", "av,1", "pv", 72.5, priority=8)
await client.write("192.168.1.100", "bo,1", "pv", 1, priority=8)
await client.write("192.168.1.100", "av,1", "pv", None, priority=8)
async read_multiple(address, specs, timeout=None)[source]

Read multiple properties from multiple objects.

Convenience wrapper around read_property_multiple() that accepts a simplified dict format and returns decoded Python values.

Parameters:
Return type:

dict[str, dict[str, object]]

Returns:

Nested dict mapping object ID strings to property name/value dicts. Property values are decoded to native Python types. Properties that returned errors have None as their value.

Result keys always use canonical hyphenated object type names (e.g. "analog-input,1") regardless of the input format used (e.g. "ai,1").

Example:

{
    "analog-input,1": {
        "present-value": 72.5,
        "object-name": "Zone Temp",
        "units": 62,
    },
}

async write_multiple(address, specs, priority=None, timeout=None)[source]

Write multiple properties to multiple objects.

Convenience wrapper around write_property_multiple() that accepts a simplified dict format and automatically encodes Python values.

Parameters:
Raises:
Return type:

None

Example:

await client.write_multiple(
    "192.168.1.100",
    {
        "av,1": {"pv": 72.5},
        "bo,1": {"pv": 1},
    },
    priority=8,
)
async get_object_list(address, device_instance, timeout=None)[source]

Read the complete object list from a device.

Attempts to read the full object-list property first. If the response is too large (BACnetAbortError with segmentation-not-supported), falls back to reading the array length then each element individually.

Parameters:

  • address (str | BACnetAddress) – Target device (e.g. "192.168.1.100").

  • device_instance (int) – Device instance number of the target.

  • timeout (float | None (default: None)) – Optional caller-level timeout in seconds.

Return type:

list[ObjectIdentifier]

Returns:

List of ObjectIdentifier for all objects in the device.

Example:

objects = await client.get_object_list("192.168.1.100", 1234)
for obj in objects:
    print(obj.object_type, obj.instance_number)
async subscribe_cov_ex(address, object_identifier, process_id, confirmed=True, lifetime=None, callback=None, timeout=None)[source]

Subscribe to COV notifications with string arguments.

Convenience wrapper around subscribe_cov() that accepts flexible address and object identifier formats and optionally registers a notification callback.

Parameters:

  • address (str | BACnetAddress) – Target device (e.g. "192.168.1.100").

  • object_identifier (str | tuple[str | ObjectType | int, int] | ObjectIdentifier) – Object to monitor (e.g. "ai,1").

  • process_id (int) – Subscriber process identifier (caller-managed).

  • confirmed (bool (default: True)) – True for confirmed notifications, False for unconfirmed.

  • lifetime (int | None (default: None)) – Subscription lifetime in seconds, or None for indefinite.

  • callback (Callable[[COVNotificationRequest, BACnetAddress], object] | None (default: None)) – Optional callback for COV notifications. Receives (COVNotificationRequest, source_address). If provided, automatically registered via register_cov_callback().

  • timeout (float | None (default: None)) – Optional caller-level timeout in seconds.

Return type:

None

Example:

def on_change(notification, source):
    values = decode_cov_values(notification)
    print(f"COV from {source}: {values}")


await client.subscribe_cov_ex(
    "192.168.1.100",
    "ai,1",
    process_id=1,
    callback=on_change,
    lifetime=3600,
)
async unsubscribe_cov_ex(address, object_identifier, process_id, unregister_callback=True, timeout=None)[source]

Cancel a COV subscription with string arguments.

Convenience wrapper around unsubscribe_cov() that accepts flexible address and object identifier formats and optionally unregisters the notification callback.

Parameters:

  • address (str | BACnetAddress) – Target device (e.g. "192.168.1.100").

  • object_identifier (str | tuple[str | ObjectType | int, int] | ObjectIdentifier) – Object being monitored (e.g. "ai,1").

  • process_id (int) – Subscriber process identifier used during subscription.

  • unregister_callback (bool (default: True)) – If True, also unregister the COV callback.

  • timeout (float | None (default: None)) – Optional caller-level timeout in seconds.

Return type:

None

async read_range(address, object_identifier, property_identifier, array_index=None, range_qualifier=None, timeout=None)[source]

Read a range of items from a list or array property.

Parameters:
Return type:

ReadRangeACK

Returns:

Decoded ReadRangeACK with the requested items.

Raises:
async who_is(low_limit=None, high_limit=None, destination=BACnetAddress(network=65535, mac_address=b''), timeout=3.0, expected_count=None)[source]

Discover devices via Who-Is broadcast.

Sends a Who-Is request and collects I-Am responses for the specified timeout duration.

Parameters:

  • low_limit (int | None (default: None)) – Optional lower bound of device instance range.

  • high_limit (int | None (default: None)) – Optional upper bound of device instance range.

  • destination (BACnetAddress (default: BACnetAddress(network=65535, mac_address=b''))) – Broadcast address (default: global broadcast).

  • timeout (float (default: 3.0)) – Seconds to wait for responses.

  • expected_count (int | None (default: None)) – When set, return early once this many responses have been collected instead of waiting for the full timeout.

Return type:

list[IAmRequest]

Returns:

List of IAmRequest responses received within the timeout.

async discover(low_limit=None, high_limit=None, destination=BACnetAddress(network=65535, mac_address=b''), timeout=3.0, expected_count=None)[source]

Discover devices via Who-Is and return enriched results.

Convenience wrapper around who_is() that captures the source address of each I-Am response and returns DiscoveredDevice objects with parsed fields.

To discover devices on a remote network reachable through a router, pass a remote broadcast BACnetAddress:

from bac_py.network.address import BACnetAddress

remote = BACnetAddress(network=2, mac_address=b"\\xff\\xff\\xff\\xff")
devices = await client.discover(destination=remote, timeout=5.0)

When using the Client wrapper, you can pass a string like "192.168.1.255" for directed local broadcast.

Parameters:

  • low_limit (int | None (default: None)) – Optional lower bound of device instance range.

  • high_limit (int | None (default: None)) – Optional upper bound of device instance range.

  • destination (BACnetAddress (default: BACnetAddress(network=65535, mac_address=b''))) – Broadcast address (default: global broadcast).

  • timeout (float (default: 3.0)) – Seconds to wait for responses.

  • expected_count (int | None (default: None)) – When set, return early once this many devices have been discovered instead of waiting for the full timeout.

Return type:

list[DiscoveredDevice]

Returns:

List of DiscoveredDevice with address and device info.

Example:

devices = await client.discover(timeout=3.0)
for dev in devices:
    print(dev.instance, dev.address_str, dev.vendor_id)
async discover_extended(low_limit=None, high_limit=None, destination=BACnetAddress(network=65535, mac_address=b''), timeout=3.0, expected_count=None, enrich_timeout=5.0)[source]

Discover devices and enrich with profile metadata (Annex X).

Calls discover() to get the initial device list, then for each device reads PROFILE_NAME, PROFILE_LOCATION, and TAGS via ReadPropertyMultiple to populate extended fields.

Parameters:

  • low_limit (int | None (default: None)) – Optional lower bound of device instance range.

  • high_limit (int | None (default: None)) – Optional upper bound of device instance range.

  • destination (BACnetAddress (default: BACnetAddress(network=65535, mac_address=b''))) – Broadcast address (default: global broadcast).

  • timeout (float (default: 3.0)) – Seconds to wait for Who-Is responses.

  • expected_count (int | None (default: None)) – Return early once this many devices respond.

  • enrich_timeout (float (default: 5.0)) – Per-device timeout for RPM enrichment.

Return type:

list[DiscoveredDevice]

Returns:

List of DiscoveredDevice with profile metadata.

async traverse_hierarchy(address, root, *, max_depth=10, timeout=None)[source]

Traverse a Structured View hierarchy via subordinate lists.

Reads SUBORDINATE_LIST from the root Structured View object, then recursively descends into any subordinate Structured View objects up to max_depth levels.

Parameters:

  • address (str | BACnetAddress) – Target device (e.g. "192.168.1.100").

  • root (str | tuple[str | ObjectType | int, int] | ObjectIdentifier) – Root Structured View object (e.g. "sv,1" or "structured-view,1").

  • max_depth (int (default: 10)) – Maximum recursion depth (prevents cycles).

  • timeout (float | None (default: None)) – Optional per-request timeout in seconds.

Return type:

list[ObjectIdentifier]

Returns:

Flat list of all discovered ObjectIdentifier values, including Structured View objects themselves.

Example:

objects = await client.traverse_hierarchy("192.168.1.100", "sv,1", max_depth=5)
async subscribe_cov(address, object_identifier, process_id, confirmed=True, lifetime=None, timeout=None)[source]

Subscribe to COV notifications from a remote device.

Sends a SubscribeCOV-Request per Clause 13.14.1. The remote device will send confirmed or unconfirmed COV notifications when the monitored object’s value changes.

Parameters:

  • address (BACnetAddress) – Target device address.

  • object_identifier (ObjectIdentifier) – Object to monitor.

  • process_id (int) – Subscriber process identifier (caller-managed).

  • confirmed (bool (default: True)) – True for confirmed notifications, False for unconfirmed.

  • lifetime (int | None (default: None)) – Subscription lifetime in seconds, or None for indefinite.

  • timeout (float | None (default: None)) – Optional caller-level timeout in seconds.

Raises:
Return type:

None

async unsubscribe_cov(address, object_identifier, process_id, timeout=None)[source]

Cancel a COV subscription on a remote device.

Per Clause 13.14, omits issueConfirmedNotifications and lifetime to indicate cancellation.

Parameters:

  • address (BACnetAddress) – Target device address.

  • object_identifier (ObjectIdentifier) – Object being monitored.

  • process_id (int) – Subscriber process identifier used during subscription.

  • timeout (float | None (default: None)) – Optional caller-level timeout in seconds.

Raises:
Return type:

None

async subscribe_cov_property(address, object_identifier, property_identifier, process_id, confirmed=True, lifetime=None, property_array_index=None, cov_increment=None, timeout=None)[source]

Subscribe to property-level COV notifications per Clause 13.15.

Parameters:

  • address (BACnetAddress) – Target device address.

  • object_identifier (ObjectIdentifier) – Object to monitor.

  • property_identifier (int) – Specific property to monitor.

  • process_id (int) – Subscriber process identifier (caller-managed).

  • confirmed (bool (default: True)) – True for confirmed notifications, False for unconfirmed.

  • lifetime (int | None (default: None)) – Subscription lifetime in seconds, or None for indefinite.

  • property_array_index (int | None (default: None)) – Optional array index within the property.

  • cov_increment (float | None (default: None)) – Optional COV increment override.

  • timeout (float | None (default: None)) – Optional caller-level timeout in seconds.

Raises:
Return type:

None

async subscribe_cov_property_multiple(address, process_id, specifications, confirmed=True, lifetime=None, max_notification_delay=None, timeout=None)[source]

Subscribe to multiple property-level COV notifications per Clause 13.16.

Parameters:

  • address (BACnetAddress) – Target device address.

  • process_id (int) – Subscriber process identifier (caller-managed).

  • specifications (list[COVSubscriptionSpecification]) – List of subscription specifications, each containing a monitored object and its list of COV references.

  • confirmed (bool (default: True)) – True for confirmed notifications.

  • lifetime (int | None (default: None)) – Subscription lifetime in seconds.

  • max_notification_delay (int | None (default: None)) – Maximum notification delay in seconds.

  • timeout (float | None (default: None)) – Optional caller-level timeout in seconds.

Raises:
Return type:

None

async device_communication_control(address, enable_disable, time_duration=None, password=None, timeout=None)[source]

Send DeviceCommunicationControl-Request per Clause 16.1.

Parameters:

  • address (BACnetAddress) – Target device address.

  • enable_disable (EnableDisable) – Enable/disable communication state.

  • time_duration (int | None (default: None)) – Optional duration in minutes.

  • password (str | None (default: None)) – Optional password string (1–20 chars).

  • timeout (float | None (default: None)) – Optional caller-level timeout in seconds.

Raises:
Return type:

None

async reinitialize_device(address, reinitialized_state, password=None, timeout=None)[source]

Send ReinitializeDevice-Request per Clause 16.4.

Parameters:

  • address (BACnetAddress) – Target device address.

  • reinitialized_state (ReinitializedState) – Desired reinitialization state.

  • password (str | None (default: None)) – Optional password string (1–20 chars).

  • timeout (float | None (default: None)) – Optional caller-level timeout in seconds.

Raises:
Return type:

None

time_synchronization(destination, date, time)[source]

Send TimeSynchronization-Request per Clause 16.7.

This is an unconfirmed service (fire-and-forget).

Parameters:

  • destination (BACnetAddress) – Target device or broadcast address.

  • date (BACnetDate) – BACnet date to synchronize.

  • time (BACnetTime) – BACnet time to synchronize.

Return type:

None

utc_time_synchronization(destination, date, time)[source]

Send UTCTimeSynchronization-Request per Clause 16.8.

This is an unconfirmed service (fire-and-forget).

Parameters:

  • destination (BACnetAddress) – Target device or broadcast address.

  • date (BACnetDate) – BACnet UTC date to synchronize.

  • time (BACnetTime) – BACnet UTC time to synchronize.

Return type:

None

async atomic_read_file(address, file_identifier, access_method, timeout=None)[source]

Send AtomicReadFile-Request per Clause 14.1.

Parameters:
Return type:

AtomicReadFileACK

Returns:

Decoded AtomicReadFileACK with file data.

Raises:
async atomic_write_file(address, file_identifier, access_method, timeout=None)[source]

Send AtomicWriteFile-Request per Clause 14.2.

Parameters:
Return type:

AtomicWriteFileACK

Returns:

Decoded AtomicWriteFileACK with actual start position.

Raises:
async create_object(address, object_type=None, object_identifier=None, timeout=None)[source]

Send CreateObject-Request per Clause 15.3.

Supply either object_type (server auto-assigns instance) or object_identifier (explicit type and instance).

Parameters:

  • address (BACnetAddress) – Target device address.

  • object_type (ObjectType | None (default: None)) – Object type for auto-assigned instance.

  • object_identifier (ObjectIdentifier | None (default: None)) – Explicit object identifier.

  • timeout (float | None (default: None)) – Optional caller-level timeout in seconds.

Return type:

ObjectIdentifier

Returns:

ObjectIdentifier of the created object.

Raises:
async delete_object(address, object_identifier, timeout=None)[source]

Send DeleteObject-Request per Clause 15.4.

Parameters:

  • address (BACnetAddress) – Target device address.

  • object_identifier (ObjectIdentifier) – Object to delete.

  • timeout (float | None (default: None)) – Optional caller-level timeout in seconds.

Raises:
Return type:

None

async add_list_element(address, object_identifier, property_identifier, list_of_elements, array_index=None, timeout=None)[source]

Send AddListElement-Request per Clause 15.1.

Parameters:

  • address (BACnetAddress) – Target device address.

  • object_identifier (ObjectIdentifier) – Object containing the list property.

  • property_identifier (PropertyIdentifier) – List property to modify.

  • list_of_elements (bytes) – Application-tagged encoded elements to add.

  • array_index (int | None (default: None)) – Optional array index.

  • timeout (float | None (default: None)) – Optional caller-level timeout in seconds.

Raises:
Return type:

None

async remove_list_element(address, object_identifier, property_identifier, list_of_elements, array_index=None, timeout=None)[source]

Send RemoveListElement-Request per Clause 15.2.

Parameters:

  • address (BACnetAddress) – Target device address.

  • object_identifier (ObjectIdentifier) – Object containing the list property.

  • property_identifier (PropertyIdentifier) – List property to modify.

  • list_of_elements (bytes) – Application-tagged encoded elements to remove.

  • array_index (int | None (default: None)) – Optional array index.

  • timeout (float | None (default: None)) – Optional caller-level timeout in seconds.

Raises:
Return type:

None

async who_has(object_identifier=None, object_name=None, low_limit=None, high_limit=None, destination=BACnetAddress(network=65535, mac_address=b''), timeout=3.0, expected_count=None)[source]

Discover objects via Who-Has broadcast per Clause 16.9.

Sends a Who-Has request and collects I-Have responses for the specified timeout duration. Supply either object_identifier or object_name.

Parameters:

  • object_identifier (str | tuple[str | ObjectType | int, int] | ObjectIdentifier | None (default: None)) – Object to search for by identifier (e.g. "ai,1" or ObjectIdentifier(...)).

  • object_name (str | None (default: None)) – Object to search for by name string.

  • low_limit (int | None (default: None)) – Optional lower bound of device instance range.

  • high_limit (int | None (default: None)) – Optional upper bound of device instance range.

  • destination (BACnetAddress (default: BACnetAddress(network=65535, mac_address=b''))) – Broadcast address (default: global broadcast).

  • timeout (float (default: 3.0)) – Seconds to wait for responses.

  • expected_count (int | None (default: None)) – When set, return early once this many responses have been collected instead of waiting for the full timeout.

Return type:

list[IHaveRequest]

Returns:

List of IHaveRequest responses received within the timeout.

Example:

# Search by object identifier
results = await client.who_has(object_identifier="ai,1")

# Search by object name
results = await client.who_has(object_name="Zone Temp")
async who_is_router_to_network(network=None, destination=None, timeout=3.0, expected_count=None)[source]

Discover routers and reachable networks.

Sends a Who-Is-Router-To-Network message and collects I-Am-Router-To-Network responses.

Parameters:

  • network (int | None (default: None)) – Optional specific network to query. If None, discovers all reachable networks.

  • destination (str | BACnetAddress | None (default: None)) – Target for the query. Accepts an IP string, a BACnetAddress, or None for local broadcast.

  • timeout (float (default: 3.0)) – Seconds to wait for responses.

  • expected_count (int | None (default: None)) – When set, return early once this many distinct routers have responded instead of waiting for the full timeout.

Return type:

list[RouterInfo]

Returns:

List of router information with address and accessible networks. Multiple responses from the same router are merged.

Example:

routers = await client.who_is_router_to_network(timeout=3.0)
for router in routers:
    print(f"Router at {router.address}: networks {router.networks}")
async confirmed_private_transfer(address, vendor_id, service_number, service_parameters=None, timeout=None)[source]

Send ConfirmedPrivateTransfer-Request per Clause 16.2.

Parameters:

  • address (BACnetAddress) – Target device address.

  • vendor_id (int) – Vendor identifier.

  • service_number (int) – Vendor-specific service number.

  • service_parameters (bytes | None (default: None)) – Optional vendor-specific data.

  • timeout (float | None (default: None)) – Optional caller-level timeout in seconds.

Return type:

ConfirmedPrivateTransferACK

Returns:

Decoded ConfirmedPrivateTransfer-ACK.

Raises:
unconfirmed_private_transfer(destination, vendor_id, service_number, service_parameters=None)[source]

Send UnconfirmedPrivateTransfer-Request per Clause 16.3.

This is an unconfirmed service (fire-and-forget).

Parameters:

  • destination (BACnetAddress) – Target device or broadcast address.

  • vendor_id (int) – Vendor identifier.

  • service_number (int) – Vendor-specific service number.

  • service_parameters (bytes | None (default: None)) – Optional vendor-specific data.

Return type:

None

async read_bdt(bbmd_address, timeout=5.0)[source]

Read the Broadcast Distribution Table from a remote BBMD.

Parameters:

  • bbmd_address (str | BACnetAddress) – Address of the BBMD to query (e.g. "192.168.1.1" or "192.168.1.1:47808").

  • timeout (float (default: 5.0)) – Seconds to wait for a response.

Return type:

list[BDTEntryInfo]

Returns:

List of BDT entries with address and mask information.

Raises:

  • RuntimeError – If transport is not available or device rejects the request (not a BBMD).

  • TimeoutError – If no response within timeout.

async read_fdt(bbmd_address, timeout=5.0)[source]

Read the Foreign Device Table from a remote BBMD.

Parameters:

  • bbmd_address (str | BACnetAddress) – Address of the BBMD to query (e.g. "192.168.1.1" or "192.168.1.1:47808").

  • timeout (float (default: 5.0)) – Seconds to wait for a response.

Return type:

list[FDTEntryInfo]

Returns:

List of FDT entries with address, TTL, and remaining time.

Raises:

  • RuntimeError – If transport is not available or device rejects the request (not a BBMD).

  • TimeoutError – If no response within timeout.

async write_bdt(bbmd_address, entries, timeout=5.0)[source]

Write a Broadcast Distribution Table to a remote BBMD.

Parameters:

  • bbmd_address (str | BACnetAddress) – Address of the BBMD to configure (e.g. "192.168.1.1" or "192.168.1.1:47808").

  • entries (list[BDTEntryInfo]) – BDT entries to write.

  • timeout (float (default: 5.0)) – Seconds to wait for a response.

Raises:

  • RuntimeError – If transport is not available or BBMD rejects the write (NAK).

  • TimeoutError – If no response within timeout.

Return type:

None

async acknowledge_alarm(address, acknowledging_process_identifier, event_object_identifier, event_state_acknowledged, time_stamp, acknowledgment_source, time_of_acknowledgment, timeout=None)[source]

Send AcknowledgeAlarm-Request per Clause 13.5.

Parameters:

  • address (BACnetAddress) – Target device address.

  • acknowledging_process_identifier (int) – Process ID of the acknowledger.

  • event_object_identifier (ObjectIdentifier) – Object whose event is being acknowledged.

  • event_state_acknowledged (EventState) – Event state being acknowledged.

  • time_stamp (BACnetTimeStamp) – Time stamp of the event being acknowledged.

  • acknowledgment_source (str) – Character string identifying the source.

  • time_of_acknowledgment (BACnetTimeStamp) – Time stamp of the acknowledgment.

  • timeout (float | None (default: None)) – Optional caller-level timeout in seconds.

Raises:
Return type:

None

async get_alarm_summary(address, timeout=None)[source]

Send GetAlarmSummary-Request per Clause 13.6.

Parameters:

  • address (BACnetAddress) – Target device address.

  • timeout (float | None (default: None)) – Optional caller-level timeout in seconds.

Return type:

GetAlarmSummaryACK

Returns:

Decoded GetAlarmSummaryACK with alarm summary entries.

Raises:
async get_enrollment_summary(address, acknowledgment_filter, event_state_filter=None, event_type_filter=None, priority_min=None, priority_max=None, notification_class_filter=None, timeout=None)[source]

Send GetEnrollmentSummary-Request per Clause 13.7.

Parameters:

  • address (BACnetAddress) – Target device address.

  • acknowledgment_filter (AcknowledgmentFilter) – Filter by acknowledgment state.

  • event_state_filter (EventState | None (default: None)) – Optional filter by event state.

  • event_type_filter (EventType | None (default: None)) – Optional filter by event type.

  • priority_min (int | None (default: None)) – Optional minimum priority (0–255).

  • priority_max (int | None (default: None)) – Optional maximum priority (0–255).

  • notification_class_filter (int | None (default: None)) – Optional notification class filter.

  • timeout (float | None (default: None)) – Optional caller-level timeout in seconds.

Return type:

GetEnrollmentSummaryACK

Returns:

Decoded GetEnrollmentSummaryACK with enrollment summaries.

Raises:
async get_event_information(address, last_received_object_identifier=None, timeout=None)[source]

Send GetEventInformation-Request per Clause 13.12.

Parameters:

  • address (BACnetAddress) – Target device address.

  • last_received_object_identifier (ObjectIdentifier | None (default: None)) – Optional object identifier for pagination. Pass the last object identifier from a previous response to continue fetching when more_events is True.

  • timeout (float | None (default: None)) – Optional caller-level timeout in seconds.

Return type:

GetEventInformationACK

Returns:

Decoded GetEventInformationACK with event summaries.

Raises:
async confirmed_event_notification(address, notification, timeout=None)[source]

Send ConfirmedEventNotification-Request per Clause 13.8.

Parameters:

  • address (BACnetAddress) – Target device address.

  • notification (EventNotificationRequest) – Pre-built EventNotificationRequest with all event notification parameters.

  • timeout (float | None (default: None)) – Optional caller-level timeout in seconds.

Raises:
Return type:

None

async delete_fdt_entry(bbmd_address, entry_address, timeout=5.0)[source]

Delete a Foreign Device Table entry on a remote BBMD.

Parameters:

  • bbmd_address (str | BACnetAddress) – Address of the BBMD (e.g. "192.168.1.1" or "192.168.1.1:47808").

  • entry_address (str) – Address of the FDT entry to delete (e.g. "10.0.0.50:47808").

  • timeout (float (default: 5.0)) – Seconds to wait for a response.

Raises:

  • RuntimeError – If transport is not available or BBMD rejects the delete (NAK).

  • TimeoutError – If no response within timeout.

Return type:

None

async send_confirmed_text_message(address, source_device, message, message_priority=MessagePriority.NORMAL, message_class_numeric=None, message_class_character=None, timeout=None)[source]

Send ConfirmedTextMessage-Request per Clause 16.5.

Parameters:

  • address (BACnetAddress) – Target device address.

  • source_device (ObjectIdentifier) – Object identifier of the sending device.

  • message (str) – Text message content.

  • message_priority (MessagePriority (default: <MessagePriority.NORMAL: 0>)) – Message priority (NORMAL or URGENT).

  • message_class_numeric (int | None (default: None)) – Optional numeric message class.

  • message_class_character (str | None (default: None)) – Optional character message class.

  • timeout (float | None (default: None)) – Optional caller-level timeout in seconds.

Raises:
Return type:

None

send_unconfirmed_text_message(destination, source_device, message, message_priority=MessagePriority.NORMAL, message_class_numeric=None, message_class_character=None)[source]

Send UnconfirmedTextMessage-Request per Clause 16.6.

This is an unconfirmed service (fire-and-forget).

Parameters:

  • destination (BACnetAddress) – Target device or broadcast address.

  • source_device (ObjectIdentifier) – Object identifier of the sending device.

  • message (str) – Text message content.

  • message_priority (MessagePriority (default: <MessagePriority.NORMAL: 0>)) – Message priority (NORMAL or URGENT).

  • message_class_numeric (int | None (default: None)) – Optional numeric message class.

  • message_class_character (str | None (default: None)) – Optional character message class.

Return type:

None

write_group(destination, group_number, write_priority, change_list)[source]

Send WriteGroup-Request per Clause 15.11.

This is an unconfirmed service (fire-and-forget).

Parameters:

  • destination (BACnetAddress) – Target device or broadcast address.

  • group_number (int) – Channel group number (Unsigned32).

  • write_priority (int) – Write priority (1-16).

  • change_list (list[GroupChannelValue]) – List of channel values to write.

Return type:

None

who_am_i(destination, vendor_id, model_name, serial_number)[source]

Send Who-Am-I-Request per Clause 16.11.

This is an unconfirmed service (fire-and-forget). Sent by unconfigured devices to request identity assignment.

Parameters:

  • destination (BACnetAddress) – Target address (typically global broadcast).

  • vendor_id (int) – Device vendor identifier.

  • model_name (str) – Device model name.

  • serial_number (str) – Device serial number.

Return type:

None

you_are(destination, device_identifier, device_mac_address, device_network_number=None)[source]

Send You-Are-Request per Clause 16.11.

This is an unconfirmed service (fire-and-forget). Sent by a supervisor to assign identity to an unconfigured device.

Parameters:

  • destination (BACnetAddress) – Target device address.

  • device_identifier (ObjectIdentifier) – Assigned device object identifier.

  • device_mac_address (bytes) – MAC address of the target device.

  • device_network_number (int | None (default: None)) – Optional network number.

Return type:

None

async discover_unconfigured(destination=BACnetAddress(network=65535, mac_address=b''), timeout=5.0)[source]

Listen for unconfigured devices broadcasting Who-Am-I.

Registers a temporary handler for Who-Am-I messages and collects responses for the specified duration.

Parameters:

  • destination (BACnetAddress (default: BACnetAddress(network=65535, mac_address=b''))) – Not used for listening, included for API consistency.

  • timeout (float (default: 5.0)) – Seconds to listen for Who-Am-I messages.

Return type:

list[UnconfiguredDevice]

Returns:

List of UnconfiguredDevice discovered.

async vt_open(address, vt_class, local_vt_session_identifier, timeout=None)[source]

Send VT-Open-Request per Clause 17.1.

Parameters:

  • address (BACnetAddress) – Target device address.

  • vt_class (VTClass) – Virtual terminal class to open.

  • local_vt_session_identifier (int) – Local session ID (0-255).

  • timeout (float | None (default: None)) – Optional caller-level timeout in seconds.

Return type:

VTOpenACK

Returns:

Decoded VTOpenACK with remote session ID.

Raises:
async vt_close(address, session_identifiers, timeout=None)[source]

Send VT-Close-Request per Clause 17.2.

Parameters:

  • address (BACnetAddress) – Target device address.

  • session_identifiers (list[int]) – List of remote VT session IDs to close.

  • timeout (float | None (default: None)) – Optional caller-level timeout in seconds.

Raises:
Return type:

None

async vt_data(address, vt_session_identifier, vt_new_data, vt_data_flag=False, timeout=None)[source]

Send VT-Data-Request per Clause 17.3.

Parameters:

  • address (BACnetAddress) – Target device address.

  • vt_session_identifier (int) – Remote VT session ID.

  • vt_new_data (bytes) – Data to send to the virtual terminal.

  • vt_data_flag (bool (default: False)) – True if this is the last data segment.

  • timeout (float | None (default: None)) – Optional caller-level timeout in seconds.

Return type:

VTDataACK

Returns:

Decoded VTDataACK.

Raises:
async query_audit_log(address, audit_log, query_parameters, start_at_sequence_number=None, requested_count=100, timeout=None)[source]

Send AuditLogQuery-Request per Clause 13.19.

Parameters:

  • address (BACnetAddress) – Target device address.

  • audit_log (ObjectIdentifier) – Audit Log object identifier.

  • query_parameters (AuditQueryByTarget | AuditQueryBySource) – Query by target or source.

  • start_at_sequence_number (int | None (default: None)) – Optional starting sequence number.

  • requested_count (int (default: 100)) – Maximum number of records to return.

  • timeout (float | None (default: None)) – Optional caller-level timeout in seconds.

Return type:

AuditLogQueryACK

Returns:

Decoded AuditLogQueryACK.

Raises:

BACnetError – On Error-PDU response.

async send_audit_notification(address, notifications, confirmed=True, timeout=None)[source]

Send audit notification(s) per Clause 13.20/13.21.

Parameters:

  • address (BACnetAddress) – Target device address.

  • notifications (list[BACnetAuditNotification]) – List of audit notifications to send.

  • confirmed (bool (default: True)) – True for confirmed, False for unconfirmed.

  • timeout (float | None (default: None)) – Optional caller-level timeout in seconds.

Raises:

BACnetError – On Error-PDU response (confirmed only).

Return type:

None

async backup_device(address, password=None, poll_interval=1.0, timeout=None)[source]

Perform a full backup of a remote BACnet device (Clause 19.1).

Executes the backup procedure: 1. ReinitializeDevice START_BACKUP 2. Poll BACKUP_AND_RESTORE_STATE until ready 3. Read CONFIGURATION_FILES list 4. Download each file via AtomicReadFile 5. ReinitializeDevice END_BACKUP

Parameters:

  • address (BACnetAddress) – Target device address.

  • password (str | None (default: None)) – Optional password for ReinitializeDevice.

  • poll_interval (float (default: 1.0)) – Seconds between state polls.

  • timeout (float | None (default: None)) – Optional overall timeout in seconds.

Return type:

BackupData

Returns:

BackupData with downloaded configuration files.

Raises:
async restore_device(address, backup_data, password=None, poll_interval=1.0, timeout=None)[source]

Perform a full restore of a remote BACnet device (Clause 19.1).

Executes the restore procedure: 1. ReinitializeDevice START_RESTORE 2. Poll BACKUP_AND_RESTORE_STATE until ready 3. Upload each config file via AtomicWriteFile 4. ReinitializeDevice END_RESTORE

Parameters:

  • address (BACnetAddress) – Target device address.

  • backup_data (BackupData) – BackupData from a previous backup.

  • password (str | None (default: None)) – Optional password for ReinitializeDevice.

  • poll_interval (float (default: 1.0)) – Seconds between state polls.

  • timeout (float | None (default: None)) – Optional overall timeout in seconds.

Raises:
Return type:

None