repository·master·Indexed 43 days ago
https://github.com/joelbender/bacpypesA Python-based implementation of the BACnet application and network layers. It enables developers to build BACnet-compliant daemons, automation scripts, and graphical user interfaces (GUIs). The library supports UDP communication, including unicast and broadcast messages, and provides tools for device discovery and network analysis.
analysis module provides tools for inspecting and decoding BACnet traffic captured in PCAP files. It includes functions for decoding various network layers (Ethernet, VLAN, IP, UDP) and high-level functions for processing entire files or individual packet strings.An IO Control Block (IOCB) is a data structure used to store parameters for a specific processing task and to retrieve the results once that task is complete.
In the BACpypes model:
IOController) acts as the executor that performs the processing defined by the IOCB.This pattern is modeled after the VAX/VMS IO subsystem API, allowing for asynchronous operations where an application can be notified of completion via event flags, semaphores, or callback functions rather than waiting synchronously for the operation to finish.
# Conceptual model of IOCB usage:
# result = some_function(arg1, arg2, kwarg1=1)
#
# 1. IOCB stores: arg1, arg2, kwarg1
# 2. IOController (some_function) executes the task
# 3. IOCB stores: result (or error value if processing fails)A Protocol Data Unit (PDU) is a collection of information passed between two entities. In the comm module, a PDU is composed of two main parts:
The PDU class combines these two components into a single object. While the comm module provides these abstractions, the classes themselves are not strictly limited to the BACnet protocol.
BACpypes organizes PDUs into several functional hierarchies:
These classes represent the fundamental types of PDUs:
ConfirmedRequestPDUUnconfirmedRequestPDUSimpleAckPDUComplexAckPDUSegmentAckPDUErrorPDURejectPDUSequence classes combine APCI with specific PDU types, often used for higher-level protocol implementations:
APCISequence(APCI, Sequence)ConfirmedRequestSequence(APCISequence, ConfirmedRequestPDU)ComplexAckSequence(APCISequence, ComplexAckPDU)UnconfirmedRequestSequence(APCISequence, UnconfirmedRequestPDU)ErrorSequence(APCISequence, ErrorPDU)In BACpypes v0.15.0+, the Application class no longer requires localDevice or localAddress parameters.
Applications that omit these parameters function as client-only applications. These are useful for:
Note: Client-only applications can only initiate confirmed or unconfirmed services that do not require local device/address information. They cannot respond to incoming requests like Who-Is.
BACpypes uses DeviceInfo objects to store metadata about remote devices, such as their device identifier, network address, maximum APDU length, and segmentation support. This information is critical for constructing confirmed services and performing device-address binding.
To manage this data, use DeviceInfoCache. An Application uses a cache to store information gathered from the network (e.g., via IAmRequest) or from a database. You can extend DeviceInfoCache to implement custom persistence logic, such as updating a database when update_device_info is called or implementing custom expiration logic in release_device_info.
Capability module, functions are ordered based on the _zIndex attribute. When using Collector.capability_functions(fn), the generator yields functions in the order determined by this attribute.The ConnectionState object tracks the lifecycle of a BSLL connection. The accessState attribute transitions through the following values:
NOT_AUTHENTICATED: No authentication has been attempted.REQUESTED: An access request has been sent to the server (Client side).CHALLENGED: An access challenge has been sent to the client (Server side).AUTHENTICATED: Authentication was successful.The bacpypes.capability module provides a mechanism to mix together classes that offer separate or overlapping functionality. It uses a component-based architecture where functionality is added to a base class via multiple inheritance.
Key classes include:
Capability: The base class for defining specific pieces of functionality (e.g., a specific data transformation).Collector: A base class used to aggregate and execute functions provided by mixed-in Capability classes.By mixing a Collector with multiple Capability classes, you can create a pipeline where the Collector iterates through all registered functions of a specific type (retrieved via capability_functions()) and applies them to a value.
from bacpypes.capability import Capability, CollectorThe npdu module defines several service request classes used for routing and network management. Most of these classes implement encode(npdu) and decode(npdu) methods, accepting an NPDU buffer as a parameter.
WhoIsRouterToNetwork(NPCI): Used to find the router for a specific network or to allow routers to update routing tables.IAmRouterToNetwork(NPCI): Response to WhoIsRouterToNetwork; contains network numbers the router provides access to.ICouldBeRouterToNetwork(NPCI): Response to WhoIsRouterToNetwork; contains network numbers a half-router could provide access to via a PTP connection (connection not yet established).RejectMessageToNetwork(NPCI): Sent when a network layer message is rejected due to an error.RouterBusyToNetwork(NPCI): Sent by a router to temporarily stop messages to specific destination networks.RouterAvailableToNetwork(NPCI): Sent by a router to enable or re-enable messages to specific destination networks.InitializeRoutingTable(NPCI): Used to initialize a router's routing table or retrieve the current table.InitializeRoutingTableAck(NPCI): Indicates the routing table has changed or been initialized.EstablishConnectionToNetwork(NPCI): Tells a half-router to establish a PTP connection to a network.DisconnectConnectionToNetwork(NPCI): Tells a half-router to close a PTP connection to a network.BACpypes uses a layered approach for Change of Value (COV) services:
ChangeOfValueServices: The central manager that handles the lifecycle of subscriptions and the dispatching of notifications.Subscription: Represents an active subscription with a specific lifetime. It acts as a OneShotTask that automatically cancels itself when its lifetime expires.COVDetection: A DetectionAlgorithm that monitors object properties. When a change is detected, it calls send_cov_notifications() to alert all associated Subscription objects.ActiveCOVSubscriptions: A Property added to a local device object. When read, it returns a list of COVSubscription objects, allowing the device to report its current COV state.