UPM

The UPM API is a high level sensor library for IoT devices using MRAA. See examples here. Back to index page.
SparkFun sensor images provided under CC BY-NC-SA-3.0.

BACNETMSTP Class

Module: common
  • ID: bacnetmstp
  • Name: UPM API for BACNET MS/TP Communications
  • Connection: uart
  • Link: http://bacnet.sourceforge.net/ This is a singleton class that provides services to UPM BACnet drivers (like E50HX ) based on the bacnet-stack at http://bacnet.sourceforge.net . This class is implemented as a singleton due to the fact that the bacnet-stack implementation does not currently allow multiple simultaneous datalinks. We are using 0.8.3 of bacnet-stack. In the future this restriction may be lifted depending on bacnet-stack, but for now, you are stuck with only a single BACnet MS/TP datalink.

This driver is not intended to be used by end users. It is intended for use with other UPM drivers that require access to a BACnet MS/TP (Master Slave/Token Passing) network over RS-485.
For this reason, no examples are provided. If you wish to implement your own BACnet MS/TP driver, please look at the E50HX driver to see how this class can be used.
Currently, only readProperty and writeProperty BACnet requests are supported. In the future, any other BACnet requests could be supported as well. readProperty and writeProperty should provide most of what you will need when communicating with BACnet devices. Since the source code is open, feel free to add other services as you see fit :)
In order to make requests over an MS/TP network, you must be a BACnet master. initMaster() is responsible for configuring your underlying RS-485 network and starting a Master FSM (finite state machine) thread that will be responsible for identifying other Masters on the network and negotiating token passing. Your master can only transmit when it has the token.
Fortunately, all of these messy details are handled for you by this class, or the underlying bacnet-stack library this class relies on.

Methods

initMaster

(
  • port
  • baudRate
  • deviceInstanceNumber
  • macAddr
  • maxMaster
  • maxInfoFrames
)

This function initializes the underlying BACNETMSTP Master singleton in the event it has not already been initialized. If the BACNETMSTP Master singleton has already been initialized, then this call will be ignored. There can be only one.

Parameters:

  • port String

    The serial port that the RS-485 interface is connected to.

  • baudRate Number

    The baudrate of the RS-485 interface. All devices on a BACnet RS-485 bus must run at the same baudrate. Valid values are 9600, 19200, 38400, 57600, 76800, and 115200.

  • deviceInstanceNumber Number

    This is the unique Device Object Instance number that will be used for our BACnet Master in order to communicate over the BACnet interface. This number must be between 1-4194302 and must be unique on the BACnet network.

  • macAddr Number

    This is the MAC address of our BACnet Master. It must be unique on the BACnet segment, and must be between 1-127.

  • maxMaster Number

    This specifies to our Master the maximum MAC address used by any other Masters on the BACnet network. This must be between 1-127, the default is 127. Do not change this unless you know what you are doing or you could introduce token passing errors on the BACnet network.

  • maxInfoFrames Number

    This number specifies the maximum number of transmissions (like requests for data) our Master is allowed to make before passing the token to the next Master. The default is 1.

readProperty

(
  • targetDeviceInstanceID
  • objType
  • objInstance
  • objProperty
  • arrayIndex
)
Boolean

Perform a BACnet readProperty transaction. This function will return when either the transaction has completed, or an error has occurred. It requests the value of a property, belonging to a specific object instance on a specific device.

Parameters:

  • targetDeviceInstanceID Number

    This is the Device Object Instance ID of the device to send the request to. This number will be unique for every device on the network. An address lookup will be performed the first time a request is made to a device using the WhoHas BACnet service. The result will be cached for further use.

  • objType BACNET_OBJECT_TYPE

    This is the BACnet object type of the object you wish to query. It should be one of the BACNET_OBJECT_TYPE values.

  • objInstance Number

    This is the instance number of the Object you wish to access. It is an integer starting from 1.

  • objProperty BACNET_PROPERTY_ID

    This is the property of the Object and instance you wish to access. It should be one of the BACNET_PROPERTY_ID values.

  • arrayIndex Number

    This specifies the index number of an array property. The default is BACNET_ARRAY_ALL.

Returns:

Boolean:

true if an error occurred, false otherwise.

writeProperty

(
  • targetDeviceInstanceID
  • objType
  • objInstance
  • objProperty
  • propValue
  • propPriority
  • arrayIndex
)
Boolean

Perform a BACnet writeProperty transaction. This function will return when either the transaction has completed, or an error has occurred. It writes the supplied value to a property, belonging to a specific object instance on a specific device.

