SIMPL BACnet Basics: A Tutorial How to use BACnet symbols in a SIMPL program v1.3 September 9, 2015

SIMPL BACnet Basics:A Tutorial

How to use BACnet symbols in a SIMPL program

v1.3

September 9, 2015

Overview of Crestron BACnet

• BACnet stands for Building Automation and Control Network

• The BACnet protocol is supported by Crestron’s SIMPL programming language

• This presentation is designed to provide an example of how to use SIMPL BACnet symbols to communicate with BACnet devices

Types of BACnet Symbols

• SIMPL uses two types of symbols to communicate in the BACnet environment

• HOST symbols allow a Crestron controller to appear as a BACnet device within a system that is controlled by a third-party (BACnet) controller

• REMOTE symbols allow a Crestron system to control and communicate with other BACnet devices

The Test Environment

• Suggested minimum versions:– 3 Series firmware: v1.011.0023– Crestron Database: 49.00.006.00– Device Database: 61.05.004.00 – Simpl Windows: v4.02.56.01– Toolbox: 2.38.637

• Each controller must have a BACnet license. A free BACnet/IP license is available to support up to 50 objects. For systems with more than 50 objects you must purchase the full license. It can be obtained from the web site below:

• http://www.crestron.com/resources/product_and_programming_resources/bacnet/license/default.asp?from=www.crestron.com%2Fbacnetlicense

http://www.crestron.com/resources/product_and_programming_resources/bacnet/license/default.asp?from=www.crestron.com/bacnetlicense

http://www.crestron.com/resources/product_and_programming_resources/bacnet/license/default.asp?from=www.crestron.com/bacnetlicense

The Test Environment (continued)• No actual BACnet devices are required for this tutorial• A BACnet environment can be simulated using multiple Crestron controllers

(minimum of two)• Each Crestron controller can simulate only one Host device, but multiple

Remote devices• There are several console commands that are available for the BACnet

environment. Those commands are not included within the scope of this document, except one.

• Enter the following console command on each of the controllers you are using:

MC3>BACNETDEVicescantime 1Remote device discovery time 1 minutes set Successfully

• This is intended to have the two controllers sync up as quickly as possible for the purposes of this tutorial. It is not recommended as standard practice.

Adding BACnet Devices in SIMPLRight click controller and add a 3-Series BACnet item to the controller

BACnet will appear in a new slot. The slot number will vary depending on the controller.

Defining BACnet DevicesEach BACnet device must contain a unique <ObjectID> and <ObjectName>

Leave the <PortNumber> at the default value 47808

The most basic test environment requires two Crestron 3-Series controllers. Each must have a BACnet license. The first controller will be referred to as the HOST controller, the other as the REMOTE controller.After adding the BACnet device to each controller, enter a unique ObjectID and ObjectName for each. Valid values for each are described in the previous slide.

HOST CONTROLLER REMOTE CONTROLLER

Defining BACnet Devices (continued)

The REMOTE controller already has the Hosted BACnet Device parameters filled in from previous step. In SIMPL, REMOTE Devices require the Hosted BACnet Device parameters even if they are not used. Now add a REMOTE BACnet Device to the REMOTE controller. You can select it from the Device library, or right-click on C2I-REMOTE-BACNET-DEVICE and add it from the Select New Device menu

• Expand the BACnet symbol in Program View. Enter the same ObjectID for the Remote BACnet Device on controller 2 as the ObjectID for the Hosted BACnet Device on controller 1

• The symbol in the middle of the figure – C2I-REMOTE-BACNET-DEVICES is not needed. It is shown here so you know you can ignore the one signal. It is a legacy from the early days.

• The Hosted BACnet Device symbol is required for every program that uses BACnet. Even when a controller is used only for Remote Devices, the Host Device parameters must filled in.


• Enter signal names on the Remote BACnet Device symbol and connect the serial signals to a Make String Permanent symbol.

•These strings are for information purposes only and do not affect functionality. Without the Make String Permanent symbol this information is lost after the program starts.

• This step can be omitted and you will still have BACnet functionality.


Remote BACnet Device Signal Definition

You now have two SIMPL programs that can communicate with each other using BACnet protocol.

PROGRAM #1 (HOST)

