Detailed Description

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.

Public Types
enum	BACERR_TYPE_T { BACERR_TYPE_NONE = 0, BACERR_TYPE_REJECT, BACERR_TYPE_ABORT, BACERR_TYPE_ERROR, BACERR_TYPE_UPM }

enum	BACCMD_TYPE_T { BACCMD_NONE = 0, BACCMD_READ_PROPERTY, BACCMD_WRITE_PROPERTY }

Public Member Functions
void	initMaster (std::string port, int baudRate, int deviceInstanceNumber, int macAddr, int maxMaster=DEFAULT_MAX_MASTER, int maxInfoFrames=1)

bool	readProperty (uint32_t targetDeviceInstanceID, BACNET_OBJECT_TYPE objType, uint32_t objInstance, BACNET_PROPERTY_ID objProperty, uint32_t arrayIndex=BACNET_ARRAY_ALL)

bool	writeProperty (uint32_t targetDeviceInstanceID, BACNET_OBJECT_TYPE objType, uint32_t objInstance, BACNET_PROPERTY_ID objProperty, BACNET_APPLICATION_DATA_VALUE *propValue, uint8_t propPriority=BACNET_NO_PRIORITY, int32_t arrayIndex=BACNET_ARRAY_ALL)

BACNET_APPLICATION_DATA_VALUE	getData (int index=0)

int	getDataNumElements ()

uint8_t	getDataType (int index=0)

float	getDataTypeReal (int index=0)

bool	getDataTypeBoolean (int index=0)

unsigned int	getDataTypeUnsignedInt (int index=0)

int	getDataTypeSignedInt (int index=0)

std::string	getDataTypeString (int index=0)

unsigned int	getDataTypeEnum (int index=0)

BACNET_APPLICATION_DATA_VALUE	createDataReal (float Real)

BACNET_APPLICATION_DATA_VALUE	createDataBool (bool value)

BACNET_APPLICATION_DATA_VALUE	createDataSignedInt (int value)

BACNET_APPLICATION_DATA_VALUE	createDataUnsignedInt (unsigned int value)

BACNET_APPLICATION_DATA_VALUE	createDataString (std::string value)

BACNET_APPLICATION_DATA_VALUE	createDataEnum (uint32_t value)

BACERR_TYPE_T	getErrorType ()

uint8_t	getRejectReason ()

std::string	getRejectString ()

uint8_t	getAbortReason ()

std::string	getAbortString ()

BACNET_ERROR_CLASS	getErrorClass ()

BACNET_ERROR_CODE	getErrorCode ()

std::string	getErrorString ()

std::string	getUPMErrorString ()

bool	isInitialized ()

std::string	getPort ()

uint32_t	getDeviceInstanceID ()

int	getMaxInfoFrames ()

int	getMaxMaster ()

int	getBaudRate ()

int	getMACAddress ()

void	setDebug (bool enable)

Static Public Member Functions
static BACNETMSTP *	instance ()

Protected Member Functions
	BACNETMSTP ()

	~BACNETMSTP ()

void	clearErrors ()

void	initServiceHandlers ()

std::string	string2HexString (std::string input)

bool	dispatchRequest ()

Static Protected Member Functions
static void	handlerError (BACNET_ADDRESS *src, uint8_t invoke_id, BACNET_ERROR_CLASS error_class, BACNET_ERROR_CODE error_code)

static void	handlerAbort (BACNET_ADDRESS *src, uint8_t invoke_id, uint8_t abort_reason, bool server)

static void	handlerReject (BACNET_ADDRESS *src, uint8_t invoke_id, uint8_t reject_reason)

static void	handlerReadPropertyAck (uint8_t service_request, uint16_t service_len, BACNET_ADDRESS src, BACNET_CONFIRMED_SERVICE_ACK_DATA *service_data)

static void	handlerWritePropertyAck (BACNET_ADDRESS *src, uint8_t invoke_id)

Constructor & Destructor Documentation

BACNETMSTP ( )

protected

BACNETMSTP constructor

~BACNETMSTP ( )

protected

BACNETMSTP Destructor

Member Function Documentation

BACNETMSTP * instance ( )

static

Get our singleton instance, initializing it if neccessary. All requests to this class should be done through this instance accessor.

Returns: static pointer to our class instance

Here is the caller graph for this function:

void initMaster	(	std::string	port,
		int	baudRate,
		int	deviceInstanceNumber,
		int	macAddr,
		int	maxMaster = `DEFAULT_MAX_MASTER`,
		int	maxInfoFrames = `1`
	)

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	The serial port that the RS-485 interface is connected to.
baudRate	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	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	This is the MAC address of our BACnet Master. It must be unique on the BACnet segment, and must be between 1-127.
maxMaster	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	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.

Here is the caller graph for this function:

bool readProperty	(	uint32_t	targetDeviceInstanceID,
		BACNET_OBJECT_TYPE	objType,
		uint32_t	objInstance,
		BACNET_PROPERTY_ID	objProperty,
		uint32_t	arrayIndex = `BACNET_ARRAY_ALL`
	)

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	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	This is the BACnet object type of the object you wish to query. It should be one of the BACNET_OBJECT_TYPE values.
objInstance	This is the instance number of the Object you wish to access. It is an integer starting from 1.
objProperty	This is the property of the Object and instance you wish to access. It should be one of the BACNET_PROPERTY_ID values.
arrayIndex	This specifies the index number of an array property. The default is BACNET_ARRAY_ALL.

Returns: true if an error occurred, false otherwise.

Here is the caller graph for this function:

