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.

BACNETUTIL Class

Module: tb7300
  • Name: Utility API for BACnet
  • Connection: uart

This class implements some common access functions that are useful to any driver making use of the bacnetmstp driver.
It provides some basic functionality for reading and writing a proprty (with and without relability checking) as well as access to error conditions. It is intended to be inherited by your driver class.

Item Index

Methods

Methods

BACNETUTIL

(
  • targetDeviceObjectID
)
Number

Provided by the e50hx module.

BACNETUTIL constructor

Parameters:

  • targetDeviceObjectID Number

    undefined

Returns:

Number:

initMaster

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

Provided by the e50hx module.

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.

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.

setDebug

(
  • enable
)

Provided by the e50hx module.

Enable some debugging output in this module as well as the BACNETMSTP module. Debugging is disabled by default.

Parameters:

  • enable Boolean

    true to enable, false to disable.

getAnalogValue

(
  • objInstance
)
Number

Provided by the e50hx module.

Retrieve the Present_Value property of an Analog Value object. If checkReliability() has been enabled, then the Reliability property of the object will be retrieved first. If the Reliability property is anything other than RELIABILITY_NO_FAULT_DETECTED, then the method will throw. Reliability checking is disabled by default for performance reasons.

Parameters:

  • objInstance Number

    The Analog Value Object instance.

Returns:

Number:

The floating point value requested.

setAnalogValue

(
  • objInstance
  • value
)

Provided by the e50hx module.

Set the Present_Value property of an Analog Value object. This method will throw on an error.

Parameters:

  • objInstance Number

    The Analog Value Object instance.

  • value Number

    The data value to write.

getAnalogInput

(
  • objInstance
)
Number

Provided by the e50hx module.

Retrieve the Present_Value property of an Analog Input object. If checkReliability() has been enabled, then the Reliability property of the object will be retrieved first. If the Reliability property is anything other than RELIABILITY_NO_FAULT_DETECTED, then the method will throw. Reliability checking is disabled by default for performance reasons.

Parameters:

  • objInstance Number

    The Analog Input Object instance.

Returns:

Number:

the floating point value requested.

getAnalogValueUnits

(
  • objInstance
)
String

Provided by the e50hx module.

Query an Analog Value object for the unit code, translate it into a string and cache the result for future use. Return the BACnet text for the Unit enumeration. Unit enumerations are things like 'kilowatt-hours', 'volts', etc. For Objects which do not have a Units property defined for them, or for which Units has no meaning, 'no-units' will typically be returned and cached for the object.

Parameters:

  • objInstance Number

    The Analog Value Object instance.

Returns:

String:

A string representing the Object's Unit property.

getAnalogInputUnits

(
  • objInstance
)
String

Provided by the e50hx module.

Query an Analog Input object for the unit code, translate it into a string and cache the result for future use. Return the BACnet text for the Unit enumeration. Unit enumerations are things like 'kilowatt-hours', 'volts', etc. For Objects which do not have a Units property defined for them, or for which Units has no meaning, 'no-units' will typically be returned and cached for the object.

Parameters:

  • objInstance Number

    The Analog Input Object instance.

Returns:

String:

A string representing the Object's Unit property.

getBinaryInput

(
  • objInstance
)
Boolean

Provided by the e50hx module.

Retrieve the Present_Value property of a Binary Input object. If checkReliability() has been enabled, then the Reliability property of the object will be retrieved first. If the Reliability property is anything other than RELIABILITY_NO_FAULT_DETECTED, then the method will throw. Reliability checking is disabled by default for performance reasons.

Parameters:

  • objInstance Number

    The Object Instance number to query

Returns:

Boolean:

the boolean point value requested

lookupBinaryInputText

(
  • objInstance
  • value
)
String

Provided by the e50hx module.

Lookup (retrieve if necessary) the Inactive_Text and Active_Text properties of a Binary Input object. These text properties are optional and can provide a string representing a given state (true/false) that can be more informational than just the boolean value the object represents. This is useful in applications that display this data to a user for example. If this text is not present in the object (as it is not required), then a string representation of the value will be returned instead ("active" and "inactive").

Parameters:

  • objInstance Number

    The Object Instance number of the object

  • value Boolean

    The value you want to lookup the text representation for.

