@thing-it/device-bacnet NPM

thing-it-device-bacnet

thing-it-node Device Plugin for BACnet networks to control BACnet devices.

The BACnet Device Plugin is operational for the scope described here which represents a subset of the full BACnet protocol plus thing-it specific usages, such as higher level compelx devices. Contact us if you're interested in connecting thing-it to your BACnet environment and / or supporting additional BACnet features, devices, or objects.

Description

This Device Plugin allows you to

show and modify values of any BACnet object of a BACnet device via the thing-it Mobile App and the thing-it portal at www.thing-it.com,
visualize historic data of any connected BACnet object,
combine data and controls from any other thing-it plugin, and
define complex scenes, storyboards and timer controlled execution

by connecting an arbitrary number of BACnet devices to a thing-it-node on the same network. thing-it-node can be run on a variety of computers incuding Raspberry Pis and Linux server.

Hereby, this plugin represents basic BACnet Objects such as

Analog Input
Analog Value
Binary Input
Binary Value
Multi State Input
Multi State Value

connected to a generic BACnet Device and communication to those via UDP/IP.

The plugin also supports specific higher level devices, such as

Thermostat
Light
Jalousie

by bundling a series of individual BACnet objects into a logical context.

User Interface Examples

Mobile UI

BACnet Object Configuration

Higher Level BACnet Device Configuration

Dashboard

In a dashboard data from a BACnet device, such as

a room's temperature setpoing history
the BACnet device's CPU load history and current value
the BACnet device's internal temperature history and current value

can be combined with thing-it-device-weather data, such as

historic outside temperature
historic outside humidity

Non-Developers

Developers

Those who are interested in implementing their own specific higher level BACnet Device e.g. a thermostat with specific state, services and UI from a thing-it-node perspective can still use the BacNetAdapter class under lib in this package to easily implement communication with the BACnet network via IP/UDP.

Installation

Installation thing-it-node

Follow the installation steps at thing-it-node to turn your computer (e.g. your PC, your Raspberry Pi, or a Linux server) into a thing-it Gateway. Installing thing-it-node automatically also installs the BACnet plugin.

After installation follow the instructions to pair your thing-it Gateway with www.thing-it.com and to start the thing-it-node. Use the configuration portal at www.thing-it.com to confirm your thing-it Gateway is properly connected.

Connectivity to BACnet

Make sure that the computer running thing-it-node (your thing-it Gateway) can connect your BACnet devices via an IP connection. As the BACnet protocol uses UPD broadcasts for an initial WhoIs / IAm handshake your BACnet devices and your thing-it Gateway should be on the same network to simplify the setup.

If your BACnet devices and your thing-it Gateway are not in the same network, additional network configuration and/or hardware may be required to ensure broadcasts from the BACnet devices can be seen by the thing-it Gateway and vice versa.

Configuring Devices and Actors

Device

Use the configuration portal at www.thing-it.com to create a BACnet device. You should specify either

IP Match Required flag and the IP address of the device, and/or
Device Id Match Required flag and the BACnet device id

of the device to connect with it. There are also other optional parameters that you can use:

Vendor Id Match Required and vendor Id - in case if you want to use vendor Id for pairing with the device,
URL Match Required flag and URL - in case if your device uses URL which can be resolved by DNS,
Port - to specify the port for connection (default value is 47808),
Priority - the priority value that will be used in BACnet commands pioritization mechanism (default value is 16),
Unicast WhoIs Confirmation flag - to use direct comunication for pairing with the device instead of broadcasting. Couldn't be used if IP address or URL is not specified,
Status Checks interval - the frequency of device healthchek requests (default interval is 60s)

Once your device is connected, you can add actors for BACnet objects or complex higher level objects.

Basic BACnet actors

Many BACnet actors have common configuration fields. To configure any BACnet actor you should at least specify:

Object Identifier - number of your BACnet object's instance;
Log Level - maximum level of log messages which will be displayed when TIN running this actor. Also affects Gateway Logs output.

