UPM API for the Veris E50HX Energy Meter. More...

Detailed Description

ID: e50hx
Name: UPM API for the Veris E50HX Energy Meters
Category: electic
Manufacturer: veris
Connection: uart
Link: http://www.veris.com/Item/E50H5.aspx

This module implements support for the Veris E50H2 and E50H5 BACnet Energy Meters.

From the datasheet: The E50H5 BACnet MS/TP DIN Rail Meter with Data Logging combines exceptional performance and easy installation to deliver a cost-effective solution for power monitoring applications. Native serial communication via BACnet MS/TP provides complete accessibility of all measurements to your Building Automation System The data logging capability protects data in the event of a power failure. The E50H5 can be easily installed on standard DIN rail, surface mounted or contained in an optional NEMA 4 enclosure, as needed. The front-panel LCD display makes device installation and setup easy and provides local access to the full set of detailed measurements.

This module was developed using the upm::BACNETMSTP module, based on libbacnet-stack 0.8.3. Both libbacnet 0.8.3 and the upm::BACNETMSTP libraries must be present in order to build this module. This driver was developed on the E50H5. The Trend Log functionality is not currently supported.

The Binary Input Objects are also not supported as these are only used for the Alarm bits which are already available from Analog Input Object 52 as an alarm bitfield incorporating all of the supported alarm indicators.

It was connected using an RS232->RS485 interface. You cannot use the built in MCU TTL UART pins for accessing this device – you must use a full Serial RS232->RS485 or USB-RS485 interface connected via USB.

  // You will need to edit this example to conform to your site and your
  // devices, specifically the Device Object Instance ID passed to the
  // constructor, and the arguments to initMaster() that are
  // appropriate for your BACnet network.
  string defaultDev = "/dev/ttyUSB0";
  // if an argument was specified, use it as the device instead
  if (argc > 1)
    defaultDev = string(argv[1]);
  cout << "Using device " << defaultDev << endl;
  cout << "Initializing..." << endl;
  // Instantiate an E50HX object for an E50HX device that has 1075425
  // as it's unique Device Object Instance ID.  NOTE: You will
  // certainly want to change this to the correct value for your
  // device(s).
  E50HX *sensor = new E50HX(1075425);
  // Initialize our BACnet master, if it has not already been
  // initialized, with the device and baudrate, choosing 1000001 as
  // our unique Device Object Instance ID, 2 as our MAC address and
  // using default values for maxMaster and maxInfoFrames
  sensor->initMaster(defaultDev, 38400, 1000001, 2);
  // Uncomment to enable debugging output
  // sensor->setDebug(true);
  cout << endl;
  cout << "Device Description: " << sensor->getDescription() << endl;
  cout << "Device Location: " << sensor->getLocation() << endl;
  cout << endl;
  // update and print a few values every 5 seconds
  while (shouldRun)
    {
      cout << "System Voltage: "
           << sensor->getAnalogValue(E50HX::AV_System_Voltage)
           << " " << sensor->getAnalogValueUnits(E50HX::AV_System_Voltage)
           << endl;
      cout << "System Type: "
           << sensor->getAnalogValue(E50HX::AV_System_Type)
           << endl;
      cout << "Energy Consumption: " << sensor->getAnalogInput(E50HX::AI_Energy)
           << " " << sensor->getAnalogInputUnits(E50HX::AI_Energy)
           << endl;
      cout << "Power Up Counter: "
           << sensor->getAnalogInput(E50HX::AI_Power_Up_Count)
           << endl;
      cout << endl;
      sleep(5);
    }
  cout << "Exiting..." << endl;
  delete sensor;

Public Types
enum	ANALOG_VALUES_T : uint32_t { AV_Config = 1, AV_System_Type = 2, AV_CT_Ratio_Primary = 3, AV_CT_Ratio_Secondary = 4, AV_PT_Ratio = 5, AV_System_Voltage = 6, AV_Display_Units = 7, AV_Phase_Loss_Voltage_Threshold = 8, AV_Phase_Loss_Imbalance_Threshold = 9, AV_Subintervals = 10, AV_Subinterval_Length = 11 }