Returns:

String:

The string representing the value.

getBinaryInputText

(
  • objInstance
)
String

Provided by the e50hx module.

Return a string representation of the Present_Value property of a BinaryInput object. This method just calls getBinaryInput() on the object, uses lookupBinaryInputText() to lookup the corresponding text value, and returns the result.

Parameters:

  • objInstance Number

    The Object Instance number of the object.

Returns:

String:

The string representing the value.

getBinaryValue

(
  • objInstance
)
Boolean

Provided by the e50hx module.

Retrieve the Present_Value property of a Binary Value object. If checkReliability() has been enabled, then the Reliability property of the object will be retrieved first. If the Reliability property is anything other than RELIABILITY_NO_FAULT_DETECTED, then the method will throw. Reliability checking is disabled by default for performance reasons.

Parameters:

  • objInstance Number

    The Object Instance number to query

Returns:

Boolean:

the boolean point value requested

setBinaryValue

(
  • objInstance
  • value
)

Provided by the e50hx module.

Set the Present_Value property of a Binary Value object. This method will throw on an error.

Parameters:

  • objInstance Number

    The Analog Value Object instance.

  • value Boolean

    The data value to write

lookupBinaryValueText

(
  • objInstance
  • value
)
String

Provided by the e50hx module.

Lookup (retrieve if necessary) the Inactive_Text and Active_Text properties of a Binary Value object. These text properties are optional and can provide a string representing a given state (true/false) that can be more informational than just the boolean value the object represents. This is useful in applications that display this data to a user for example. If this text is not present in the object (as it is not required), then a string representation of the value will be returned instead ("active" and "inactive").

Parameters:

  • objInstance Number

    The Object Instance number of the object.

  • value Boolean

    The value you want to lookup the text representation for.

Returns:

String:

The string representing the value.

getBinaryValueText

(
  • objInstance
)
String

Provided by the e50hx module.

Return a string representation of the Present_Value property of a Binary Value object. This method just calls getBinaryValue() on the object, uses lookupBinaryValueText() to lookup the corresponding text value, and returns the result.

Parameters:

  • objInstance Number

    The Object Instance number of the object.

Returns:

String:

The string representing the value.

getMultiStateValue

(
  • objInstance
)
Number

Provided by the e50hx module.

Retrieve the Present_Value property of a Multi State Value object. If checkReliability() has been enabled, then the Reliability property of the object will be retrieved first. If the Reliability property is anything other than RELIABILITY_NO_FAULT_DETECTED, then the method will throw. Reliability checking is disabled by default for performance reasons.

Parameters:

  • objInstance Number

    The Object Instance number to query.

Returns:

Number:

The Present_Value property of the object.

lookupMultiStateValueText

(
  • objInstance
  • value
)
String

Provided by the e50hx module.

Lookup (retrieve if necessary) the State_Text strings corresponding to the supplied value of a MultiStateValue object. State_Text is an optional property that can provide strings representing a given state that can be more informational than just the unsigned integer the object represents. This is useful in applications that display this data to a user for example. If this text is not present in the object (as it is not required), then a string representation of the integer value will be returned instead.

Parameters:

  • objInstance Number

    The Object Instance number of the object.

  • value Number

    The value you want to lookup the text representation for.

Returns:

String:

The string representing the value.

getMultiStateValueText

(
  • objInstance
)
String

Provided by the e50hx module.

Return a string representation of the Present_Value property of a MultiStateValue object. This method just calls getMultiStateValue() on the object, uses lookupMultiStateValueText() to lookup the corresponding State_Text value, and returns the result.

Parameters:

  • objInstance Number

    The Object Instance number of the object.

Returns:

String:

The string representing the value.

getMultiStateValueMaxStates

(
  • objInstance
)
Number

Provided by the e50hx module.

Return the maximum legal value of a Multi State Value Object. The value represents the highest value the Present_Value porperty of the object will allow.

Parameters:

  • objInstance Number

    The Object Instance number of the object.

Returns:

Number:

The highest Present_Value the object supports.

setMultiStateValue

(
  • objInstance
  • value
)

Provided by the e50hx module.

