Opto HART Toolkit
A .NET/MONO toolkit for using Opto22 HART modules
 All Classes Namespaces Functions Properties Pages
Opto22.HART.HART Class Reference

Enables HART communication with a single Opto 22 HART I/O module channel. More...

Public Member Functions

 HART (String address, int moduleNumber, int channelNumber)
 A constructor for the HART class. More...
 
 HART (String address, int moduleNumber, int channelNumber, int port)
 A constructor for the HART class. More...
 
void Dispose ()
 
int SendReceive (byte[] deviceAddress, byte commandNumber, ref byte[] txHartData, out byte[] rxHartData, out byte[] rxMessage, int timeoutMS)
 Send and receive a HART command in a single operation. More...
 
int Receive (out byte[]rxHartData, out byte[] rxMessage, int timeoutMS)
 Receive a message from the HART module. More...
 
void PointConfig ()
 Send the current Config to the HART module. More...
 
void FindDevices (byte startAddress, byte stopAddress, out byte[] PollingAddresses, out byte[][] UniqueAddresses)
 Searches the bus for HART devices and reports their unique Addresses. More...
 
void FindOneDevice (byte PollingAddress, out byte[] UniqueAddress)
 Finds the unique address of a device with a known polling address. More...
 
int ClearRxBacklog (out byte[] rxHartData, out byte[] rxMessage, int timeoutMS)
 Clears any messages that have not been retrieved from the HART module. More...
 
void PackBytes (ref byte[] txBuffer, byte[] bytesToPack, int startIndex)
 Copies a byte array to another, placing it at the specified index. More...
 
void Packi08 (ref byte[] txBuffer, byte byteToPack, int index)
 Copies an unsigned byte to txBuffer[index]. More...
 
void Packi08 (ref byte[] txBuffer, sbyte byteToPack, int index)
 Copies a signed byte to txBuffer[index]. More...
 
void Packi16 (ref byte[] txBuffer, UInt16 i16ToPack, int index)
 Copies the bytes of a UInt16 to txBuffer starting at index. More...
 
void Packi16 (ref byte[] txBuffer, Int16 i16ToPack, int index)
 Copies the bytes of a Int16 to txBuffer starting at index. More...
 
void Packi24 (ref byte[] txBuffer, UInt32 i24ToPack, int index)
 Copies three bytes of a UInt32 to txBuffer starting at index More...
 
void Packi24 (ref byte[] txBuffer, Int32 i24ToPack, int index)
 Copies three bytes of a Int32 to txBuffer starting at index More...
 
void Packi32 (ref byte[] txBuffer, UInt32 i32ToPack, int index)
 Copies the bytes of a UInt32 to txBuffer starting at index. More...
 
void Packi32 (ref byte[] txBuffer, Int32 i32ToPack, int index)
 Copies the bytes of a Int32 to txBuffer starting at index. More...
 
void Packf32 (ref byte[] txBuffer, float floatToPack, int index)
 Copies the byte representation of a float to txBuffer starting at index. More...
 
void Packd64 (ref byte[] txBuffer, double doubleToPack, int index)
 Copies the byte representation of a double to txBuffer starting at index. More...
 
void PackTime (ref byte[] txBuffer, byte hours, byte minutes, byte seconds, UInt16 milliseconds, byte millisecond32nds, int index)
 Converts the given time into HART format and copies to txBuffer. More...
 
void PackDate (ref byte[] txBuffer, byte day, byte month, UInt16 year, int index)
 Converts the given date into HART format and copies to txBuffer More...
 
void PackLatin1 (ref byte[] txBuffer, String stringToPack, int index)
 Copies the ISO Latin-1 byte representation of a String into txBuffer. More...
 
void PackPAsc (ref byte[] txBuffer, String stringToPack, int index)
 Converts a String into Packed ASCII and copies it into txBuffer More...
 
byte[] UnpackBytes (byte[] rxBuffer, int numberToUnpack, int startIndex)
 Retrieves the given number of bytes from the specified index of rxBuffer More...
 