PROGRAM #2 (REMOTE)Note that there are no IP table entries. As long as the two controllers are on the same subnet and have a valid ObjectID and ObjectName the BACnet protocol will manage the connection.

• Load each program to its respective controller• Open a SIMPL Debugger window in Toolbox• Connect to the REMOTE controller (ObjectName controller 2 )• The information for the HOST (ObjectName controller 1) will be displayed in SIMPL Debugger

This completes the BACnet Device configuration section

ADDING BACNET OBJECTS TO THE BACNET DEVICES

In this section you will learn how to send data between two BACnet devices

Notes about BACnet Objects in the world of SIMPL

• In the previous section, a unique ObjectID was assigned to each device

• In the next section, the parameter ObjectID is also used for objects

• A BACnet device contains one or more BACnet objects

• This is similar to a Crestron environment containing several identical devices. The IP or Cresnet ID is analogous to the device ObjectID, whereas the device symbols are the objects.

Notes about BACnet Objects in the world of SIMPL (continued)

• BACnet supports many different types of objects and properties

• The only property that all BACnet devices must support is PresentValue

• BACnet SIMPL symbols contain other signals that can control and respond to read and write events

• The scope of this section is limited to only reading and writing the PresentValue property

Notes about BACnet Objects in the world of SIMPL (continued)

• There are several ways to query and poll BACnet devices to send or receive data.

• All examples presented in this document rely on the Change Of Value (COV) method.

• The COV method updates all BACnet data at the moment any value changes. It does not wait for a periodic update time, or polling signal.

• A more detailed explanation on alternate polling techniques (other than COV) will be discussed later.

Binary Input Objects

• The Binary Input Object is used to represent a physical digital input. A typical use for this type of object is to indicate whether a particular piece of mechanical equipment, such as a fan or pump, is running or idle.

• You can only write the PresentValue to a Binary Input Object.

Add a Hosted Binary Input Object to the HOST program. You can drag and drop it from the Device library, or right-click on C2I-HOSTED-BACNET-DEVICE and add it from the Select New Device menu

Add a Remote Binary Input Object to the REMOTE program. You can select it from the Device library, or right-click on C2I-REMOTE-BACNET-DEVICE and add it from the Select New Device

menu

Adding Binary Input Objects

PROGRAM #1 (HOST) PROGRAM #2 (REMOTE)

Signals needed for a Hosted Binary Input Object

• Parameter: <ObjectID> A 22-bit decimal number that serves as an unique address of the object within the BACnet device. Valid range from 0d to 4194302d.

• Parameter: <ObjectName> A printable string (restricted to maximim 80 characters in length) unique for the BACnet device.

• Digital input: <PresentValue> Represents the current state of the object. Can have one of two values: ACTIVE and INACTIVE.

• Enter the values shown by the red arrows in the figure.

Signals needed for a Remote Binary Input Object


• The <ObjectID> should be the same as the corresponding <ObjectID> of the host object

• Digital output: <PresentValue> Reports the <PresentValue> of the object


Binary Input Object Signal FlowBinary data entered for the PresentValue on the host object...

will be transmitted to the PresentValue on the remote object

Binary Input Objects in SIMPL Debugger


This completes the BACnet Binary Input Object section

Binary Value Objects

• The Binary Value Object functions much like a Binary Input Object, with the added feature of being able to read / write the PresentValue.

• These objects are added to the program using the same method as the Binary Input Objects.

Adding Binary Value Objects


Signals needed for a Hosted Binary Value Object


• Parameter: <ObjectName> A printable string (restricted to maximim 80 characters in length) unique for the BACnet device.

• Digital input: <PresentValue> Sets the current <PresentValue>.

• Digital output: <PresentValueOut> Reports the current<PresentValue>.

• NOTE: A signal feedback (using the same signal name) should be introduced between <PresentValueOut> and <PresentValue>, otherwise the BACnet stack won't update the value.


Signals needed for a Remote Binary Value Object


• The <ObjectID> should be the same as the corresponding <ObjectID> of the host object

• Digital input: <SetPresentValue> On the rising edge of the signal sets <PresentValue> to go High.

• Digital input: <ClearPresentValue> On the rising edge of the signal clears <PresentValue>.