Set the Present_Value property of a Multi State Value object. The value provided must not be 0, and must not exceed the object's Number_Of_States property. Use getMultiStateValueMaxStates() to determine the maximum value the object supports. This method will throw on an error.

Parameters:

  • objInstance Number

    The MultiStateValue Object instance.

  • value Number

    The data value to write.

checkReliability

(
  • enable
)

Provided by the e50hx module.

Enable or disable reliability checking. When retrieving data, the Present_Value property is returned. There is also an optional property called Reliability that can be checked to ensure that the Present_Value property is currently valid.
Enabling Reliability Checking has the data retrieval functions check for a RELIABILITY_NO_FAULT_DETECTED value for the Reliability property before querying the Present_Value property. If anything other than RELIABILITY_NO_FAULT_DETECTED is set, then the method will throw.
This checking is disabled by default since it will double the number of queries needed to retrieve a given value. In addition, since it is an optional property, calling it for an object that does not support it will also throw. However, if you need to ensure that the values returned are always completely valid as determined by the device firmware, and the objects you are querying support the reliability property, you can enable this.

Parameters:

  • enable Boolean

    true to check Reliability before returning a value, false otherwise.

getDeviceDescription

() String

Provided by the e50hx module.

Query the Device Object of the device and return it's Description property. This typically contains information like the Vendor, model and serial number of a device.

Returns:

String:

A string containing the Device Object's Description property.

getDeviceLocation

() String

Provided by the e50hx module.

Query the Device Object of the device and return it's Location property. This typically contains a string indication of a customer specific value. Use setLocation() to change.

Returns:

String:

A string containing the Device Object's Location property.

setDeviceLocation

(
  • location
)
Boolean

Provided by the e50hx module.

Set the Device Object's Location property. This must be a string containing no more than 63 characters. Not all devices allow setting the location.

Parameters:

  • location String

    The new location to set, if supported.

Returns:

Boolean:

true if the operation succeeded, otherwise false.

getDeviceName

() String

Provided by the e50hx module.

Query the Device Object of the device and return it's Name property. This should contain a unique string value. Use setName() to change. Note, according to the spec, the Device Object Name must be unique within a given BACnet network.

Returns:

String:

A string containing the Object's Name property.

setDeviceName

(
  • name
)
Boolean

Provided by the e50hx module.

Set the Device Object's Name property. This must be a string containing at least one character and no more than 63 characters. Note, according to the spec, the Device Object Name must be unique within a given BACnet network.

Parameters:

  • name String

    The name to set.

Returns:

Boolean:

true if the operation succeeded, false otherwise

getAllErrorString

() String

Provided by the e50hx module.

This is a utility function that will return a string reporting on the various types of errors that can occur in BACnet operation.

Returns:

String:

A string containing the last error message.

getErrorType

() BACNETMSTP::BACERR_TYPE_T

Provided by the e50hx module.

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

Returns:

BACNETMSTP::BACERR_TYPE_T:

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

getRejectReason

() Number

Provided by the e50hx module.

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

Returns:

Number:

The Reject error code.

getRejectString

() String

Provided by the e50hx module.

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

Returns:

String:

The Reject error string.

getAbortReason

() Number

Provided by the e50hx module.

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

Returns:

Number:

The Abort reason code.

getAbortString

() String

Provided by the e50hx module.

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

Returns:

String:

The Abort error string.

getErrorClass

() BACNET_ERROR_CLASS

Provided by the e50hx module.

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

Provided by the e50hx module.

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

Provided by the e50hx module.

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

Provided by the e50hx module.

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

Returns:

String:

A string representing the UPM error.

BACNETUTIL

(
  • targetDeviceObjectID
)
Number

Provided by the t8100 module.

BACNETUTIL constructor

Parameters:

  • targetDeviceObjectID Number

    undefined

Returns:

Number:

initMaster

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

Provided by the t8100 module.

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.

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.

setDebug

(
  • enable
)

Provided by the t8100 module.

Enable some debugging output in this module as well as the BACNETMSTP module. Debugging is disabled by default.

Parameters:

  • enable Boolean

    true to enable, false to disable.

getAnalogValue

(
  • objInstance
)
Number

Provided by the t8100 module.

