.. _user/protocols/bacnet:

******
BACnet
******

BACnet is a data communication protocol for **B**\uilding **A**\utomation and
**C**\ontrol **net**\works. A data communication protocol is a set of rules
governing the exchange of data over a computer network. The rules take the form
of a written specification that spells out what is required to conform to the
protocol.

.. _user/protocols/bacnet_glossary:

BACnet glossary (advanced reading)
==================================

Device
  The device represents a server that is managing one or more BACnet objects. A
  device has a unique **device instance** number (which is sufficient for
  addressing if using the same network interface) and a unique UDP port as
  **device address** (in the format `<ip-address>:<port-number>`) which can be
  used for addressing throughout the entire LAN. Technically, the device is an
  object with the name `device`. The device instance in fact is its object
  instance with the additional requirement to be unique.

Object
  An object reflects a physical hardware actor or sensor (i.e. an I/O device).
  BACnet defines a list of standardized **object type**\s (such as analog-input,
  analog-output, binary-input, binary-output, etc.). Object types are identified
  by a fixed number or by a fixed ASCII string identifier (s.a.). Depending on
  the installation, a device may serve an arbitrary number of **object instance**\s
  of arbitrary type. A device may for example run 3 analog-inputs, 1
  analog-value and two binary-outputs. An object is addressed using its type and
  numeric instance ID which must only be unique within the device.

Property
  Every object contains a type-dependent set of **properties**. The most
  important property that exists in every object is the `present-value`
  property. This is conceptually very similar to the process-variable (PV) of
  other industry protocols. Like object types, the properties are identified by
  a fixed number or by a fixed ASCII string (e.g. `present-value`). Examples of
  other properties are `version` or `object-name`. The property is the final
  data-endpoint where values can be read from or written to. The value type can
  be any scalar value, arrays of scalars or specific complex types (this depends
  on the object type).

For unambiguously addressing any data endpoint (in BACnet: `property`) the
following information must be provided:

* At the :ref:`Cybus::Connection <user/protocols/bacnet_connection>`:

  1. ``deviceAddress`` (e.g. `192.168.2.160:43712`)
  2. ``deviceInstance`` (e.g. `27335`)

* At the :ref:`Cybus::Endpoint <user/protocols/bacnet_endpoint>`:

  1. ``objectType`` (e.g. `analog-input`)
  2. ``objectInstance`` (e.g. `2`)
  3. ``property`` (e.g. `present-value`)

.. note::

  If only one device is running on a given host (with fixed IP), the port can
  be omitted from the `deviceAddress` field.



.. _user/protocols/bacnet_connection:

.. include:: ../protocolSchemas/BacnetConnection.rst


.. _user/protocols/bacnet_endpoint:

.. include:: ../protocolSchemas/BacnetEndpoint.rst

.. _user/protocols/bacnet_example:

Example Configuration
=====================

The following example demonstrates how to configure a simple BACnet connection
and endpoint that subscribes to an `analog-input` BACnet object.

Download: :download:`bacnet-example.yml`

.. literalinclude:: bacnet-example.yml
  :language: yaml
  :linenos:

Input Format
------------

To write data to BACnet a request must be sent to the MQTT endpoint of the service
using a ``/set`` suffix providing a JSON object with the following format:

.. code:: json

  { "value": "<value>" }

.. code

No response message is written to the `/res` topic of the Endpoint for this protocol.

Output Format on Read
---------------------

For a read endpoint, additionally a correlation id (id) can be set in the
payload of the message request, to ensure the correct identification of
responses to specific requests.

When data is read results are published to the `/res` topic of the Endpoint.
The output message is an object with the following format:

.. code:: json

  {
    "value": "<value>",
    "timestamp": "<msSinceEpoch>"
    "id": "<correlation id>"
  }

.. code

Further reading:
----------------

* `BACnet FAQ <http://www.bacnet.org/FAQ/HPAC-3-97.html>`_
* `The language of BACnet <http://www.bacnet.org/Bibliography/ES-7-96/ES-7-96.htm>`_
* `BACnet ASHRAE Standard <http://www.bacnet.org/Addenda/Add-2001-135d.pdf>`_