Parameters:

  • targetDeviceInstanceID Number

    This is the Device Object Instance ID of the device to send the request to. This number will be unique for every device on the network. An address lookup will be performed the first time a request is made to a device using the WhoHas BACnet service. The result will be cached for further use.

  • objType BACNET_OBJECT_TYPE

    This is the BACnet object type of the object you wish to query. It should be one of the BACNET_OBJECT_TYPE values.

  • objInstance Number

    This is the instance number of the Object you wish to access. It is an integer starting from 1.

  • objProperty BACNET_PROPERTY_ID

    This is the property of the Object and instance you wish to access. It should be one of the BACNET_PROPERTY_ID values.

  • propValue BACNET_APPLICATION_DATA_VALUE *

    This is a pointer to a BACNET_APPLICATION_DATA_VALUE structure containg the data value to write to the property. Use the createData*() methods to properly create these structures.

  • propPriority Number

    This specifies the priority of a commandable property. Leave it at the default unless you know what you are doing. In addition, there is conflicting information in the bacnet-stack documentation as to whether this is even supported.

  • arrayIndex Number

    This specifies the index number of an array property. The default is BACNET_ARRAY_ALL.

Returns:

Boolean:

true if an error occurred, false otherwise.

getData

(
  • index
)
BACNET_APPLICATION_DATA_VALUE

After a successful readProperty request, this method can be used to return a BACNET_APPLICATION_DATA_VALUE structure containing the returned data.

Parameters:

  • index Number

    into the list of returned data. 0 (first) is the default.

Returns:

BACNET_APPLICATION_DATA_VALUE:

a BACNET_APPLICATION_DATA_VALUE structure containing the returned data.

getDataNumElements

() Number

After a successful readProperty request, this method can be used to return the number of data elements returned. This will usually be 1, unless reading an array.

Returns:

Number:

The number of data elements received.

getDataType

(
  • index
)
Number

After a successful readProperty request, this method can be used to return the BACnet data type of the returned data. It will be one of the BACNET_APPLICATION_TAG_* values.

Parameters:

  • index Number

    into the list of returned data. 0 (first) is the default.

Returns:

Number:

A BACNET_APPLICATION_TAG_* value

getDataTypeReal

(
  • index
)
Number

After a successful readProperty request, this method can be used to return the BACnet dataype of the returned data as a Real. If the data type ( getDataType() ) is not a BACNET_APPLICATION_TAG_REAL, and the value returned cannot be safely converted, an exception is thrown.

Parameters:

  • index Number

    into the list of returned data. 0 (first) is the default.

Returns:

Number:

A floating point value representing the returned data

getDataTypeBoolean

(
  • index
)
Boolean

After a successful readProperty request, this method can be used to return the BACnet dataype of the returned data as a Boolean. If the data type ( getDataType() ) is not a BACNET_APPLICATION_TAG_BOOLEAN, and the value returned cannot be safely converted, an exception is thrown.

Parameters:

  • index Number

    into the list of returned data. 0 (first) is the default.

Returns:

Boolean:

A boolean value representing the returned data

getDataTypeUnsignedInt

(
  • index
)
Number

After a successful readProperty request, this method can be used to return the BACnet dataype of the returned data as a unsigned int. If the data type ( getDataType() ) is not a BACNET_APPLICATION_TAG_UNSIGNED_INT, and the value returned cannot be safely converted, an exception is thrown.

Parameters:

  • index Number

    into the list of returned data. 0 (first) is the default.

Returns:

Number:

An unsigned int value representing the returned data

getDataTypeSignedInt

(
  • index
)
Number

After a successful readProperty request, this method can be used to return the BACnet dataype of the returned data as a signed int. If the data type ( getDataType() ) is not a BACNET_APPLICATION_TAG_SIGNED_INT, and the value returned cannot be safely converted, an exception is thrown.

Parameters:

  • index Number

    into the list of returned data. 0 (first) is the default.

Returns:

Number:

A signed int value representing the returned data

getDataTypeString

(
  • index
)
String

After a successful readProperty request, this method can be used to return the BACnet dataype of the returned data as a string. Most of the data types except Enum can be converted to a string. If the data type ( getDataType() ) is not a BACNET_APPLICATION_TAG_CHARACTER_STRING, and the value returned cannot be safely converted, an exception is thrown.

Parameters:

  • index Number

    into the list of returned data. 0 (first) is the default.

Returns:

String:

A string value representing the returned data

getDataTypeEnum

(
  • index
)
Number

After a successful readProperty request, this method can be used to return the BACnet dataype of the returned data as an enumeration. If the data type ( getDataType() ) is not a BACNET_APPLICATION_TAG_ENUMERATED an exception is thrown.

Parameters:

  • index Number

    into the list of returned data. 0 (first) is the default.

Returns:

Number:

An unsigned int representing a BACnet enumerant

createDataReal

(
  • Real
)
BACNET_APPLICATION_DATA_VALUE

This method is used to create and return an initialized BACNET_APPLICATION_DATA_VALUE containing a real (floating point value). A pointer to this returned structure can then be used with writeProperty() .

Parameters:

  • Real Number

    undefined

Returns:

BACNET_APPLICATION_DATA_VALUE:

An initialized structure containing the value

createDataBool

(
  • value
)
BACNET_APPLICATION_DATA_VALUE

This method is used to create and return an initialized BACNET_APPLICATION_DATA_VALUE containing a boolean. A pointer to this returned structure can then be used with writeProperty() .

Parameters:

  • value Boolean

    The boolean value to initialize the structure to.

Returns:

BACNET_APPLICATION_DATA_VALUE:

An initialized structure containing the value

createDataSignedInt