Retrieve the Present_Value property of an Analog Value object. If checkReliability() has been enabled, then the Reliability property of the object will be retrieved first. If the Reliability property is anything other than RELIABILITY_NO_FAULT_DETECTED, then the method will throw. Reliability checking is disabled by default for performance reasons.

Parameters:

  • objInstance Number

    The Analog Value Object instance.

Returns:

Number:

The floating point value requested.

setAnalogValue

(
  • objInstance
  • value
)

Provided by the t8100 module.

Set the Present_Value property of an Analog Value object. This method will throw on an error.

Parameters:

  • objInstance Number

    The Analog Value Object instance.

  • value Number

    The data value to write.

getAnalogInput

(
  • objInstance
)
Number

Provided by the t8100 module.

Retrieve the Present_Value property of an Analog Input object. If checkReliability() has been enabled, then the Reliability property of the object will be retrieved first. If the Reliability property is anything other than RELIABILITY_NO_FAULT_DETECTED, then the method will throw. Reliability checking is disabled by default for performance reasons.

Parameters:

  • objInstance Number

    The Analog Input Object instance.

Returns:

Number:

the floating point value requested.

getAnalogValueUnits

(
  • objInstance
)
String

Provided by the t8100 module.

Query an Analog Value object for the unit code, translate it into a string and cache the result for future use. Return the BACnet text for the Unit enumeration. Unit enumerations are things like 'kilowatt-hours', 'volts', etc. For Objects which do not have a Units property defined for them, or for which Units has no meaning, 'no-units' will typically be returned and cached for the object.

Parameters:

  • objInstance Number

    The Analog Value Object instance.

Returns:

String:

A string representing the Object's Unit property.

getAnalogInputUnits

(
  • objInstance
)
String

Provided by the t8100 module.

Query an Analog Input object for the unit code, translate it into a string and cache the result for future use. Return the BACnet text for the Unit enumeration. Unit enumerations are things like 'kilowatt-hours', 'volts', etc. For Objects which do not have a Units property defined for them, or for which Units has no meaning, 'no-units' will typically be returned and cached for the object.

Parameters:

  • objInstance Number

    The Analog Input Object instance.

Returns:

String:

A string representing the Object's Unit property.

getBinaryInput

(
  • objInstance
)
Boolean

Provided by the t8100 module.

Retrieve the Present_Value property of a Binary Input object. If checkReliability() has been enabled, then the Reliability property of the object will be retrieved first. If the Reliability property is anything other than RELIABILITY_NO_FAULT_DETECTED, then the method will throw. Reliability checking is disabled by default for performance reasons.

Parameters:

  • objInstance Number

    The Object Instance number to query

Returns:

Boolean:

the boolean point value requested

lookupBinaryInputText

(
  • objInstance
  • value
)
String

Provided by the t8100 module.

Lookup (retrieve if necessary) the Inactive_Text and Active_Text properties of a Binary Input object. These text properties are optional and can provide a string representing a given state (true/false) that can be more informational than just the boolean value the object represents. This is useful in applications that display this data to a user for example. If this text is not present in the object (as it is not required), then a string representation of the value will be returned instead ("active" and "inactive").

Parameters:

  • objInstance Number

    The Object Instance number of the object

  • value Boolean

    The value you want to lookup the text representation for.

Returns:

String:

The string representing the value.

getBinaryInputText

(
  • objInstance
)
String

Provided by the t8100 module.

Return a string representation of the Present_Value property of a BinaryInput object. This method just calls getBinaryInput() on the object, uses lookupBinaryInputText() to lookup the corresponding text value, and returns the result.

Parameters:

  • objInstance Number

    The Object Instance number of the object.

Returns:

String:

The string representing the value.

getBinaryValue

(
  • objInstance
)
Boolean

Provided by the t8100 module.

Retrieve the Present_Value property of a Binary Value object. If checkReliability() has been enabled, then the Reliability property of the object will be retrieved first. If the Reliability property is anything other than RELIABILITY_NO_FAULT_DETECTED, then the method will throw. Reliability checking is disabled by default for performance reasons.

Parameters:

  • objInstance Number

    The Object Instance number to query

Returns:

Boolean:

the boolean point value requested

setBinaryValue

(
  • objInstance
  • value
)

Provided by the t8100 module.