enum	ANALOG_INPUTS_T : uint32_t { AI_Energy = 1, AI_kW_Total = 2, AI_kVAR_Total = 3, AI_kVA_Total = 4, AI_PF_Total = 5, AI_Volts_LL_Avg = 6, AI_Volts_LN_Avg = 7, AI_Current_Avg = 8, AI_kW_A = 9, AI_kW_B = 10, AI_kW_C = 11, AI_PF_A = 12, AI_PF_B = 13, AI_PF_C = 14, AI_Volts_AB = 15, AI_Volts_BC = 16, AI_Volts_AC = 17, AI_Volts_AN = 18, AI_Volts_BN = 19, AI_Volts_CN = 20, AI_Current_A = 21, AI_Current_B = 22, AI_Current_C = 23, AI_Frequency = 25, AI_kVAh = 26, AI_kVARh = 27, AI_kVA_A = 28, AI_kVA_B = 29, AI_kVA_C = 30, AI_kVAR_A = 31, AI_kVAR_B = 32, AI_kVAR_C = 33, AI_KW_Present_Demand = 34, AI_KVAR_Present_Demand = 35, AI_KWA_Present_Demand = 36, AI_KW_Max_Demand = 37, AI_KVAR_Max_Demand = 38, AI_KVA_Max_Demand = 39, AI_Pulse_Count_1 = 40, AI_Pulse_Count_2 = 41, AI_KWH_A = 42, AI_KWH_B = 43, AI_KWH_C = 44, AI_Max_Power = 45, AI_Energy_Resets = 47, AI_Power_Up_Count = 50, AI_Output_Config = 51, AI_Alarm_Bitmap = 52 }

enum	ALARM_BITS_T : uint16_t { ALARM_Volts_Error_A = 0x0001, ALARM_Volts_Error_B = 0x0002, ALARM_Volts_Error_C = 0x0004, ALARM_Current_Error_A = 0x0008, ALARM_Current_Error_B = 0x0010, ALARM_Current_Error_C = 0x0020, ALARM_Frequency_Error = 0x0040, ALARM_Reserved_0 = 0x0080, ALARM_Phase_Loss_A = 0x0100, ALARM_Phase_Loss_B = 0x0200, ALARM_Phase_Loss_C = 0x0400, ALARM_Power_Factor_A = 0x0800, ALARM_Power_Factor_B = 0x1000, ALARM_Power_Factor_C = 0x2000, ALARM_RTC_RESET = 0x4000 }

enum	CFG_VALUES_T { CFG_CLR_ENERGY_ACCUM = 30078, CFG_NEW_DSI = 21211, CFG_RESET_MAX_TO_PRESENT = 21212, CFG_CLEAR_PULSE_COUNTERS = 16498 }

enum	SYSTEM_TYPES_T { SYSTYPE_SINGLE_PHASE_AN = 10, SYSTYPE_SINGLE_PHASE_AB = 11, SYSTYPE_SPLIT_PHASE_ABN = 12, SYSTYPE_3PHASE_ABC = 31, SYSTYPE_3PHASE_ABCN = 40 }

enum	CT_SECONDARY_T { CT_RATIO_SECONDARY_1 = 1, CT_RATIO_SECONDARY_3 = 3 }

enum	DISP_UNITS_T { DISP_UNITS_IEC = 0, DISP_UNITS_IEEE = 1 }

Public Member Functions
	E50HX (uint32_t targetDeviceObjectID)

	~E50HX ()

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

void	setDebug (bool enable)

float	getAnalogValue (ANALOG_VALUES_T objInstance)

float	getAnalogInput (ANALOG_INPUTS_T objInstance)

bool	writeConfig (CFG_VALUES_T config)

bool	writeSystemType (SYSTEM_TYPES_T systype)

bool	writeCTRatioPrimary (float ctRatio)