• Digital output: <PresentValue> Reports the current <PresentValue>.


Binary Value Object Signal FlowA change in PresentValue on the host object will also change the PresentValue on the remote object

The PresentValue on the remote object can be changed with a pulse on SetPresentValue or ClearPresentValue. The PresentValue on the host object will also change.

Binary Value Objects in SIMPL Debugger


This completes the BACnet Binary Value Object section

Analog Input Objects• The Analog Input Object is used to represent a physical input into the control

system. This could be a device such as a thermometer or other measuring device.

• It is similar in nature to the Binary Input Object, the major difference being that the “Present Value” property of the Analog Input Object is of type REAL.

• Standard BACnet analog signals are 32 bit real values. SIMPL only understands 16 bit integers, therefore there is a 16 bit ‘LoWord’ and a 16 bit ‘HiWord’.

• Values from 0-65535 can be sent using only the LoWord signal. Negative values, or values greater than 65535 require the HiWord to be used as well.

• The Hosted Analog Input Object includes a scaling provision for up to three decimal places by using the <DecimalPlace> parameter.

• This presentation only discusses signals needed for values in the range of 0-65535.

Adding Analog Input Objects


Signals needed for a Hosted Analog Input Object

• Parameter: <ObjectID>

• Parameter: <ObjectName>

• Parameter: <Units> This parameter is required but in no way affects the numeric PresentValue data. It is just an enumerated data type. You can select any unit from the list.

• Parameter: <COVIncrement> If <DecimalPlace> is set to 0d, <COVIncrement> will consist of one field allowing only a whole number (i.e. X) ranging from 1d to 65535d. For this example, the value of ‘1’ specifies the minimum change that will cause the PresentValue to update.

• Analog input: <PresentValueLoWord> The lower 16 bits of the desired <PresentValue> property of the object.


Signals needed for a Remote Analog Input Object

• Parameter: <ObjectID> should be the same as the corresponding <ObjectID> of the host object

• Analog output: <PresentValueLoWord> : Reports the lower 16 bits of the <PresentValue> property.

• Analog outputs: <Units> and <COVIncrement> These signals provide feedback from the corresponding parameters entered on the HOST object symbol. They have no effect on the PresentValue data. They are not required, but are being included here for the sake of completeness since these values must be entered on the HOST object.


Analog Input Object Signal FlowAnalog data entered for the PresentValueLoWord on the host object...

will be transmitted to the PresentValueLoWord on the remote object

Analog Input Objects in SIMPL Debugger


Note that there are three transitions on the HOST program...

... but there are five transitions on the REMOTE program

This reason for this will be explained in the following slides

Important notes about analog outputsThe signals RAIO_units and RAIO_COVIncrement are ‘feedback’ signals that are read from the corresponding parameters defined on the HOST object.______________________________

The signal RAIO_PVLO is an analog output. All analog outputs on all BACnet SIMPL symbols have a known, unpredictable operating condition. There are usually TWO values which are output, but sometimes only ONE value appears on an analog output.

This can be seen in the figure on the upper right. There are two yellow boxes that demonstrate this condition. What happens is the ‘old’ PresentValue is output prior to the ‘new’ PresentValue, resulting in two responses to a single event.

We have been using the term ‘double pulsing’ to describe this phenomena. This unpredictable operation may or may not cause a problem in your program. It is more likely to become an issue when routing signals into a SIMPL+ module. A solution for this will be presented next.

Important notes about analog outputs (continued)

In the first instance, the initial state of HAIO_PVLO and RAIO_PVLO is 0. When the user sets HAIO_PVLO to 23, RAIO_PVLO responds by first sending out the old value of 0, followed by the new value of 23. The time difference is milliseconds.

In the second instance, the value of HAIO_PVLO and RAIO_PVLO is now 23. When the user sets HAIO_PVLO to 500, RAIO_PVLO responds by outputting the new value of 500 without sending out the old (previous) value of 23.

In the third instance, the value of HAIO_PVLO and RAIO_PVLO is now 500. When the user sets HAIO_PVLO to 0, RAIO_PVLO responds by first sending out the old value of 500, followed by the new value of 0. The time difference is milliseconds.