Set the Present_Value property of a Binary Value object. This method will throw on an error.

Parameters:

  • objInstance Number

    The Analog Value Object instance.

  • value Boolean

    The data value to write

lookupBinaryValueText

(
  • objInstance
  • value
)
String

Provided by the t8100 module.

Lookup (retrieve if necessary) the Inactive_Text and Active_Text properties of a Binary Value object. These text properties are optional and can provide a string representing a given state (true/false) that can be more informational than just the boolean value the object represents. This is useful in applications that display this data to a user for example. If this text is not present in the object (as it is not required), then a string representation of the value will be returned instead ("active" and "inactive").

Parameters:

  • objInstance Number

    The Object Instance number of the object.

  • value Boolean

    The value you want to lookup the text representation for.

Returns:

String:

The string representing the value.

getBinaryValueText

(
  • objInstance
)
String

Provided by the t8100 module.

Return a string representation of the Present_Value property of a Binary Value object. This method just calls getBinaryValue() on the object, uses lookupBinaryValueText() to lookup the corresponding text value, and returns the result.

Parameters:

  • objInstance Number

    The Object Instance number of the object.

Returns:

String:

The string representing the value.

getMultiStateValue

(
  • objInstance
)
Number

Provided by the t8100 module.

Retrieve the Present_Value property of a Multi State Value object. If checkReliability() has been enabled, then the Reliability property of the object will be retrieved first. If the Reliability property is anything other than RELIABILITY_NO_FAULT_DETECTED, then the method will throw. Reliability checking is disabled by default for performance reasons.

Parameters:

  • objInstance Number

    The Object Instance number to query.

Returns:

Number:

The Present_Value property of the object.

lookupMultiStateValueText

(
  • objInstance
  • value
)
String

Provided by the t8100 module.

Lookup (retrieve if necessary) the State_Text strings corresponding to the supplied value of a MultiStateValue object. State_Text is an optional property that can provide strings representing a given state that can be more informational than just the unsigned integer the object represents. This is useful in applications that display this data to a user for example. If this text is not present in the object (as it is not required), then a string representation of the integer value will be returned instead.

Parameters:

  • objInstance Number

    The Object Instance number of the object.

  • value Number

    The value you want to lookup the text representation for.

Returns:

String:

The string representing the value.

getMultiStateValueText

(
  • objInstance
)
String

Provided by the t8100 module.

Return a string representation of the Present_Value property of a MultiStateValue object. This method just calls getMultiStateValue() on the object, uses lookupMultiStateValueText() to lookup the corresponding State_Text value, and returns the result.

Parameters:

  • objInstance Number

    The Object Instance number of the object.

Returns:

String:

The string representing the value.

getMultiStateValueMaxStates

(
  • objInstance
)
Number

Provided by the t8100 module.

Return the maximum legal value of a Multi State Value Object. The value represents the highest value the Present_Value porperty of the object will allow.

Parameters:

  • objInstance Number

    The Object Instance number of the object.

Returns:

Number:

The highest Present_Value the object supports.

setMultiStateValue

(
  • objInstance
  • value
)

Provided by the t8100 module.

Set the Present_Value property of a Multi State Value object. The value provided must not be 0, and must not exceed the object's Number_Of_States property. Use getMultiStateValueMaxStates() to determine the maximum value the object supports. This method will throw on an error.

Parameters:

  • objInstance Number

    The MultiStateValue Object instance.

  • value Number

    The data value to write.

checkReliability

(
  • enable
)

Provided by the t8100 module.

Enable or disable reliability checking. When retrieving data, the Present_Value property is returned. There is also an optional property called Reliability that can be checked to ensure that the Present_Value property is currently valid.
Enabling Reliability Checking has the data retrieval functions check for a RELIABILITY_NO_FAULT_DETECTED value for the Reliability property before querying the Present_Value property. If anything other than RELIABILITY_NO_FAULT_DETECTED is set, then the method will throw.
This checking is disabled by default since it will double the number of queries needed to retrieve a given value. In addition, since it is an optional property, calling it for an object that does not support it will also throw. However, if you need to ensure that the values returned are always completely valid as determined by the device firmware, and the objects you are querying support the reliability property, you can enable this.

