Documentation
¶
Overview ¶
Package bacnet provides a Go implementation of the BACnet/IP protocol stack for building automation and control systems.
BACnet (Building Automation and Control Networks) is a data communication protocol for building automation and control systems. It is designed to facilitate communication between different devices and systems in buildings, such as HVAC, lighting, security, and fire safety systems.
This package implements the following BACnet services:
Confirmed Services: - ReadProperty (12) - ReadPropertyMultiple (14) - WriteProperty (15) - WritePropertyMultiple (16)
Unconfirmed Services: - IAm (0) - WhoIs (8)
Key Features: - Full BACnet/IP protocol support - Device discovery (WhoIs/IAm) - Object access (ReadProperty, WriteProperty) - Transaction management with TSM (Transaction State Machine) - Thread-safe design with connection pooling - Support for multiple network interfaces
Data Collection Flow: The typical data collection process involves the following steps:
- Client Initialization: Create a BACnet client with appropriate network configuration (IP address, subnet, port).
- Device Discovery: Use WhoIs service to discover all BACnet devices on the network. This sends a broadcast message to which all devices respond with their device ID and network address.
- Object Discovery: Once devices are discovered, use Objects() method to retrieve all objects from a specific device. This includes Analog Inputs, Binary Inputs, Analog Outputs, Binary Outputs, and other object types.
- Data Reading: Use ReadProperty() to read individual property values or ReadMultiProperty() to read multiple properties in a single request.
- Data Writing: Use WriteProperty() or WriteMultiProperty() to write values to device objects.
6. Cleanup: Always close the client when done to release resources.
Example Usage:
// Create client
client, err := bacnet.NewClient(&bacnet.ClientBuilder{
Ip: "192.168.1.100",
SubnetCIDR: 24,
Port: 47808,
})
if err != nil {
log.Fatal(err)
}
defer client.Close()
// Start message loop
go client.ClientRun()
// Discover devices
devices, err := client.WhoIs(&bacnet.WhoIsOpts{
Low: 0,
High: 4194304,
})
// Read property from device
result, err := client.ReadProperty(device, btypes.PropertyData{
Object: btypes.Object{
ID: btypes.ObjectID{
Type: btypes.AnalogInput,
Instance: 1,
},
Properties: []btypes.Property{
{Type: btypes.PropPresentValue},
},
},
})
For more detailed information, see the README.md file.
中文说明: BACnet(楼宇自动化和控制网络)是用于楼宇自动化和控制系统的数据通信协议。 它旨在促进楼宇中不同设备和系统之间的通信,如暖通空调(HVAC)、照明、安全和消防系统。
数据采集流程: 典型的数据采集过程包括以下步骤:
1. 客户端初始化:使用适当的网络配置创建BACnet客户端(IP地址、子网、端口)。
- 设备发现:使用WhoIs服务发现网络上的所有BACnet设备。这会发送广播消息, 所有设备都会响应其设备ID和网络地址。
- 对象发现:发现设备后,使用Objects()方法从特定设备检索所有对象。 包括模拟输入、二进制输入、模拟输出、二进制输出等对象类型。
- 数据读取:使用ReadProperty()读取单个属性值,或使用ReadMultiProperty() 在单个请求中读取多个属性。
5. 数据写入:使用WriteProperty()或WriteMultiProperty()向设备对象写入值。
6. 清理:完成操作后始终关闭客户端以释放资源。
参考文档: - ANSI/ASHRAE Standard 135-2020 - http://www.bacnet.org/
Index ¶
Constants ¶
const ArrayAll = 0xFFFFFFFF
ArrayAll is used when reading/writing to a property to read/write the entire array
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Client ¶
type Client interface {
io.Closer
// IsRunning returns true if the client message loop is running.
// IsRunning 返回客户端消息循环是否正在运行。
IsRunning() bool
// ClientRun starts the client message loop. This should be called in a goroutine.
// ClientRun 启动客户端消息循环,应在 goroutine 中调用。
ClientRun()
// WhoIs discovers BACnet devices on the network within the specified device ID range.
// It sends a broadcast WhoIs request and collects IAm responses from devices.
// Returns a list of discovered devices.
// WhoIs 发现网络上指定设备ID范围内的BACnet设备。
// 发送广播 WhoIs 请求并收集设备的 IAm 响应。
// 返回发现的设备列表。
WhoIs(wh *WhoIsOpts) ([]btypes.Device, error)
// WhatIsNetworkNumber determines the network number of the local BACnet network.
// Returns a list of addresses that responded to the What-Is-Network-Number request.
// WhatIsNetworkNumber 确定本地BACnet网络的网络号。
// 返回响应 What-Is-Network-Number 请求的地址列表。
WhatIsNetworkNumber() []*btypes.Address
// IAm sends an IAm response to the specified destination.
// This is typically used to respond to WhoIs requests from other devices.
// IAm 向指定目标发送 IAm 响应。
// 通常用于响应其他设备的 WhoIs 请求。
IAm(dest btypes.Address, iam btypes.IAm) error
// WhoIsRouterToNetwork discovers routers on the BACnet network.
// Returns a list of router addresses.
// WhoIsRouterToNetwork 发现BACnet网络上的路由器。
// 返回路由器地址列表。
WhoIsRouterToNetwork() (resp *[]btypes.Address)
// Objects retrieves all objects from a BACnet device.
// This includes AnalogInput, AnalogOutput, BinaryInput, BinaryOutput, and other object types.
// Returns a Device structure containing all discovered objects.
// Objects 从BACnet设备检索所有对象。
// 包括模拟输入、模拟输出、二进制输入、二进制输出等对象类型。
// 返回包含所有发现对象的 Device 结构。
Objects(dev btypes.Device) (btypes.Device, error)
// ReadProperty reads a single property from a BACnet device object.
// Returns the PropertyData containing the read property value.
// ReadProperty 从BACnet设备对象读取单个属性。
// 返回包含读取属性值的 PropertyData。
ReadProperty(dest btypes.Device, rp btypes.PropertyData) (btypes.PropertyData, error)
// ReadMultiProperty reads multiple properties from multiple objects in a single request.
// This is more efficient than multiple ReadProperty calls.
// Returns the MultiplePropertyData containing all read property values.
// ReadMultiProperty 在单个请求中从多个对象读取多个属性。
// 这比多次调用 ReadProperty 更高效。
// 返回包含所有读取属性值的 MultiplePropertyData。
ReadMultiProperty(dev btypes.Device, rp btypes.MultiplePropertyData) (btypes.MultiplePropertyData, error)
// ReadPropertyWithTimeout reads a single property with a specified timeout.
// This allows for more granular timeout control than the default timeout.
// ReadPropertyWithTimeout 使用指定超时读取单个属性。
// 允许比默认超时更精细的超时控制。
ReadPropertyWithTimeout(dest btypes.Device, rp btypes.PropertyData, timeout time.Duration) (btypes.PropertyData, error)
// ReadMultiPropertyWithTimeout reads multiple properties with a specified timeout.
// ReadMultiPropertyWithTimeout 使用指定超时读取多个属性。
ReadMultiPropertyWithTimeout(dev btypes.Device, rp btypes.MultiplePropertyData, timeout time.Duration) (btypes.MultiplePropertyData, error)
// WriteProperty writes a single property to a BACnet device object.
// Returns an error if the write operation fails.
// WriteProperty 向BACnet设备对象写入单个属性。
// 如果写入操作失败返回错误。
WriteProperty(dest btypes.Device, wp btypes.PropertyData) error
// WriteMultiProperty writes multiple properties to multiple objects in a single request.
// This is more efficient than multiple WriteProperty calls.
// WriteMultiProperty 在单个请求中向多个对象写入多个属性。
// 这比多次调用 WriteProperty 更高效。
WriteMultiProperty(dev btypes.Device, wp btypes.MultiplePropertyData) error
}
Client defines the interface for BACnet client operations. It provides methods for device discovery, object access, and network management. All methods are thread-safe and can be called concurrently from multiple goroutines.
中文说明:Client 定义了 BACnet 客户端操作的接口。 它提供设备发现、对象访问和网络管理的方法。 所有方法都是线程安全的,可以从多个 goroutine 并发调用。
func NewClient ¶
func NewClient(cb *ClientBuilder) (Client, error)
NewClient creates a new BACnet client with the provided configuration. It validates the configuration, creates the data link layer, initializes the Transaction State Machine (TSM), and sets up the unconfirmed transaction manager (UTSM).
Parameters:
cb - ClientBuilder containing the client configuration
Returns:
A new Client instance and any error encountered during initialization.
中文说明:NewClient 使用提供的配置创建新的 BACnet 客户端。 它验证配置,创建数据链路层,初始化事务状态机(TSM), 并设置非确认事务管理器(UTSM)。
参数:
cb - 包含客户端配置的 ClientBuilder
返回:
新的 Client 实例和初始化期间遇到的任何错误。
type ClientBuilder ¶
type ClientBuilder struct {
DataLink datalink.DataLink // Custom data link implementation (optional)
Interface string // Network interface name (e.g., "eth0")
Ip string // IP address to bind to
Port int // BACnet port (default: 47808)
SubnetCIDR int // Subnet CIDR (e.g., 24 for /24)
MaxPDU uint16 // Maximum PDU size (default: 1476)
}
ClientBuilder is used to configure and create a new BACnet client. All fields are optional with sensible defaults.
中文说明:ClientBuilder 用于配置和创建新的 BACnet 客户端。 所有字段都是可选的,有合理的默认值。
type SetBroadcastType ¶
type SetBroadcastType struct {
Set bool // Whether to override the default behavior
BacFunc btypes.BacFunc // The function type to set
}
SetBroadcastType is used to override the BVLC header function type. This allows forcing a specific broadcast/unicast behavior.
中文说明:SetBroadcastType 用于覆盖 BVLC 头部函数类型。 允许强制特定的广播/单播行为。
type WhoIsOpts ¶
type WhoIsOpts struct {
Low int `json:"low"` // Lower bound of device ID range (0 to 4194304)
High int `json:"high"` // Upper bound of device ID range
GlobalBroadcast bool `json:"global_broadcast"` // Use global broadcast (0xFFFF)
NetworkNumber uint16 `json:"network_number"` // Target network number
Destination *btypes.Address `json:"-"` // Specific destination address (optional)
}
WhoIsOpts contains options for the WhoIs device discovery request.
中文说明:WhoIsOpts 包含 WhoIs 设备发现请求的选项。