A SOLUTION TO THE ANALOG OUTPUT ‘DOUBLE PULSE’

/*********************************************** DIGITAL, ANALOG and SERIAL INPUTS and OUTPUTS************************************************/ANALOG_INPUT AI;ANALOG_OUTPUT AO;

/*********************************************** Global Variables************************************************/INTEGER PreviousValue;

/*********************************************** Event Handlers************************************************/CHANGE AI{// this ignores the first double-pulse on // BACnet objects for zero-time RCB if (AI = PreviousValue)

{// do nothing

}else{

AO = AI;PreviousValue = AI;

}}

• When the SIMPL+ module shown is connected to an analog output, it will prevent the ‘double pulse’ from propagating to other symbols.

• If the ‘old’ or previous PresentValue is output prior to the ‘new’ or current PresentValue, only the ‘new’ PresentValue will pass through.

• The reason for the ‘double pulse’ occurring is due to the zero-time ramp control block that is used in the BACnet code.

• The name used for this SIMPL+ Module was ‘RCB filter’. It is shown in the next slide.

Using the Ramp Control Block Filter (RCB filter.usp)

This filter may not be needed in your program. It is shown here in case the ‘double pulse’ condition is causing issues within your application. No further reference will be made to it in this presentation.

This completes the BACnet Analog Input Object section

Analog Value Objects• The Analog Value Object functions much like a Analog Input Object, with