Parameters:

  • enable Boolean

    true to check Reliability before returning a value, false otherwise.

getDeviceDescription

() String

Provided by the t8100 module.

Query the Device Object of the device and return it's Description property. This typically contains information like the Vendor, model and serial number of a device.

Returns:

String:

A string containing the Device Object's Description property.

getDeviceLocation

() String

Provided by the t8100 module.

Query the Device Object of the device and return it's Location property. This typically contains a string indication of a customer specific value. Use setLocation() to change.

Returns:

String:

A string containing the Device Object's Location property.

setDeviceLocation

(
  • location
)
Boolean

Provided by the t8100 module.

Set the Device Object's Location property. This must be a string containing no more than 63 characters. Not all devices allow setting the location.

Parameters:

  • location String

    The new location to set, if supported.

Returns:

Boolean:

true if the operation succeeded, otherwise false.

getDeviceName

() String

Provided by the t8100 module.

Query the Device Object of the device and return it's Name property. This should contain a unique string value. Use setName() to change. Note, according to the spec, the Device Object Name must be unique within a given BACnet network.

Returns:

String:

A string containing the Object's Name property.

setDeviceName

(
  • name
)
Boolean

Provided by the t8100 module.

Set the Device Object's Name property. This must be a string containing at least one character and no more than 63 characters. Note, according to the spec, the Device Object Name must be unique within a given BACnet network.

Parameters:

  • name String

    The name to set.

Returns:

Boolean:

true if the operation succeeded, false otherwise

getAllErrorString

() String

Provided by the t8100 module.

This is a utility function that will return a string reporting on the various types of errors that can occur in BACnet operation.

Returns:

String:

A string containing the last error message.

getErrorType

() BACNETMSTP::BACERR_TYPE_T

Provided by the t8100 module.

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

Returns:

BACNETMSTP::BACERR_TYPE_T:

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

getRejectReason

() Number

Provided by the t8100 module.

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

Returns:

Number:

The Reject error code.

getRejectString

() String

Provided by the t8100 module.

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

Returns:

String:

The Reject error string.

getAbortReason

() Number

Provided by the t8100 module.

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

Returns:

Number:

The Abort reason code.

getAbortString

() String

Provided by the t8100 module.

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

Returns:

String:

The Abort error string.

getErrorClass

() BACNET_ERROR_CLASS

Provided by the t8100 module.

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

Provided by the t8100 module.

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

Provided by the t8100 module.

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

Provided by the t8100 module.

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

Returns:

String:

A string representing the UPM error.

BACNETUTIL

(
  • targetDeviceObjectID
)
Number

BACNETUTIL constructor

Parameters:

  • targetDeviceObjectID Number

    undefined

Returns:

Number:

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.

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.

setDebug

(
  • enable
)

Enable some debugging output in this module as well as the BACNETMSTP module. Debugging is disabled by default.

Parameters:

  • enable Boolean

    true to enable, false to disable.

getAnalogValue

(
  • objInstance
)
Number

Retrieve the Present_Value property of an Analog Value object. If checkReliability() has been enabled, then the Reliability property of the object will be retrieved first. If the Reliability property is anything other than RELIABILITY_NO_FAULT_DETECTED, then the method will throw. Reliability checking is disabled by default for performance reasons.

Parameters:

  • objInstance Number

    The Analog Value Object instance.

Returns:

Number:

The floating point value requested.

setAnalogValue

(
  • objInstance
  • value
)

Set the Present_Value property of an Analog Value object. This method will throw on an error.

Parameters:

  • objInstance Number

    The Analog Value Object instance.

  • value Number

    The data value to write.

getAnalogInput

(
  • objInstance
)
Number

Retrieve the Present_Value property of an Analog Input object. If checkReliability() has been enabled, then the Reliability property of the object will be retrieved first. If the Reliability property is anything other than RELIABILITY_NO_FAULT_DETECTED, then the method will throw. Reliability checking is disabled by default for performance reasons.

Parameters:

  • objInstance Number

    The Analog Input Object instance.

Returns:

Number:

the floating point value requested.

getAnalogValueUnits

(
  • objInstance
)
String