(
  • value
)
BACNET_APPLICATION_DATA_VALUE

This method is used to create and return an initialized BACNET_APPLICATION_DATA_VALUE containing a signed integer. A pointer to this returned structure can then be used with writeProperty() .

Parameters:

  • value Number

    The signed integer value to initialize the structure to.

Returns:

BACNET_APPLICATION_DATA_VALUE:

An initialized structure containing the value

createDataUnsignedInt

(
  • value
)
BACNET_APPLICATION_DATA_VALUE

This method is used to create and return an initialized BACNET_APPLICATION_DATA_VALUE containing a unsigned integer. A pointer to this returned structure can then be used with writeProperty() .

Parameters:

  • value Number

    The unsigned integer value to initialize the structure to.

Returns:

BACNET_APPLICATION_DATA_VALUE:

An initialized structure containing the value

createDataString

(
  • value
)
BACNET_APPLICATION_DATA_VALUE

This method is used to create and return an initialized BACNET_APPLICATION_DATA_VALUE containing a character string. A pointer to this returned structure can then be used with writeProperty() . Strings are typically limited to 63 characters.

Parameters:

  • value String

    The character string value to initialize the structure to.

Returns:

BACNET_APPLICATION_DATA_VALUE:

An initialized structure containing the value

createDataEnum

(
  • value
)
BACNET_APPLICATION_DATA_VALUE

This method is used to create and return an initialized BACNET_APPLICATION_DATA_VALUE containing an enumeration. A pointer to this returned structure can then be used with writeProperty() .

Parameters:

  • value Number

    The BACnet enumeration to initialize the structure to.

Returns:

BACNET_APPLICATION_DATA_VALUE:

An initialized structure containing the value

getErrorType

() BACERR_TYPE_T

Return an enumration of the last error type to occur. The value returned will be one of the BACERR_TYPE_T values.

Returns:

BACERR_TYPE_T:

The last error type to occur, one of the BACERR_TYPE_T values.

getRejectReason

() Number

In the event of a BACnet Reject error, return the error code.

Returns:

Number:

The Reject error code.

getRejectString

() String

In the event of a BACnet Reject error, return the error string.

Returns:

String:

The Reject error string.

getAbortReason

() Number

In the event of a BACnet Abort error, return the Abort reason code.

Returns:

Number:

The Abort reason code.

getAbortString

() String

In the event of a BACnet Abort error, return the Abort string.

Returns:

String:

The Abort error string.

getErrorClass

() BACNET_ERROR_CLASS

In the event of a general BACnet error, return the BACnet error class.

Returns:

BACNET_ERROR_CLASS:

One of the BACNET_ERROR_CLASS error class codes

getErrorCode

() BACNET_ERROR_CODE

In the event of a general BACnet error, return the BACnet error code.

Returns:

BACNET_ERROR_CODE:

One of the BACNET_ERROR_CODE error codes

getErrorString

() String

In the event of a general BACnet error, return the BACnet error string.

Returns:

String:

A string representing the BACnet error class and code.

getUPMErrorString

() String

In the event of a non-BACnet UPM error, return a string describing the error.

Returns:

String:

A string representing the UPM error.

isInitialized

() Boolean

Check to see if initMaster) has already been called, and out master is initialized.

Returns:

Boolean:

true if the master is initialized, false otherwise

getPort

() String

Return the port that was specified to initMaster() .

Returns:

String:

The port specified to initMaster() .

getDeviceInstanceID

() Number

Return the Object Device Instance ID for our Master was specified to initMaster() .

Returns:

Number:

The Object Device Instance ID for our Master.

getMaxInfoFrames

() Number

Return the maxInfoFrames parameter that was specified to initMaster() .

Returns:

Number:

The maxInfoFrames parameter specified to initMaster() .

getMaxMaster

() Number

Return the maxMaster parameter that was specified to initMaster() .

Returns:

Number:

The maxMaster parameter specified to initMaster() .

getBaudRate

() Number

Return the baud rate parameter that was specified to initMaster() .

Returns:

Number:

The baud rate parameter specified to initMaster() .

getMACAddress

() Number

Return the MAC address parameter that was specified to initMaster() .

Returns:

Number:

The MAC address parameter specified to initMaster() .

setDebug

(
  • enable
)

Enable or disable debugging output.

Parameters:

  • enable Boolean

    true to enable debugging, false otherwise

Properties

cmd

BACCMD_TYPE_T

readPropArgs

READ_PROPERTY_ARGS_T

writePropArgs

WRITE_PROPERTY_ARGS_T

BACERR_TYPE_NONE

Enum BACERR_TYPE_T

BACERR_TYPE_REJECT

Enum BACERR_TYPE_T

BACERR_TYPE_ABORT

Enum BACERR_TYPE_T

BACERR_TYPE_ERROR

Enum BACERR_TYPE_T

BACERR_TYPE_UPM

Enum BACERR_TYPE_T

BACCMD_NONE

Enum BACCMD_TYPE_T

BACCMD_READ_PROPERTY

Enum BACCMD_TYPE_T

BACCMD_WRITE_PROPERTY

Enum BACCMD_TYPE_T