bool	writeCTRatioSecondary (CT_SECONDARY_T ctRatio)

bool	writePTRatio (float ptRatio)

bool	writeSystemVoltage (float sysVolts)

bool	writeDisplayUnits (DISP_UNITS_T dispUnits)

bool	writePhaseLossVT (float phaseLoss)

bool	writePhaseLossIT (float phaseLoss)

std::string	getAnalogValueUnits (ANALOG_VALUES_T objInstance)

std::string	getAnalogInputUnits (ANALOG_INPUTS_T objInstance)

uint16_t	getAlarmBits ()

void	checkReliability (bool enable)

std::string	getDescription ()

std::string	getLocation ()

bool	setLocation (std::string location)

std::string	getAllErrorString ()

BACNETMSTP::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 ()

Data Fields
const float	RETURN_ERROR = -1.0

const float	RETURN_UNRELIABLE = -2.0

Protected Attributes
BACNETMSTP *	m_instance

uint32_t	m_targetDeviceObjectID

bool	m_initialized

Constructor & Destructor Documentation

E50HX ( uint32_t targetDeviceObjectID )

E50HX constructor

Parameters

targetDeviceObjectID the unique Instance ID of the Device Object. This number is used to uniquely identify devices on the BACnet network, and ranges from 1 to 4194302. This is not the device's MAC address, though on some devices, the MAC address may be used as part of this number. On the E50HX, this number is randomly generated per device, and you can see this number (or change it) on the BACnet config screens on the LCD.

Here is the call graph for this function:

~E50HX ( )

E50HX Destructor

Member Function Documentation

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.

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 call graph for this function:

void setDebug ( bool enable )

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

Parameters

enable true to enable, false to disable.

Here is the call graph for this function:

Here is the caller graph for this function:

float getAnalogValue ( ANALOG_VALUES_T objInstance )

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 RETURN_UNRELIABLE value will be returned. Reliability checking is disabled by default for performance reasons.

Parameters

objInstance One of the ANALOG_VALUES_T values.

Returns: the floating point value requested

Here is the call graph for this function:

float getAnalogInput ( ANALOG_INPUTS_T objInstance )

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 RETURN_UNRELIABLE value will be returned. Reliability checking is disabled by default for performance reasons.

Parameters

objInstance One of the ANALOG_INPUTS_T values.

Returns: the floating point value requested

Here is the call graph for this function:

Here is the caller graph for this function:

bool writeConfig ( CFG_VALUES_T config )

Write one of several 'magic' numbers to the configuration object (AV1). This is used to clear certain counters, reset the accumulated Energy consumption values, etc.

Parameters

config One of the CFG_VALUES_T values

Returns: true if the operation suceeded, false if there was an error.

Here is the call graph for this function:

bool writeSystemType ( SYSTEM_TYPES_T systype )

Set the System Type of the device. This defines the voltage lines you have connected.

Parameters

systype One of the SYSTEM_TYPES_T values.

Returns: true if the operation suceeded, false if there was an error.

Here is the call graph for this function:

bool writeCTRatioPrimary ( float ctRatio )

Set the Primary CT ratio. See the datasheet for details.

Parameters

ctRatio A floating point value between 5-32000

Returns: true if the operation suceeded, false if there was an error.

Here is the call graph for this function:

bool writeCTRatioSecondary ( CT_SECONDARY_T ctRatio )

Set the Secondary CT ratio. See the datasheet for details.

Parameters

ctRatio One of the CT_SECONDARY_T values.

Returns: true if the operation suceeded, false if there was an error.

Here is the call graph for this function:

bool writePTRatio ( float ptRatio )

Set the PT ratio. See the datasheet for details.

Parameters

ptRatio A floating point value between 0.01-320.0

Returns: true if the operation suceeded, false if there was an error.

Here is the call graph for this function:

bool writeSystemVoltage ( float sysVolts )

Set the System Voltage parmeter. See the datasheet for details.

Parameters