the added feature of being able to read or write the current state.• This object is intended to represent storage or control values (for

example, to set a thermostat's temperature setpoint). It can also be used to represent a sensor input or control output.

• Like the Analog Input object, the PresentValue signal is split between the PresentValueHiWord and the PresentValueLoWord.

• Values from 0-65535 can be sent using only the LoWord signal. Negative values, or values greater than 65535 require the HiWord to be used as well.

• The Hosted Analog Value Object includes a scaling provision for up to three decimal places by using the <DecimalPlace> parameter.

• This presentation only discusses signals needed for values in the range of 0-65535.

Adding Analog Value Objects


Signals needed for a Hosted Analog Value Object



• Parameter: <Units> This parameter is required but in no way affects the numeric PresentValue data. It is just an enumerated data type. You can select any unit from the list.

• Parameter: <COVIncrement> If <DecimalPlace> is set to 0d, <COVIncrement> will consist of one field allowing only a whole number (i.e. X) ranging from 1d to 65535d. For this example, the value of ‘1’ specifies the minimum change that will cause the PresentValue to update.

Signals needed for a Hosted Analog Value Object (continued)

• Analog input: <PresentValueLoWord> The lower 16 bits of the desired <PresentValue> property of the object.

• Analog output: <PresentValueOutLoWord> Reports the new current value for the lower 16 bits of <PresentValue>.

• Whenever there is a change in value the programmer should introduce a signal feedback by using the same signal name on <PresentValueOutLoWord> and <PresentValueLoWord>, otherwise the BACnet stack won't update the value.


Signals needed for a Remote Analog Value Object


• Analog input: <NewPresentValueLoWord> Sets the lower 16 bits of <PresentValue> of the object.

• Analog output: <PresentValueLoWord> : Reports the lower 16 bits of the <PresentValue> property.

• Analog outputs: <Units> and <COVIncrement> These signals provide feedback from the corresponding parameters entered on the HOST object symbol. They have no effect on the PresentValue data. They are not required, but are being included here for the sake of completeness since these values must be entered on the HOST object.


Analog Value Object Signal FlowA change in PresentValueLoWord on the host object will also change the PresentValueLoWord on the remote object

A change in NewPresentValueLoWord on the remote object will update the PresentValueLoWord on both the remote and host object

Analog Value Objects in SIMPL Debugger


‘Double Pulse’ events are outlined in yellow

This completes the BACnet Analog Value Object section

Multistate Input Objects

• Multistate objects are used to represent multiple-state processes. The Hosted Multistate Input Object is similar to the Binary Input and Analog Input Objects, the difference being that the PresentValue is an enumerated value.

• For example, a fan may have more than two discrete states (such as High, Medium and Low) rather than a numeric value.

Adding Multistate Input Objects


Signals needed for a Hosted Multistate Input Object



• Analog input: <PresentValue> Sets the current <PresentValue>.

• Parameter: <NumberOfStates> Defines the number of states the <PresentValue> may have. Valid values are 1d to 50d.

• Parameter <State Text1> (optional through <State Text50>) String parameter(s) not more than 40 characters long, describing each state of <PresentValue>. NOTE: There should be as many State Texts defined as specified in the <NumberOfStates> parameter.

• Additionally all states need to have <State Text> parameter assigned to them. If there is no <State Text> parameter description assigned to a specific state, this state will not exist in runtime.

• You can insert additional State Text parameters in SIMPL using <Alt +> to add fields


Signals needed for a Remote Multistate Input Object


• Analog output: <PresentValue> Reports the <PresentValue>

• Analog output: <NumberOfStates> Defines the number of states the <PresentValue> may have. This is a feedback signal from the HOST object. NOTE: This output has to be defined, otherwise the object will not work properly.

• Serial output: <StateText> Reports the state associated with the current <PresentValue>.


Multistate Input Object Signal FlowWhen PresentValue is changed on the HOST object, it sends the enumerated StateText associated with that value

The REMOTE object receives the PresentValue as well as the enumerated StateText

Multistate Input Objects in SIMPL Debugger


Note the results in Program #2 (REMOTE). This illustrates the ‘double pulse’ condition previously described with analog objects. The previous value is being output prior to the new vale. Multistate objects use the same logic, and are susceptible to the same unpredictable behavior that affect analog objects.

This completes the BACnet Multistate Input Object section

Multistate Value Objects

• The Hosted Multistate Value Object is similar to the Hosted Binary Value and Hosted Analog Value Objects, the only difference being that the “Present Value” is an enumerated value.

• Examples of applications for Multistate Value Objects are: Active Preset (feedback only, control only, or feedback and control)

• HVAC mode (heat, cool, auto, off)

Adding Multistate Value Objects


Signals needed for a Hosted Multistate Value Object



• Analog input: <PresentValue> Sets the current <PresentValue>.

• Analog output: <PresentValueOut> Sets the current <PresentValue>. Whenever there is a change in value the programmer should introduce a signal feedback by using the same signal name on <PresentValueOut> and <PresentValue>, otherwise the BACnet stack won't update the value.

• Parameter: <NumberOfStates> Defines the number of states the <PresentValue> may have. Valid values are 1d to 50d.

Signals needed for a Hosted Multistate Value Object (continued)

• Parameter <State Text1> (optional through <State Text50>) String parameter(s) not more than 40 characters long, describing each state of <PresentValue>. NOTE: There should be as many State Texts defined as specified in the <NumberOfStates> parameter.

• Additionally all states need to have <State Text> parameter assigned to them. If there is no <State Text> parameter description assigned to a specific state, this state will not exist in runtime.

• Serial output: <StateText> Sets the textual representation of the state associated with the current <PresentValue>.

• You can insert additional State Text parameters in SIMPL using <Alt +> to add fields


Signals needed for a Remote Multistate Value Object


• Analog input: <NewPresentValue> Sets the current <PresentValue>.

• Analog output: <PresentValue> Reports the <PresentValue>

• Analog output: <NumberOfStates> Defines the number of states the <PresentValue> may have. This is a feedback signal from the HOST object. NOTE: This output has to be defined, otherwise the object will not work properly.

• Serial output: <StateText> Reports the state associated with the current <PresentValue>.


Multistate Value Object Signal FlowA change in PresentValue on the host object will update StateText as well as change the PresentValue and StateText on the remote object

A change in NewPresentValue on the remote object will update the PresentValue and StateText on both the remote and host object

Multistate Input Objects in SIMPL Debugger


This capture from SIMPL Debugger illustrates the ‘double pulse’ condition on the analog outputs. Note each transition in PresentValue triggers a StateText event as well.

This completes the BACnet Multistate Value Object section

This completes the BACnet tutorial section

Object Polling Signals and Parameters

How to update BACnet data using methods other than Change of Value

(COV)

Object Polling Signals and Parameters

This section will be available in a future version of this document.

Documents

SIMPL BACnet Basics: A Tutorial How to use BACnet symbols in a SIMPL program v1.3 September 9, 2015