BACstack is a low-level Elixir implementation for the ASHRAE standard 135, BACnet - Building Automation and Controller network. This implementation supports ASHRAE 135-xxxx and BACnet/IPv4. Support for other transport layers (such as BACnet/SC, BACnet/MSTP) can be straight forward added on top of it.
As this is a low-level implementation, users of this library are required to do the heavy-lifting of the BACnet stack, such as automatically replying to Who-Is services, applying hard application timeout constraints, synchronizing time, etc.
While v0.0.1 has been released to Hex to provide a minimal BACnet client featureset, it is recommended to install it through GitHub (you can also pin it to a commit hash). New changes, bugfixes and features are not released to Hex until bacstack has reached a more stable and complete featureset.
The package can be installed by adding bacstack to your list of dependencies in mix.exs:
def deps do
[
{:bacstack, github: "bacnet-ex/bacstack"}
]
endThe documentation can be found at https://bacnet-ex.github.io/bacstack/.
First start a transport (specify callback), start Segmentator, start SegmentsStore and finally start Client,
specifying all three previously started processes.
In the following example, we will use registered processes for ease of use. You can also use :via tuple for
an alternative to locally registered names (or simply no registration at all).
However since we need to "link" the processes, names make it a lot easier.
Though the transport module does allow to use a function or MFA callback instead,
so "linking" can be implementation by the user as desired.
We use the IPv4 transport and it will automatically determine a network interface to use. You can also specify the network interface directly, if you want to or the wrong interface is selected. Refer to the documentation for more information.
alias BACnet.Stack.Client
alias BACnet.Stack.Segmentator
alias BACnet.Stack.SegmentsStore
alias BACnet.Stack.Transport.IPv4Transport
IPv4Transport.open(Client, name: IPv4Transport)
Segmentator.start_link(name: Segmentator)
SegmentsStore.start_link(name: SegmentsStore)
Client.start_link(
name: Client,
segmentator: Segmentator,
segments_store: SegmentsStore,
transport: IPv4Transport
)In a more production environment these processes should be started under a supervisor and also where possible, you should specify the supervisor for the modules to use (i.e. IPv4 transport).
You can now use the Client module to interact with the BACnet network (i.e. send Who-Is messages).
You can also receive BACnet traffic by specifying a notification receiver when starting Client.
See also the ClientHelper module for functions orientated around helping you to send BACnet service requests.
If you need to interact with a remote BACnet network, you may want to register yourself as a Foreign Device.
For that case, you can start an additional process ForeignDevice and specify the BBMD.
Please note that the Client needs to be started on the correct network interface where the BBMD is reachable.
alias BACnet.Stack.ForeignDevice
ForeignDevice.start_link(bbmd: {bbmd_ip, 0xBAC0}, client: Client)This library uses the library Codepagex to implement character set conversion. By default, Codepagex only generates conversion code for fast conversion algorithms to and from UTF-8 (such as ISO-8859-1).
If you need to use other character sets, such as CP932 (JIS-X-0208) or CP850 (DBCS), you will have to configure Codepagex accordingly. Refer to their documentation for the necessary steps.
When using this library, there are some functions that take or return DateTime structs.
Inside the library, there is a default timezone that will be used, when you don't particularily set/override the timezone.
The default timezone is an application environment configuration that is used across the library and can be used
to set a different timezone than the default Etc/UTC. Where applicable,
you can still override the default timezone locally (i.e. BACnetDateTime.to_datetime/3).
config :bacstack, :default_timezone, "Etc/UTC"Please note, for timezones other than UTC, you still need to set a timezone database for Elixir to work with.
For example, with the library Tzdata it's just a matter of configuration:
config :elixir, :time_zone_database, Tzdata.TimeZoneDatabaseSome parts of this library can be extended at compile-time to provide additional value. Let's explore them.
The known property identifiers can be extended at compile-time by the library user. This can be done to add new properties or even proprietary property identifiers.
Simply configure the key :additional_property_identifiers of the application :bacstack
to be a keyword or map and use the name as key and the integer protocol value as value.
For example:
config :bacstack, :additional_property_identifiers, loop_enable: 523, loop_mode: 524For each object the available properties can be extended at compile-time by the library user. This may be done to add new properties or even proprietary properties to an object type.
Configure the key :objects_additional_properties of the application :bacstack and
supply proper quoted expression (Elixir AST) to a keyword list or map,
with the object type as key.
Please note that the properties must be known (either already supplied by the library
or added by the library user using additional_property_identifiers).
For example:
config :bacstack, :objects_additional_properties,
loop:
(quote do
field(:loop_enable, boolean(), encode_as: :enumerated)
field(:loop_mode, :bacnet_loop | :plc_loop,
bac_type: {:in_list, [:bacnet_loop, :plc_loop]},
annotation: [
encoder: &{:enumerated, if(&1 == :plc_loop, do: 1, else: 0)},
decoder: &if(&1.value == 1, do: :plc_loop, else: :bacnet_loop)
]
)
end)See the documentation to ObjectsMacro.bac_object/2 for more information and the allowed/expected expression.
The known object types can be extended at compile-time by the library. That does not automatically implement the new object types, however makes it possible to do so. It can be done to provide forward compatibility for new revisions at early stages.
Simply configure the key :additional_object_type of the application :bacstack
to be a keyword or map and use the name as key and the integer protocol value as value.
You'll also want to extend object types supported through :additional_object_types_supported.
The struct BACnet.Protocol.Device.ObjectTypesSupported is automatically adjusted and up-to-date at compile time.
Both confirmed and unconfirmed service choices known can be extended at compile-time by the library user. That does not mean though, that the services are implemented. It can be done though, to provide forward compatibility for new revisions at early stages.
Simply configure the key :additional_confirmed_service_choice and/or :additional_unconfirmed_service_choice
of the application :bacstack to be a keyword or map and use the name as key and the integer protocol value as value.
You'll also want to extend services supported through :additional_services_supported.
The struct BACnet.Protocol.Device.ServicesSupported is automatically adjusted and up-to-date at compile time.
Abort Reason, Error Class, Error Code and Reject Reason can be extended at compile-time by the library user. This allows to provide forward compatibility for new revisions at early stages.
Simply configure the key :additional_abort_reason, :additional_error_class,
:additional_error_code and/or :additional_reject_reason of the application :bacstack
to be a keyword or map and use the name as key and the integer protocol value as value.
| Object Type | Representation | Execute | Intrinsic Reporting |
|---|---|---|---|
| Accumulator | 135-2012 | - | - |
| Analog Input | 135-2012 | - | - |
| Analog Output | 135-2012 | - | - |
| Analog Value | 135-2012 | - | - |
| Averaging | 135-2012 | - | - |
| Binary Input | 135-2012 | - | - |
| Binary Output | 135-2012 | - | - |
| Binary Value | 135-2012 | - | - |
| Calendar | 135-2012 | - | - |
| Command | 135-2012 | - | - |
| Device | 135-2012 | - | - |
| Event Enrollment | 135-2012 | - | - |
| File | 135-2012 | - | - |
| Group | 135-2012 | - | - |
| Life Safety Point | N/A | - | - |
| Life Safety Zone | N/A | - | - |
| Loop | 135-2012 | - | - |
| Multistate Input | 135-2012 | - | - |
| Multistate Output | 135-2012 | - | - |
| Multistate Value | 135-2012 | - | - |
| Notification Class | 135-2012 | - | - |
| Program | 135-2012 | - | - |
| Pulse Converter | 135-2012 | - | - |
| Schedule | 135-2012 | - | - |
| Event Log | 135-2012 | - | - |
| Trend Log | 135-2012 | - | - |
| Trend Log Multiple | 135-2012 | - | - |
| Load Control | - | - | - |
| Access Point | N/A | - | - |
| Access Zone | N/A | - | - |
| Access User | N/A | - | - |
| Access Rights | N/A | - | - |
| Access Credential | N/A | - | - |
| Credential Data Input | N/A | - | - |
| Structured View | 135-2012 | - | - |
| Character String Value | 135-2012 | - | - |
| DateTime Value | 135-2012 | - | - |
| Large Analog Value | 135-2012 | - | - |
| Bitstring | 135-2012 | - | - |
| Octet String Value | 135-2012 | - | - |
| Time Value | 135-2012 | - | - |
| Integer Value | 135-2012 | - | - |
| Positive Integer Value | 135-2012 | - | - |
| Date Value | 135-2012 | - | - |
| DateTime Pattern Value | 135-2012 | - | - |
| Time Pattern Value | 135-2012 | - | - |
| Date Pattern Value | 135-2012 | - | - |
| Network Security | N/A | - | - |
| Global Group | - | - | - |
| Notification Forwarder | - | - | - |
| Alert Enrollment | - | - | - |
| Channel | - | - | - |
| Lighting Output | - | - | - |
| Service Name | Receive | Send | ACK (Pos/Neg) |
|---|---|---|---|
| Confirmed COV | x | x | Simple/Error |
| Unconfirmed COV | x | x | |
| Confirmed Event | x | x | Simple/Error |
| Unconfirmed Event | x | x | |
| Acknowledge Alarm | x | x | Simple/Error |
| Get Alarm Summary | x | x | x/Error |
| Get Enrollment Summary | x | x | x/Error |
| Get Event Information | x | x | x/Error |
| Life Safety Operation | x | x | Simple/Error |
| Subscribe COV | x | x | Simple/Error |
| Subscribe COV Property | x | x | Simple/Error |
| Atomic Read File | x | x | x/Error |
| Atomic Write File | x | x | x/Error |
| Add List Element | x | x | Simple/x |
| Remove List Element | x | x | Simple/x |
| Create Object | x | x | x/x |
| Delete Object | x | x | Simple/x |
| Read Property | x | x | x/Error |
| Read Property Multiple | x | x | x/Error |
| Read Range | x | x | x/Error |
| Write Property | x | x | Simple/Error |
| Write Property Multiple | x | x | Simple/x |
| Write Group | x | x | |
| Device Communication Control | x | x | Simple/Error |
| Confirmed Private Transfer | x | x | x/x |
| Unconfirmed Private Transfer | x | x | |
| Reinitialize Device | x | x | Simple/Error |
| Confirmed Text Message | x | x | Simple/Error |
| Unconfirmed Text Message | x | x | |
| Time Synchronization | x | x | |
| UTC Time Synchronization | x | x | |
| Who-Has | x | x | |
| I-Have | x | x | |
| Who-Is | x | x | |
| I-Am | x | x | |
| VT Open | N/A | N/A | |
| VT Close | N/A | N/A | |
| VT Data | N/A | N/A |
| Event Algorithm | Implemented |
|---|---|
| Buffer Ready | 135-2012 |
| Change Of Bitstring | 135-2012 |
| Change Of Character String | 135-2012 |
| Change Of Life Safety | 135-2012 |
| Change Of State | 135-2012 |
| Change Of Status Flags | 135-2012 |
| Change Of Value | 135-2012 |
| Command Failure | 135-2012 |
| Complex Event Type | N/A |
| Double Out Of Range | 135-2012 |
| Extended | N/A |
| Floating Limit | 135-2012 |
| Out Of Range | 135-2012 |
| Signed Out Of Range | 135-2012 |
| Unsigned Out Of Range | 135-2012 |
| Unsigned Range | 135-2012 |
| Fault Algorithm | Implemented |
|---|---|
| Fault Character String | 135-2012 |
| Fault Extended | N/A |
| Fault Life Safety | 135-2012 |
| Fault State | 135-2012 |
| Fault Status Flags | 135-2012 |