Query an Analog Value object for the unit code, translate it into a string and cache the result for future use. Return the BACnet text for the Unit enumeration. Unit enumerations are things like 'kilowatt-hours', 'volts', etc. For Objects which do not have a Units property defined for them, or for which Units has no meaning, 'no-units' will typically be returned and cached for the object.

Parameters:

  • objInstance Number

    The Analog Value Object instance.

Returns:

String:

A string representing the Object's Unit property.

getAnalogInputUnits

(
  • objInstance
)
String

Query an Analog Input object for the unit code, translate it into a string and cache the result for future use. Return the BACnet text for the Unit enumeration. Unit enumerations are things like 'kilowatt-hours', 'volts', etc. For Objects which do not have a Units property defined for them, or for which Units has no meaning, 'no-units' will typically be returned and cached for the object.

Parameters:

  • objInstance Number

    The Analog Input Object instance.

Returns:

String:

A string representing the Object's Unit property.

getBinaryInput

(
  • objInstance
)
Boolean

Retrieve the Present_Value property of a Binary Input object. If checkReliability() has been enabled, then the Reliability property of the object will be retrieved first. If the Reliability property is anything other than RELIABILITY_NO_FAULT_DETECTED, then the method will throw. Reliability checking is disabled by default for performance reasons.

Parameters:

  • objInstance Number

    The Object Instance number to query

Returns:

Boolean:

the boolean point value requested

lookupBinaryInputText

(
  • objInstance
  • value
)
String

Lookup (retrieve if necessary) the Inactive_Text and Active_Text properties of a Binary Input object. These text properties are optional and can provide a string representing a given state (true/false) that can be more informational than just the boolean value the object represents. This is useful in applications that display this data to a user for example. If this text is not present in the object (as it is not required), then a string representation of the value will be returned instead ("active" and "inactive").

Parameters:

  • objInstance Number

    The Object Instance number of the object

  • value Boolean

    The value you want to lookup the text representation for.

Returns:

String:

The string representing the value.

getBinaryInputText

(
  • objInstance
)
String

Return a string representation of the Present_Value property of a BinaryInput object. This method just calls getBinaryInput() on the object, uses lookupBinaryInputText() to lookup the corresponding text value, and returns the result.

Parameters:

  • objInstance Number

    The Object Instance number of the object.

Returns:

String:

The string representing the value.

getBinaryValue

(
  • objInstance
)
Boolean

Retrieve the Present_Value property of a Binary Value object. If checkReliability() has been enabled, then the Reliability property of the object will be retrieved first. If the Reliability property is anything other than RELIABILITY_NO_FAULT_DETECTED, then the method will throw. Reliability checking is disabled by default for performance reasons.

Parameters:

  • objInstance Number

    The Object Instance number to query

Returns:

Boolean:

the boolean point value requested

setBinaryValue

(
  • objInstance
  • value
)

Set the Present_Value property of a Binary Value object. This method will throw on an error.

Parameters:

  • objInstance Number

    The Analog Value Object instance.

  • value Boolean

    The data value to write

lookupBinaryValueText

(
  • objInstance
  • value
)
String

Lookup (retrieve if necessary) the Inactive_Text and Active_Text properties of a Binary Value object. These text properties are optional and can provide a string representing a given state (true/false) that can be more informational than just the boolean value the object represents. This is useful in applications that display this data to a user for example. If this text is not present in the object (as it is not required), then a string representation of the value will be returned instead ("active" and "inactive").

Parameters:

  • objInstance Number

    The Object Instance number of the object.

  • value Boolean

    The value you want to lookup the text representation for.

Returns:

String:

The string representing the value.

getBinaryValueText

(
  • objInstance
)
String

Return a string representation of the Present_Value property of a Binary Value object. This method just calls getBinaryValue() on the object, uses lookupBinaryValueText() to lookup the corresponding text value, and returns the result.

Parameters:

  • objInstance Number

    The Object Instance number of the object.

Returns:

String:

The string representing the value.

getMultiStateValue

(
  • objInstance
)
Number

Retrieve the Present_Value property of a Multi State Value object. If checkReliability() has been enabled, then the Reliability property of the object will be retrieved first. If the Reliability property is anything other than RELIABILITY_NO_FAULT_DETECTED, then the method will throw. Reliability checking is disabled by default for performance reasons.

