alexey.zholtikov/upm
1
0
Fork 0
mirror of https://github.com/eclipse/upm.git synced 2025-03-24 09:20:39 +03:00
Code Issues Actions Packages Projects Releases Wiki Activity
upm/src/bacnetmstp/bacnetutil.hpp
Jon Trulson b7f038de3d bacnetmstp: add new bacnetutil class to bacnetmstp UPM library 
There is some functionality that will always be needed for BACnet
drivers.  Here we create a new bacnetutil class, built as part of the
bacnetmstp library that can handle much of the data handling and setup
a BACnet driver will need.

The idea is that any BACnet functionality needed, that is not
device-specific, should be added to this class for all drivers to use.

The intent is that all BACnet drivers will inherit from this class.

Signed-off-by: Jon Trulson <jtrulson@ics.com>
2016-06-14 16:53:17 -06:00

560 lines
21 KiB
C++
Raw Blame History

/*
* Author: Jon Trulson <jtrulson@ics.com>
* Copyright (c) 2016 Intel Corporation.
*
* Permission is hereby granted, free of charge, to any person obtaining
* a copy of this software and associated documentation files (the
* "Software"), to deal in the Software without restriction, including
* without limitation the rights to use, copy, modify, merge, publish,
* distribute, sublicense, and/or sell copies of the Software, and to
* permit persons to whom the Software is furnished to do so, subject to
* the following conditions:
*
* The above copyright notice and this permission notice shall be
* included in all copies or substantial portions of the Software.
*
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
* EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
* MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
* NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
* LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
* OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
* WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
*/
#pragma once
#include <string>
#include <map>
#include <vector>
#include "bacnetmstp.hpp"
namespace upm {
/**
* @library bacnetmstp
* @comname UPM Utility API for BACnet
* @con uart
*
* @brief UPM Utility API for BACnet
*
* 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.
*/
class BACNETUTIL {
public:
/**
* BACNETUTIL constructor
*
*/
BACNETUTIL(uint32_t targetDeviceObjectID);
/**
* BACNETUTIL Destructor
*/
virtual ~BACNETUTIL();
/**
* 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.
*
* @param port The serial port that the RS-485 interface is
* connected to.
* @param 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.
* @param 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.
* @param macAddr This is the MAC address of our BACnet Master.
* It must be unique on the BACnet segment, and must be between
* 1-127.
* @param 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.
* @param 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.
*/
virtual void initMaster(std::string port, int baudRate,
int deviceInstanceNumber,
int macAddr, int maxMaster=DEFAULT_MAX_MASTER,
int maxInfoFrames=1);
/**
* Enable some debugging output in this module as well as the
* BACNETMSTP module. Debugging is disabled by default.
*
* @param enable true to enable, false to disable.
*/
virtual void setDebug(bool enable);
/**
* 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.
*
* @param objInstance The Analog Value Object instance.
* @return The floating point value requested.
*/
virtual float getAnalogValue(uint32_t objInstance);
/**
* Set the Present_Value property of an Analog Value object. This
* method will throw on an error.
*
* @param objInstance The Analog Value Object instance.
* @param value The data value to write.
*/
virtual void setAnalogValue(uint32_t objInstance,
float value);
/**
* 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.
*
* @param objInstance The Analog Input Object instance.
* @return the floating point value requested.
*/
virtual float getAnalogInput(uint32_t objInstance);
/**
* 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.
*
* @param objInstance The Analog Value Object instance.
* @return A string representing the Object's Unit property.
*/
virtual std::string getAnalogValueUnits(uint32_t objInstance);
/**
* 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.
*
* @param objInstance The Analog Input Object instance.
* @return A string representing the Object's Unit property.
*/
virtual std::string getAnalogInputUnits(uint32_t objInstance);
/**
* 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.
*
* @param objInstance The Object Instance number to query
* @return the boolean point value requested
*/
virtual bool getBinaryInput(uint32_t objInstance);
/**
* 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").
*
* @param objInstance The Object Instance number of the object
* @param value The value you want to lookup the text
* representation for.
* @return The string representing the value.
*/
virtual std::string lookupBinaryInputText(uint32_t objInstance, bool value);
/**
* 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.
*
* @param objInstance The Object Instance number of the object.
* @return The string representing the value.
*/
virtual std::string getBinaryInputText(uint32_t objInstance);
/**
* 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.
*
* @param objInstance The Object Instance number to query
* @return the boolean point value requested
*/
virtual bool getBinaryValue(uint32_t objInstance);
/**
* Set the Present_Value property of a Binary Value object. This
* method will throw on an error.
*
* @param objInstance The Analog Value Object instance.
* @param value The data value to write
*/
virtual void setBinaryValue(uint32_t objInstance,
bool value);
/**
* 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").
*
* @param objInstance The Object Instance number of the object.
* @param value The value you want to lookup the text
* representation for.
* @return The string representing the value.
*/
virtual std::string lookupBinaryValueText(uint32_t objInstance, bool value);
/**
* 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.
*
* @param objInstance The Object Instance number of the object.
* @return The string representing the value.
*/
virtual std::string getBinaryValueText(uint32_t objInstance);
/**
* 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.
*
* @param objInstance The Object Instance number to query.
* @return The Present_Value property of the object.
*/
virtual unsigned int getMultiStateValue(uint32_t objInstance);
/**
* 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.
*
* @param objInstance The Object Instance number of the object.
* @param value The value you want to lookup the text
* representation for.
* @return The string representing the value.
*/
virtual std::string lookupMultiStateValueText(uint32_t objInstance,
unsigned int value);
/**
* 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.
*
* @param objInstance The Object Instance number of the object.
* @return The string representing the value.
*/
virtual std::string getMultiStateValueText(uint32_t objInstance);
/**
* 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.
*
* @param objInstance The Object Instance number of the object.
* @return The highest Present_Value the object supports.
*/
virtual unsigned int getMultiStateValueMaxStates(uint32_t objInstance);
/**
* 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.
*
* @param objInstance The MultiStateValue Object instance.
* @param value The data value to write.
*/
virtual void setMultiStateValue(uint32_t objInstance,
unsigned int value);
/**
* 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.
*
* @param enable true to check Reliability before returning a
* value, false otherwise.
*/
virtual void checkReliability(bool enable)
{
m_checkReliability = enable;
};
/**
* 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.
*
* @return A string containing the Device Object's Description property.
*/
virtual std::string getDeviceDescription();
/**
* 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.
*
* @return A string containing the Device Object's Location property.
*/
virtual std::string getDeviceLocation();
/**
* 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.
*
* @param location The new location to set, if supported.
* @return true if the operation succeeded, otherwise false.
*/
virtual bool setDeviceLocation(std::string location);
/**
* 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.
*
* @return A string containing the Object's Name property.
*/
virtual std::string getDeviceName();
/**
* 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.
*
* @param name The name to set.
* @return true if the operation succeeded, false otherwise
*/
virtual bool setDeviceName(std::string name);
/**
* This is a utility function that will return a string reporting
* on the various types of errors that can occur in BACnet
* operation.
*
* @return A string containing the last error message.
*/
virtual std::string getAllErrorString();
/**
* Return an enumration of the last error type to occur. The
* value returned will be one of the BACNETMSTP::BACERR_TYPE_T
* values.
*
* @return The last error type to occur, one of the
* BACNETMSTP::BACERR_TYPE_T values.
*/
virtual BACNETMSTP::BACERR_TYPE_T getErrorType();
/**
* In the event of a BACnet Reject error, return the error code.
*
* @return The Reject error code.
*/
virtual uint8_t getRejectReason();
/**
* In the event of a BACnet Reject error, return the error string.
*
* @return The Reject error string.
*/
virtual std::string getRejectString();
/**
* In the event of a BACnet Abort error, return the Abort reason code.
*
* @return The Abort reason code.
*/
virtual uint8_t getAbortReason();
/**
* In the event of a BACnet Abort error, return the Abort string.
*
* @return The Abort error string.
*/
virtual std::string getAbortString();
/**
* In the event of a general BACnet error, return the BACnet error class.
*
* @return One of the BACNET_ERROR_CLASS error class codes
*/
virtual BACNET_ERROR_CLASS getErrorClass();
/**
* In the event of a general BACnet error, return the BACnet error code.
*
* @return One of the BACNET_ERROR_CODE error codes
*/
virtual BACNET_ERROR_CODE getErrorCode();
/**
* In the event of a general BACnet error, return the BACnet error
* string.
*
* @return A string representing the BACnet error class and code.
*/
virtual std::string getErrorString();
/**
* In the event of a non-BACnet UPM error, return a string
* describing the error.
*
* @return A string representing the UPM error.
*/
virtual std::string getUPMErrorString();
protected:
// update our stored info for an MSV
virtual void updateMultiStateValueInfo(uint32_t objInstance);
// delete our stored info for an MSV
virtual void deleteMultiStateValueInfo(uint32_t objInstance);
// update our stored info for a BV
virtual void updateBinaryValueInfo(uint32_t objInstance);
// delete our stored info for a BV
virtual void deleteBinaryValueInfo(uint32_t objInstance);
// update our stored info for a BI
virtual void updateBinaryInputInfo(uint32_t objInstance);
// delete our stored info for a BI
virtual void deleteBinaryInputInfo(uint32_t objInstance);
// also enable mstp debugging in BACNETMSTP
bool m_debugging;
// whether or not to verify reliability before reading a value.
bool m_checkReliability;
// our target Device Object ID
uint32_t m_targetDeviceObjectID;
// a copy of the BACNETMSTP singleton instance pointer
BACNETMSTP* m_instance;
// are we initialized?
bool m_initialized;
// storage for Binary Input and Binary Value Data. This will
// generate SWIG warnings which can be ignored as we do not expose
// this struct outside the class.
typedef struct {
std::string inactiveText;
std::string activeText;
} binaryData_t;
typedef std::map<uint32_t, binaryData_t> binaryInfo_t;
// storage for binary input/value information
binaryInfo_t m_bvInfo;
binaryInfo_t m_biInfo;
// storage for multi-state data. This will generate SWIG
// warnings which can be ignored as we do not expose this struct
// outside the class.
typedef struct {
unsigned int numStates;
std::vector<std::string>stateList;
} multiStateData_t;
// our information storage for MSV's
typedef std::map<uint32_t, multiStateData_t> multiStateInfo_t;
multiStateInfo_t m_msvInfo;
// Unit cache for AV
typedef std::map<uint32_t, std::string> avCacheMap_t;
avCacheMap_t m_avUnitCache;
// Unit cache for AI
typedef std::map<uint32_t, std::string> aiCacheMap_t;
aiCacheMap_t m_aiUnitCache;
private:
};
}
Reference in New Issue View Git Blame Copy Permalink