byte UnpackU08 (byte[] rxBuffer, int index)
 Retrieves an unsigned byte from the specified index of rxBuffer More...
 
sbyte UnpackS08 (byte[] rxBuffer, int index)
 Retrieves a signed byte from the specified index of rxBuffer More...
 
UInt16 UnpackU16 (byte[] rxBuffer, int index)
 Retrieves a UInt16 from the specified index of rxBuffer More...
 
Int16 UnpackS16 (byte[] rxBuffer, int index)
 Retrieves a Int16 from the specified index of rxBuffer More...
 
UInt32 UnpackU24 (byte[] rxBuffer, int index)
 Retrieves an unsigned 24 bit value from the specified index of rxBuffer More...
 
Int32 UnpackS24 (byte[] rxBuffer, int index)
 Retrieves a signed 24 bit value from the specified index of rxBuffer More...
 
UInt32 UnpackU32 (byte[] rxBuffer, int index)
 Retrieves a UInt32 from the specified index of rxBuffer More...
 
Int32 UnpackS32 (byte[] rxBuffer, int index)
 Retrieves a Int32 from the specified index of rxBuffer More...
 
float Unpackf32 (byte[] rxBuffer, int index)
 Retrieves and converts the bytes of a float from the specified index of rxBuffer More...
 
double Unpackd64 (byte[] rxBuffer, int index)
 Retrieves and converts the bytes of a double from the specified index of rxBuffer More...
 
void UnpackTime (byte[] rxBuffer, int index, out byte hours, out byte minutes, out byte seconds, out UInt16 milliseconds, out byte millisecond32nds)
 Retrieves and converts the HART time from the specified index of rxBuffer More...
 
void UnpackDate (byte[] rxBuffer, int index, out byte day, out byte month, out UInt16 year)
 Retrieves and converts the HART date from the specified index of rxBuffer More...
 
String UnpackLatin1 (byte[] rxBuffer, int numberOfChars, int index)
 Retrieves and converts a String from the specified index of rxBuffer More...
 
String UnpackPAsc (byte[] rxBuffer, int numberOfBytes, int index)
 Retrieves and converts Packed ASCII from the specified index of rxBuffer More...
 
void PrintBytes (byte[] arrayToPrint)
 Prints a byte array in an easily readable format. More...
 

Public Attributes

HartConfig Config
 

Detailed Description

Enables HART communication with a single Opto 22 HART I/O module channel.

Constructor & Destructor Documentation

Opto22.HART.HART.HART ( String  address,
int  moduleNumber,
int  channelNumber 
)

A constructor for the HART class.

Creates a new instance of HART. The instance only accesses a single point of HART I/O on a SNAP-Rack. In order to access multiple HART I/O points, multiple HART instances must be created.

This constructor uses the default port number for sending and receiving serial HART data.

Parameters
addressThe IPv4 address of the brain connected to the module. Format: "x.x.x.x"
moduleNumberThe rack position of the target HART module. (Note: This number indexes from zero)
channelNumberThe channel on the module to which the target HART network is connected. (Note: This number indexes from zero)
Opto22.HART.HART.HART ( String  address,
int  moduleNumber,
int  channelNumber,
int  port 
)

A constructor for the HART class.

Creates a new instance of HART. The instance only accesses a single point of HART I/O on a SNAP-Rack. In order to access multiple HART I/O points, multiple HART instances must be created.

This constructor allows the use of a custom port number for serial HART communications.

Parameters
addressThe IPv4 address of the brain connected to the module. Format: "x.x.x.x"
moduleNumberThe rack position of the target HART module. (Note: This number indexes from zero)
channelNumberThe channel on the module to which the target HART network is connected. (Note: This number indexes from zero)
portThe port number that should be used to send and receive serial HART data.

Member Function Documentation

int Opto22.HART.HART.SendReceive ( byte[]  deviceAddress,
byte  commandNumber,
ref byte[]  txHartData,
out byte[]  rxHartData,
out byte[]  rxMessage,
int  timeoutMS 
)

Send and receive a HART command in a single operation.