In addition to that, most of BACnet objects have parameter that are common, but not stricly required:

Status Checks Interval (default: 60s) - time interval for performing BACnet object's healthcheck polling requests.
Subscribe to COV Notifications (default: true) - Allows BACnet actors to receive state updates via COV Notifications mechanism. The option is on by default, but some old implementations of BACnet objects don't support such messaging. In that case, it should be turned off.
(depricated) Object Type - a type of BACnet object. Normally, you need both Object Type, and Object Instanse to encode Object Id. In new version of plugin, the Object Type is already set for each basic actor, so you don't need to set is explicitly in the configuration.
(depricated) Object Name - name of your BACnet object. In new version of plugin, this field is presented in object's state and received from the Object, so you don't need to specify it manually.
(depricated) Description - description of your BACnet object. In new version of plugin, this field is presented in object's state and received from the Object, so you don't need to specify it manually.

Analog Input

Here are the specific configuration fields for Analog Input :

Unit - name of the measuring unit of analog input. This field is also presented in the actor's state and could be received via BACnet readProperty request. The value from state used only when it is missing in configuration.
Analog Value
Here are the specific configuration fields for Analog Value :
Unit - name of the measuring unit of analog value. The same way as for Analog input, this field could be ether received from the actor (if not presented).
Minimum value (default: 0) - the lowest border of actor's presentValue. Could be ether received from the actor, or from configuration.
Maximum value (default: 100) - the highest border of actor's presentValue. Could be ether received from the actor, or from configuration.
Unused fields
For Analog Value and Binary Value there are some fields that currently no use in the plugin's logic.
Read-only (default: false) - Designed to switch on the read-only mode for BACnet Object (presentValue could be read, but couldn't be written)
Write-only (default: false) - Designed to switch on the write-only mode for BACnet Object (presentValue could be written, but couldn't be read)
Complex actors

Complex actors are basically combinations of basic, combined to represent different interfaces of some particular devices (thermostat, jalousie, etc). They also have some common configuration fields:

Log Level - maximum level of log messages which will be displayed when TIN running this actor. Also affects Gateway Logs output.
Status Checks Interval (default: 60s) - time interval for performing BACnet object's healthcheck polling requests.

Binary Light

The actor that represents simple light switch with two states (on and off). COnfiguration:

Light Active Object Id - number of BACnet object's instance that represents state of binary light.
Light Active Object Type - a type of BACnet object that represents state of binary light. Should be set to BinaryValue.

Jalousie Simple

The actor that represents jalousie device with the basic controlls (open/close blades, move up/down, move by step). Configuration:

Motion Direction Object Id - number of BACnet object's instance that represents the motion direction of the Jalousie Simple.
Motion Direction Object Type - a type of BACnet object that represents the motion direction of the Jalousie simple. Should be set to BinaryValue.
Stop Value Object Id - number of BACnet object's instance that used to start/stop movement of the Jalousie simple.
Stop Value Object Type - a type of BACnet object that used to start/stop movement of the Jalousie simple. Should be set to BinaryValue.
Step duration (default: 5s) - a duration of step movement. Basically movement by step is regular movement, restricted by particular time. This parameter is used to set this interval.

Jalousie

The actor that represents jalousie device with full controll of jalousie position and rotation. Configuration:

Position Feedback Oject Id - number of BACnet object's instance that represents the interface for reading Jalousie position value.
Position Feedback Oject Type - type of BACnet object that represents the interface for reading Jalousie position. Should be set to AnalogValue
Position Modification Oject Id - number of BACnet object's instance that represents the interface for setting target Jalousie position value.
Position Modification Oject Type - type of BACnet object that represents the interface for setting target Jalousie position. Should be set to AnalogValue.
Position Step Size - the least position change that could be applied to pozition value.
Rotation Feedback Oject Id - number of BACnet object's instance that represents the interface for reading Jalousie blades rotation angle.
Rotation Feedback Oject Type - type of BACnet object that represents the interface for reading Jalousie blages rotation angle. Should be set to AnalogValue.
Rotation Modification Oject Id - number of BACnet object's instance that represents the interface for setting target Jalousie rotation angle.
Rotation Modification Oject Type - type of BACnet object that represents the interface for setting target Jalousie rotation angle. Should be set to AnalogValue.
Rotation Up Value - rotation angle value, that represents opened state of blades. Usually equals to 0°, but may differ in some cases.
Rotation Down Value - rotation angle value that represents closed state of blades. Usually equals to 90°, but may differ in some cases.
Rotation Step Size - the least rotation angle change that could be applied to rotation angle value.
Action Object Id - number of BACnet object's instatnse that represents interface for triggering jalousie movement after setting target position and rotation valies.
Action Object Type - type of BACnet object that represents interface for triggering/stoping jalousie movement after setting target position and rotation valies. Should be set to MultiStateValue
Action Go Value - a specific value, used to trigger jalousie movement (by writing it to Action Object's presentValue).
Action Stop Value - a specific value, used to stop jalousie movement (by writing it to Action Object's presentValue).

Light

The actor that represents a light with dimmer and switch. Configuration:

Level Feedback Object Id - number of BACnet object's instance that represents the interface for reading Light dimmer level.
Level Feedback Object Type - type of BACnet object that represents the interface for reading Jalousie Light dimmer level. Should be set to AnalogValue.
Level Modification Oject Id - number of BACnet object's instance that represents the interface for changing Light dimmer level.
Level Modification Oject Type - type of BACnet object that represents the interface for changing Light dimmer level. Should be set to AnalogValue.
Light Active Feedback Object Id - number of BACnet object's instance that represents the interface for reading the state of Light switch.
Light Active Feedback Object Type - a type of BACnet object that represents the interface for reading the state of Light switch. Should be set to MultiStateValue.
Light Active Modification Object Id - number of BACnet object's instance that represents the interface for changing the state of Light switch.
Light Active Modification Object Type - a type of BACnet object that represents the interface for changing the state of Light switch. Should be set to MultiStateValue.
Light Active Modification Value On - a specific value, used to turn the Light switch on (by writing it to Light Active Modification Object's presentValue).
Light Active Modification Value Off - a specific value, used to turn the Light switch off (by writing it to Light Active Modification Object's presentValue).

Thermostat

The actor that represents thermostat device with the control of temperature setpoint. Configuration:

Setpoint Feedback Object Id - number of BACnet object's instance that represents the interface for reading Thermostat temperature setpoint.
Setpoint Feedback Object Type - type of BACnet object that represents the interface for reading Thermostat temperature setpoint. Should be set to AnalogValue.
Temperature Object Id - number of BACnet object's instance that represents the interface for reading the actual temperature, measured by Thermostat sensor.
Temperature Object Type - type of BACnet object that represents the interface for reading the actual temperature, measured by Thermostat sensor. Should be set to AnalogValue.
Setpoint Modification Object Id - number of BACnet object's instance that represents the interface for changing Thermostat temperature setpoint.
Setpoint Modification Object Type - type of BACnet object that represents the interface for changing Thermostat temperature setpoint. Should be set to AnalogValue.
Mode Object Id - number of BACnet object's instance that represents the interface for reading Thermostat mode (heating, cooling, etc.).
Mode Object Type - type of BACnet object that represents the interface for reading Thermostat mode (heating, cooling, etc.). Should be set to MultiStateValue.

Where to go from here ...

After completing the above, you may be interested in

Configuring additional Devices, Groups, Services, Event Processing, Storyboards and Jobs via your thing-it Mobile App.
Use thing-it.com to safely connect your Node Box from everywhere, manage complex configurations, store and analyze historical data and offer your configurations to others on the thing-it Mesh Market.
Explore other Device Plugins like Texas Instruments Sensor Tag, Plugwise Smart Switches and many more. For a full set of Device Plugins search for thing-it-device on npm. Or write your own Plugins.