# BACstack
BACstack is a low-level Elixir implementation for the ASHRAE standard 135, BACnet - Building Automation and Controller network.
This implementation supports ASHRAE 135-xxxx<!-- TODO --> 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.
<!--If you're looking for a high level Elixir abstraction on top of this library, check out [BACnex].
BACnex is a high level abstraction on top of this library, that offers the high level features of a regular BACnet stack.-->
## Installation
While v0.0.1 has been released to [Hex](https://hex.pm/packages/bacstack) 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`:
```elixir
def deps do
[
{:bacstack, github: "bacnet-ex/bacstack"}
]
end
```
The documentation can be found at <https://bacnet-ex.github.io/bacstack/>.
<!--
If [available in Hex](https://hex.pm/docs/publish), the package can be installed
by adding `bacstack` to your list of dependencies in `mix.exs`:
```elixir
def deps do
[
{:bacstack, "~> 0.1.0"}
]
end
```
Documentation can be generated with [ExDoc](https://github.com/elixir-lang/ex_doc)
and published on [HexDocs](https://hexdocs.pm). Once published, the docs can
be found at <https://hexdocs.pm/bacstack>.
-->
## Getting Started
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.
```elixir
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.
```elixir
alias BACnet.Stack.ForeignDevice
ForeignDevice.start_link(bbmd: {bbmd_ip, 0xBAC0}, client: Client)
```
## Character Sets
This library uses the library [Codepagex](https://hex.pm/packages/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.
## Time Zone
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`).
```elixir
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](https://hex.pm/packages/tzdata) it's just a matter of configuration:
```elixir
config :elixir, :time_zone_database, Tzdata.TimeZoneDatabase
```
## Extensibility
Some parts of this library can be extended at compile-time to provide additional value. Let's explore them.
### Property Identifiers
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:
```elixir
config :bacstack, :additional_property_identifiers, loop_enable: 523, loop_mode: 524
```
### Object Properties
For 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:
```elixir
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.
### Object Types
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.
### Services
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.
### Errors
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.
## Status of BACnet objects implementation
| 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 | - | - | - |
## Status of BACnet services implementation
| 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 | |
## Status of Event Algorithms Implementation
| 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 |
## Status of Fault Algorithms Implementation
| 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 |