This method blocks for the time specified in timeoutMS. Setting timeoutMS to zero results in non-blocking behavior, and the returned value will be -20 (assuming there isn't another message waiting to be read).

Parameters
deviceAddressThe polling or unique address of the slave to send the command to.
commandNumberThe HART command number being sent.
txHartDataThe data to send in the command (pass an array of length zero for commands with no data). The entire OT4H message sent will be placed in this array.
rxHartDataThe data received from the slave device (this will get reset, and will be length zero if no data is received).
rxMessageThe total message received back from the HART master, including OT4H and HART headers, as well as HART data.
timeoutMSThe number of milliSeconds to wait for a response.
Returns
Error Code
Error Code Meaning
2 Burst/promiscuous message received
1 Error free response received
-3 Invalid address length
-20 Timeout
-43 NACK received
-8612 Mismatched sequence ID received
int Opto22.HART.HART.Receive ( out byte[]  rxHartData,
out byte[]  rxMessage,
int  timeoutMS 
)

Receive a message from the HART module.

Parameters
rxHartDataThe data received from the slave device (this will get reset, and will be length zero if no data is received).
rxMessageThe total message received back from the HART master, including OT4H and HART headers, as well as HART data.
timeoutMSThe number of milliSeconds to wait for a response.
Returns
Error Code
Error Code Meaning
2 Burst/promiscuous message received
1 Error free response received
-20 Timeout
-43 NACK received
-8612 Mismatched sequence ID received
void Opto22.HART.HART.PointConfig ( )

Send the current Config to the HART module.

Once the Config data member has been set, call this method to send that configuration to the target HART module.

void Opto22.HART.HART.FindDevices ( byte  startAddress,
byte  stopAddress,
out byte[]  PollingAddresses,
out byte  UniqueAddresses[][] 
)

Searches the bus for HART devices and reports their unique Addresses.

Finds all connected HART devices with polling addresses between startAddress and stopAddress. Reports both the polling and unique addresses of found devices. The indices in the polling and unique address arrays are the same for a given found device (e.g. PollingAddresses[2] will be the polling address of the device with unique address UniqueAddresses[2]).

Note: Max value for polling addresses is 63, does not wrap (e.g. startAddress = 40 and stopAddress = 10 will return immediately).

Parameters
startAddressBegin searching for devices at this polling address.
stopAddressStop searching for devices at this polling address.
PollingAddressesFound polling addresses will be placed here.
UniqueAddressesFound unique addresses will be placed here. Will be an array of 5-byte arrays.
void Opto22.HART.HART.FindOneDevice ( byte  PollingAddress,
out byte[]  UniqueAddress 
)

Finds the unique address of a device with a known polling address.

Parameters
PollingAddressThe polling address of the device.
UniqueAddressThe location to put the found unique address of the device.
int Opto22.HART.HART.ClearRxBacklog ( out byte[]  rxHartData,
out byte[]  rxMessage,
int  timeoutMS 
)

Clears any messages that have not been retrieved from the HART module.

Retrieves any messages that have not yet been retrieved, until it runs out of messages, or gets to the response to the most recently sent message. This is particularly useful for retrieving responses while a field device on the HART bus is bursting.

Parameters
rxHartDataThe data received from the slave device (this will get reset, and will be length zero if no data is received).
rxMessageThe total message received back from the HART master, including OT4H and HART headers, as well as HART data.
timeoutMSThe number of milliSeconds to wait for a response.
Returns
Error Code
Error Code Meaning
1 Error free response received
-20 Timeout
void Opto22.HART.HART.PackBytes ( ref byte[]  txBuffer,
byte[]  bytesToPack,
int  startIndex 
)

Copies a byte array to another, placing it at the specified index.

Copies the entire array bytesToPack into the array txBuffer, starting with bytesToPack[0] at txBuffer[startIndex]. All of the bytes from bytesToPack will be copied. If txBuffer is not long enough to copy into, it will be enlarged. Any gaps will be filled with zeros.

Parameters
txBufferThe buffer that data will be copied into
bytesToPackThe buffer that data will be copied from
startIndexThe index in txBuffer to place the first byte of bytesToPack
void Opto22.HART.HART.Packi08 ( ref byte[]  txBuffer,
byte  byteToPack,
int  index 
)

Copies an unsigned byte to txBuffer[index].

Parameters
txBufferThe buffer that data will be copied into
byteToPackThe byte that will be copied
indexThe location to copy the byte
void Opto22.HART.HART.Packi08 ( ref byte[]  txBuffer,
sbyte  byteToPack,
int  index 
)

Copies a signed byte to txBuffer[index].

Parameters
txBufferThe buffer that data will be copied into
byteToPackThe byte that will be copied
indexThe location to copy the byte
void Opto22.HART.HART.Packi16 ( ref byte[]  txBuffer,
UInt16  i16ToPack,
int  index 
)

Copies the bytes of a UInt16 to txBuffer starting at index.

Converts the input into its component bytes, ensures they are in BigEndian order, then places them into txBuffer starting at index index.

Parameters
txBufferThe buffer that data will be copied into
i16ToPackThe UInt16 that will be copied
indexThe location to copy the bytes
void Opto22.HART.HART.Packi16 ( ref byte[]  txBuffer,
Int16  i16ToPack,
int  index 
)

Copies the bytes of a Int16 to txBuffer starting at index.

Converts the input into its component bytes, ensures they are in BigEndian order, then places them into txBuffer starting at index index.

Parameters
txBufferThe buffer that data will be copied into
i16ToPackThe Int16 that will be copied
indexThe location to copy the bytes
void Opto22.HART.HART.Packi24 ( ref byte[]  txBuffer,
UInt32  i24ToPack,
int  index 
)

Copies three bytes of a UInt32 to txBuffer starting at index

Takes the three least significant bytes of i24ToPack and copies them in BigEndian order into txBuffer starting at index index.

Parameters
txBufferThe buffer that data will be copied into
i24ToPackThe UInt32 from which three bytes will be copied
indexThe location to copy the bytes
void Opto22.HART.HART.Packi24 ( ref byte[]  txBuffer,
Int32  i24ToPack,
int  index 
)

Copies three bytes of a Int32 to txBuffer starting at index

Takes the three least significant bytes of i24ToPack and copies them in BigEndian order into txBuffer starting at index index.

Parameters
txBufferThe buffer that data will be copied into
i24ToPackThe Int32 from which three bytes will be copied
indexThe location to copy the bytes
void Opto22.HART.HART.Packi32 ( ref byte[]  txBuffer,
UInt32  i32ToPack,
int  index 
)

Copies the bytes of a UInt32 to txBuffer starting at index.

Converts the input into its component bytes, ensures they are in BigEndian order, then places them into txBuffer starting at index index.

Parameters
txBufferThe buffer that data will be copied into
i32ToPackThe UInt32 that will be copied
indexThe location to copy the bytes
void Opto22.HART.HART.Packi32 ( ref byte[]  txBuffer,
Int32  i32ToPack,
int  index 
)

Copies the bytes of a Int32 to txBuffer starting at index.

Converts the input into its component bytes, ensures they are in BigEndian order, then places them into txBuffer starting at index index.

Parameters
txBufferThe buffer that data will be copied into
i32ToPackThe Int32 that will be copied
indexThe location to copy the bytes
void Opto22.HART.HART.Packf32 ( ref byte[]  txBuffer,
float  floatToPack,
int  index 
)

Copies the byte representation of a float to txBuffer starting at index.

Converts floatToPack into its representative bytes, ensures BigEndian ordering, and places them into txBuffer starting at index index.

Parameters
txBufferThe buffer that data will be copied into
floatToPackThe float that will be copied
indexThe location to copy the bytes
void Opto22.HART.HART.Packd64 ( ref byte[]  txBuffer,
double  doubleToPack,
int  index 
)

Copies the byte representation of a double to txBuffer starting at index.

Converts doubleToPack into its representative bytes, ensures BigEndian ordering, and places them into txBuffer starting at index index.

Parameters
txBufferThe buffer that data will be copied into
doubleToPackThe double that will be copied
indexThe location to copy the bytes
void Opto22.HART.HART.PackTime ( ref byte[]  txBuffer,
byte  hours,
byte  minutes,
byte  seconds,
UInt16  milliseconds,
byte  millisecond32nds,
int  index 
)

Converts the given time into HART format and copies to txBuffer.

HART formats time as a 32-bit integer, with the LSB representing 1/32 of a millisecond. This is capable of representing up to ~37 hours. It is recommended that to represent time spans greater than 24 hours, time be used in conjunction with a date.

No checks are performed for overflow when calculating the time value.

Parameters
txBufferThe buffer that data will be copied into
hours
minutes
seconds
milliseconds
milliseconds32nds
indexThe location to copy the converted time
void Opto22.HART.HART.PackDate ( ref byte[]  txBuffer,
byte  day,
byte  month,
UInt16  year,
int  index 
)

Converts the given date into HART format and copies to txBuffer

Converts the input parameters into a three-byte HART Date. day and month are copied verbatim, but year has 1900 subtracted from it. This limits year to representing the years 1900-2155.

Parameters
txBufferThe buffer that data will be copied into
day
month
yearShould be between 1900 and 2155
indexThe location to copy the converted date
void Opto22.HART.HART.PackLatin1 ( ref byte[]  txBuffer,
String  stringToPack,
int  index 
)

Copies the ISO Latin-1 byte representation of a String into txBuffer.

Parameters
txBufferThe buffer that data will be copied into
stringToPackThe string that will be copied from
indexThe location to copy the bytes
void Opto22.HART.HART.PackPAsc ( ref byte[]  txBuffer,
String  stringToPack,
int  index 
)

Converts a String into Packed ASCII and copies it into txBuffer

Packed ASCII is a format used by HART to pack 4 ASCII chars into 3 bytes of data. The representable chars are those between " "(space, 0x20) and "_"(underscore, 0x5F). Any string with a length that is not a multiple of 4 will be space extended until it has a length of 4.

Parameters
txBufferThe buffer that data will be copied into
stringToPackThe string that will be copied from
indexThe location to copy the bytes
byte [] Opto22.HART.HART.UnpackBytes ( byte[]  rxBuffer,
int  numberToUnpack,
int  startIndex 
)

Retrieves the given number of bytes from the specified index of rxBuffer

An attempt to retrieve an out of range value results in an ArgumentOutOfRangeException.

Parameters
rxBufferThe byte array to get the bytes from
numberToUnpackThe number of bytes to retrieve
startIndexThe index to start retrieving from
Returns
A byte array containing the requested bytes
byte Opto22.HART.HART.UnpackU08 ( byte[]  rxBuffer,
int  index 
)

Retrieves an unsigned byte from the specified index of rxBuffer

Parameters
rxBufferThe byte array to get the byte from
indexThe index to retrieve from
Returns
The requested unsigned byte
sbyte Opto22.HART.HART.UnpackS08 ( byte[]  rxBuffer,
int  index 
)

Retrieves a signed byte from the specified index of rxBuffer

Parameters
rxBufferThe byte array to get the byte from
indexThe index to retrieve from
Returns
The requested signed byte
UInt16 Opto22.HART.HART.UnpackU16 ( byte[]  rxBuffer,
int  index 
)

Retrieves a UInt16 from the specified index of rxBuffer

Parameters
rxBufferThe byte array to get the data from
indexThe index to start retrieving from
Returns
The requested UInt16
Int16 Opto22.HART.HART.UnpackS16 ( byte[]  rxBuffer,
int  index 
)

Retrieves a Int16 from the specified index of rxBuffer

Parameters
rxBufferThe byte array to get the data from
indexThe index to start retrieving from
Returns
The requested Int16
UInt32 Opto22.HART.HART.UnpackU24 ( byte[]  rxBuffer,
int  index 
)

Retrieves an unsigned 24 bit value from the specified index of rxBuffer

Since there is no native C# 24-bit data type, this function returns a UInt32 where the most significant byte is 0x00.

Parameters
rxBufferThe byte array to get the byte from
indexThe index to start retrieving from
Returns
The requested U24 as a UInt32
Int32 Opto22.HART.HART.UnpackS24 ( byte[]  rxBuffer,
int  index 
)

Retrieves a signed 24 bit value from the specified index of rxBuffer

Since there is no native C# 24-bit data type, this function returns a Int32 where the most significant byte is sign extended based on the sign of the msb.

Parameters
rxBufferThe byte array to get the byte from
indexThe index to start retrieving from
Returns
The requested S24 as a Int32
UInt32 Opto22.HART.HART.UnpackU32 ( byte[]  rxBuffer,
int  index 
)

Retrieves a UInt32 from the specified index of rxBuffer

Parameters
rxBufferThe byte array to get the data from
indexThe index to start retrieving from
Returns
The requested UInt32
Int32 Opto22.HART.HART.UnpackS32 ( byte[]  rxBuffer,
int  index 
)

Retrieves a Int32 from the specified index of rxBuffer

Parameters
rxBufferThe byte array to get the data from
indexThe index to start retrieving from
Returns
The requested Int32
float Opto22.HART.HART.Unpackf32 ( byte[]  rxBuffer,
int  index 
)

Retrieves and converts the bytes of a float from the specified index of rxBuffer

Parameters
rxBufferThe byte array to get the data from
indexThe index to start retrieving from
Returns
The requested float
double Opto22.HART.HART.Unpackd64 ( byte[]  rxBuffer,
int  index 
)

Retrieves and converts the bytes of a double from the specified index of rxBuffer

Parameters
rxBufferThe byte array to get the data from
indexThe index to start retrieving from
Returns
The requested double
void Opto22.HART.HART.UnpackTime ( byte[]  rxBuffer,
int  index,
out byte  hours,
out byte  minutes,
out byte  seconds,
out UInt16  milliseconds,
out byte  millisecond32nds 
)

Retrieves and converts the HART time from the specified index of rxBuffer

Parameters
rxBufferThe byte array to get the data from
indexThe index to start retrieving from
hoursThe variable to place the calculated hours in
minutesThe variable to place the calculated minutes in
secondsThe variable to place the calculated seconds in
millisecondsThe variable to place the calculated milliseconds in
millisecond32ndsThe variable to place the calculated millisecond32nds in
void Opto22.HART.HART.UnpackDate ( byte[]  rxBuffer,
int  index,
out byte  day,
out byte  month,
out UInt16  year 
)

Retrieves and converts the HART date from the specified index of rxBuffer

Parameters
rxBufferThe byte array to get the data from
indexThe index to start retrieving from
dayThe variable to place the calculated day in
monthThe variable to place the calculated month in
yearThe variable to place the calculated year in
String Opto22.HART.HART.UnpackLatin1 ( byte[]  rxBuffer,
int  numberOfChars,
int  index 
)

Retrieves and converts a String from the specified index of rxBuffer

Parameters
rxBufferThe byte array to get the data from
numberOfCharsThe number of characters to retrieve
indexThe index to start retrieving from
Returns
The requested String
String Opto22.HART.HART.UnpackPAsc ( byte[]  rxBuffer,
int  numberOfBytes,
int  index 
)

Retrieves and converts Packed ASCII from the specified index of rxBuffer

If numberOfBytes is not a multiple of 3, an ArgumentException will be thrown.

Parameters
rxBufferThe byte array to get the data from
numberOfBytesThe number of bytes that the Packed ASCII data takes up in rxBuffer, NOT the expected number of characters to be returned.
indexThe index to start retrieving from
Returns
A String with the requested Packed ASCII data decoded
void Opto22.HART.HART.PrintBytes ( byte[]  arrayToPrint)

Prints a byte array in an easily readable format.

Prints the length of the array on one line, and then the array itself. The values are comma separated and in hexadecimal notation.


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