Parameters:

  • objInstance Number

    The Object Instance number to query.

Returns:

Number:

The Present_Value property of the object.

lookupMultiStateValueText

(
  • objInstance
  • value
)
String

Lookup (retrieve if necessary) the State_Text strings corresponding to the supplied value of a MultiStateValue object. State_Text is an optional property that can provide strings representing a given state that can be more informational than just the unsigned integer the object represents. This is useful in applications that display this data to a user for example. If this text is not present in the object (as it is not required), then a string representation of the integer value will be returned instead.

Parameters:

  • objInstance Number

    The Object Instance number of the object.

  • value Number

    The value you want to lookup the text representation for.

Returns:

String:

The string representing the value.

getMultiStateValueText

(
  • objInstance
)
String

Return a string representation of the Present_Value property of a MultiStateValue object. This method just calls getMultiStateValue() on the object, uses lookupMultiStateValueText() to lookup the corresponding State_Text value, and returns the result.

Parameters:

  • objInstance Number

    The Object Instance number of the object.

Returns:

String:

The string representing the value.

getMultiStateValueMaxStates

(
  • objInstance
)
Number

Return the maximum legal value of a Multi State Value Object. The value represents the highest value the Present_Value porperty of the object will allow.

Parameters:

  • objInstance Number

    The Object Instance number of the object.

Returns:

Number:

The highest Present_Value the object supports.

setMultiStateValue

(
  • objInstance
  • value
)

Set the Present_Value property of a Multi State Value object. The value provided must not be 0, and must not exceed the object's Number_Of_States property. Use getMultiStateValueMaxStates() to determine the maximum value the object supports. This method will throw on an error.

Parameters:

  • objInstance Number

    The MultiStateValue Object instance.

  • value Number

    The data value to write.

checkReliability

(
  • enable
)

Enable or disable reliability checking. When retrieving data, the Present_Value property is returned. There is also an optional property called Reliability that can be checked to ensure that the Present_Value property is currently valid.
Enabling Reliability Checking has the data retrieval functions check for a RELIABILITY_NO_FAULT_DETECTED value for the Reliability property before querying the Present_Value property. If anything other than RELIABILITY_NO_FAULT_DETECTED is set, then the method will throw.
This checking is disabled by default since it will double the number of queries needed to retrieve a given value. In addition, since it is an optional property, calling it for an object that does not support it will also throw. However, if you need to ensure that the values returned are always completely valid as determined by the device firmware, and the objects you are querying support the reliability property, you can enable this.

Parameters:

  • enable Boolean

    true to check Reliability before returning a value, false otherwise.

getDeviceDescription

() String

Query the Device Object of the device and return it's Description property. This typically contains information like the Vendor, model and serial number of a device.

Returns:

String:

A string containing the Device Object's Description property.

getDeviceLocation

() String

Query the Device Object of the device and return it's Location property. This typically contains a string indication of a customer specific value. Use setLocation() to change.

Returns:

String:

A string containing the Device Object's Location property.

setDeviceLocation

(
  • location
)
Boolean

Set the Device Object's Location property. This must be a string containing no more than 63 characters. Not all devices allow setting the location.

Parameters:

  • location String

    The new location to set, if supported.

Returns:

Boolean:

true if the operation succeeded, otherwise false.

getDeviceName

() String

Query the Device Object of the device and return it's Name property. This should contain a unique string value. Use setName() to change. Note, according to the spec, the Device Object Name must be unique within a given BACnet network.

Returns:

String:

A string containing the Object's Name property.

setDeviceName

(
  • name
)
Boolean

Set the Device Object's Name property. This must be a string containing at least one character and no more than 63 characters. Note, according to the spec, the Device Object Name must be unique within a given BACnet network.

Parameters:

  • name String

    The name to set.

Returns:

Boolean:

true if the operation succeeded, false otherwise

getAllErrorString

() String

This is a utility function that will return a string reporting on the various types of errors that can occur in BACnet operation.

Returns:

String:

A string containing the last error message.

getErrorType

() BACNETMSTP::BACERR_TYPE_T

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

Returns:

BACNETMSTP::BACERR_TYPE_T:

The last error type to occur, one of the BACNETMSTP::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.