sysVolts A floating point value between 82.0-32000.0

Returns: true if the operation suceeded, false if there was an error.

Here is the call graph for this function:

bool writeDisplayUnits ( DISP_UNITS_T dispUnits )

Set the LCD Display Units in IEC or IEEE format.

Parameters

dispUnits One of the DISP_UNITS_T values.

Returns: true if the operation suceeded, false if there was an error.

Here is the call graph for this function:

bool writePhaseLossVT ( float phaseLoss )

Set the Phase Loss Voltage Threshold. See the datasheet for details.

Parameters

dispUnits A floating point value between 1.0-99.0

Returns: true if the operation suceeded, false if there was an error.

Here is the call graph for this function:

bool writePhaseLossIT ( float phaseLoss )

Set the Phase Loss Imbalance Threshold. See the datasheet for details.

Parameters

dispUnits A floating point value between 1.0-99.0

Returns: true if the operation suceeded, false if there was an error.

Here is the call graph for this function:

string getAnalogValueUnits ( ANALOG_VALUES_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.

Parameters

objInstance One of the ANALOG_VALUES_T values.

Returns: A string representing the Object's Unit property.

Here is the call graph for this function:

string getAnalogInputUnits ( ANALOG_INPUTS_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.

Parameters

objInstance One of the ANALOG_INPUTS_T values.

Returns: A string representing the Object's Unit property.

Here is the call graph for this function:

uint16_t getAlarmBits ( )

Query the AI52 Object and return a bitmask of current Alarms. Compare against ALARM_BITS_T to determine what conditions are signaling an alarm. Alarm conditions will clear on their own as soon as the cause is rectified.

Returns: A bitmask of values from ALARM_BITS_T indicating current alarm conditions.

Here is the call graph for this function:

void checkReliability ( bool enable )

inline

Enable or disable reliability checking. By default, when using getAnalogValue() or getAnalogInput() the Present_Value property is returned. There is also a property called Reliability that can be checked to ensure that the Present_Value property is currently valid.

Enabling Reliability Checking has these 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 these functions will return RETURN_UNRELIABLE rather than the Present_Value.

This checking is disabled by default since it will double the number of queries needed to retrieve a given value. However, if you need to ensure that the values returned are always completely valid as determined by the device firmware, you should enable this.

Parameters

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

Here is the caller graph for this function:

string getDescription ( )

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: A string containing the Device Object's Description property.

Here is the call graph for this function:

string getLocation ( )

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

Returns: A string containing the Device Object's Location property.

Here is the call graph for this function:

bool setLocation ( std::string location )

Set the Device Object's Location property. This must be a string containing no more than 63 characters.

Returns: true if the operation succeeded, false otherwise

Here is the call graph for this function:

string getAllErrorString ( )

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

Returns: A string containing the last error message.

Here is the call graph for this function:

Here is the caller graph for this function:

BACNETMSTP::BACERR_TYPE_T getErrorType ( )

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

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

Here is the call graph for this function:

uint8_t getRejectReason ( )

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

Returns: The Reject error code.

Here is the call graph for this function:

std::string getRejectString ( )

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

Returns: The Reject error string.

Here is the call graph for this function:

Here is the caller graph for this function:

uint8_t getAbortReason ( )

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

Returns: The Abort reason code.

Here is the call graph for this function:

std::string getAbortString ( )

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

Returns: The Abort error string.

Here is the call graph for this function:

Here is the caller graph for this function:

BACNET_ERROR_CLASS getErrorClass ( )

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 call graph for this function:

BACNET_ERROR_CODE getErrorCode ( )

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 call graph for this function:

std::string getErrorString ( )

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 call graph for this function:

Here is the caller graph for this function:

std::string getUPMErrorString ( )

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 call graph for this function:

Here is the caller graph for this function:

Collaboration diagram for E50HX:

[legend]

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

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

Detailed Description

Public Types

Public Member Functions

Data Fields

Protected Attributes

Constructor & Destructor Documentation

Member Function Documentation