bool writeProperty	(	uint32_t	targetDeviceInstanceID,
		BACNET_OBJECT_TYPE	objType,
		uint32_t	objInstance,
		BACNET_PROPERTY_ID	objProperty,
		BACNET_APPLICATION_DATA_VALUE *	propValue,
		uint8_t	propPriority = `BACNET_NO_PRIORITY`,
		int32_t	arrayIndex = `BACNET_ARRAY_ALL`
	)

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	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	This is the BACnet object type of the object you wish to query. It should be one of the BACNET_OBJECT_TYPE values.
objInstance	This is the instance number of the Object you wish to access. It is an integer starting from 1.
objProperty	This is the property of the Object and instance you wish to access. It should be one of the BACNET_PROPERTY_ID values.
propValue	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	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	This specifies the index number of an array property. The default is BACNET_ARRAY_ALL.

Returns: true if an error occurred, false otherwise.

Here is the caller graph for this function:

BACNET_APPLICATION_DATA_VALUE getData ( int index = 0 )

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

Parameters

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

Returns: a BACNET_APPLICATION_DATA_VALUE structure containing the returned data.

int getDataNumElements ( )

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: The number of data elements received.

uint8_t getDataType ( int index = 0 )

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 into the list of returned data. 0 (first) is the default.

Returns: A BACNET_APPLICATION_TAG_* value

float getDataTypeReal ( int index = 0 )

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 into the list of returned data. 0 (first) is the default.

Returns: A floating point value representing the returned data

Here is the caller graph for this function:

bool getDataTypeBoolean ( int index = 0 )

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 into the list of returned data. 0 (first) is the default.

Returns: A boolean value representing the returned data

unsigned int getDataTypeUnsignedInt ( int index = 0 )

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 into the list of returned data. 0 (first) is the default.

Returns: An unsigned int value representing the returned data

Here is the caller graph for this function:

int getDataTypeSignedInt ( int index = 0 )

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 into the list of returned data. 0 (first) is the default.

Returns: A signed int value representing the returned data

std::string getDataTypeString ( int index = 0 )

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 into the list of returned data. 0 (first) is the default.

Returns: A string value representing the returned data

Here is the caller graph for this function:

unsigned int getDataTypeEnum ( int index = 0 )

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 into the list of returned data. 0 (first) is the default.

Returns: An unsigned int representing a BACnet enumerant

Here is the caller graph for this function:

BACNET_APPLICATION_DATA_VALUE createDataReal ( float Real )

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

value The floating point value to initialize the structure to.

Returns: An initialized structure containing the value

Here is the caller graph for this function:

BACNET_APPLICATION_DATA_VALUE createDataBool ( bool 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 The boolean value to initialize the structure to.

Returns: An initialized structure containing the value

BACNET_APPLICATION_DATA_VALUE createDataSignedInt ( int 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 The signed integer value to initialize the structure to.

Returns: An initialized structure containing the value

BACNET_APPLICATION_DATA_VALUE createDataUnsignedInt ( unsigned int 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 The unsigned integer value to initialize the structure to.

Returns: An initialized structure containing the value

Here is the caller graph for this function:

BACNET_APPLICATION_DATA_VALUE createDataString ( std::string 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 The character string value to initialize the structure to.

Returns: An initialized structure containing the value

Here is the caller graph for this function:

BACNET_APPLICATION_DATA_VALUE createDataEnum ( uint32_t 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 The BACnet enumeration to initialize the structure to.

Returns: An initialized structure containing the value

Here is the caller graph for this function:

BACERR_TYPE_T getErrorType ( )

inline

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

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

Here is the caller graph for this function:

uint8_t getRejectReason ( )

inline

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

Returns: The Reject error code.

Here is the caller graph for this function:

std::string getRejectString ( )

inline

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

Returns: The Reject error string.

Here is the caller graph for this function:

uint8_t getAbortReason ( )

inline

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

Returns: The Abort reason code.

Here is the caller graph for this function:

std::string getAbortString ( )

inline

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

Returns: The Abort error string.

Here is the caller graph for this function:

BACNET_ERROR_CLASS getErrorClass ( )

inline

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

Returns: One of the BACNET_ERROR_CLASS error class codes

Here is the caller graph for this function:

BACNET_ERROR_CODE getErrorCode ( )

inline

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

Returns: One of the BACNET_ERROR_CODE error codes

Here is the caller graph for this function:

std::string getErrorString ( )

inline

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

Returns: A string representing the BACnet error class and code.

Here is the caller graph for this function:

std::string getUPMErrorString ( )

inline

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

Returns: A string representing the UPM error.

Here is the caller graph for this function:

bool isInitialized ( )

inline

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

Returns: true if the master is initialized, false otherwise

Here is the caller graph for this function:

std::string getPort ( )

inline

Return the port that was specified to initMaster().

Returns: The port specified to initMaster().

uint32_t getDeviceInstanceID ( )

inline

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

Returns: The Object Device Instance ID for our Master.

int getMaxInfoFrames ( )

inline

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

Returns: The maxInfoFrames parameter specified to initMaster().

int getMaxMaster ( )

inline

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

Returns: The maxMaster parameter specified to initMaster().

int getBaudRate ( )

inline

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

Returns: The baud rate parameter specified to initMaster().

int getMACAddress ( )

inline

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

Returns: The MAC address parameter specified to initMaster().

void setDebug ( bool enable )

Enable or disable debugging output.

Parameters

enable true to enable debugging, false otherwise

Here is the caller graph for this function:

Collaboration diagram for BACNETMSTP:

[legend]

The documentation for this class was generated from the following files:

/iotdk/jenkins/workspace/upm-doc-stable/src/bacnetmstp/bacnetmstp.hpp
/iotdk/jenkins/workspace/upm-doc-stable/src/bacnetmstp/bacnetmstp.cxx

Detailed Description

Public Types

Public Member Functions

Static Public Member Functions

Protected Member Functions

Static Protected Member Functions

Constructor & Destructor Documentation

Member Function Documentation