Opto HART Toolkit
A .NET/MONO toolkit for using Opto22 HART modules
|
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 |
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.
address | The IPv4 address of the brain connected to the module. Format: "x.x.x.x" |
moduleNumber | The rack position of the target HART module. (Note: This number indexes from zero) |
channelNumber | The 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.
address | The IPv4 address of the brain connected to the module. Format: "x.x.x.x" |
moduleNumber | The rack position of the target HART module. (Note: This number indexes from zero) |
channelNumber | The channel on the module to which the target HART network is connected. (Note: This number indexes from zero) |
port | The port number that should be used to send and receive serial HART data. |
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).
deviceAddress | The polling or unique address of the slave to send the command to. |
commandNumber | The HART command number being sent. |
txHartData | The 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. |
rxHartData | The data received from the slave device (this will get reset, and will be length zero if no data is received). |
rxMessage | The total message received back from the HART master, including OT4H and HART headers, as well as HART data. |
timeoutMS | The number of milliSeconds to wait for a response. |
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.
rxHartData | The data received from the slave device (this will get reset, and will be length zero if no data is received). |
rxMessage | The total message received back from the HART master, including OT4H and HART headers, as well as HART data. |
timeoutMS | The number of milliSeconds to wait for a response. |
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 | ( | ) |
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).
startAddress | Begin searching for devices at this polling address. |
stopAddress | Stop searching for devices at this polling address. |
PollingAddresses | Found polling addresses will be placed here. |
UniqueAddresses | Found 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.
PollingAddress | The polling address of the device. |
UniqueAddress | The 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.
rxHartData | The data received from the slave device (this will get reset, and will be length zero if no data is received). |
rxMessage | The total message received back from the HART master, including OT4H and HART headers, as well as HART data. |
timeoutMS | The number of milliSeconds to wait for a response. |
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.
txBuffer | The buffer that data will be copied into |
bytesToPack | The buffer that data will be copied from |
startIndex | The 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]
.
txBuffer | The buffer that data will be copied into |
byteToPack | The byte that will be copied |
index | The location to copy the byte |
void Opto22.HART.HART.Packi08 | ( | ref byte[] | txBuffer, |
sbyte | byteToPack, | ||
int | index | ||
) |
Copies a signed byte to txBuffer[index]
.
txBuffer | The buffer that data will be copied into |
byteToPack | The byte that will be copied |
index | The 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
.
txBuffer | The buffer that data will be copied into |
i16ToPack | The UInt16 that will be copied |
index | The 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
.
txBuffer | The buffer that data will be copied into |
i16ToPack | The Int16 that will be copied |
index | The 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
.
txBuffer | The buffer that data will be copied into |
i24ToPack | The UInt32 from which three bytes will be copied |
index | The 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
.
txBuffer | The buffer that data will be copied into |
i24ToPack | The Int32 from which three bytes will be copied |
index | The 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
.
txBuffer | The buffer that data will be copied into |
i32ToPack | The UInt32 that will be copied |
index | The 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
.
txBuffer | The buffer that data will be copied into |
i32ToPack | The Int32 that will be copied |
index | The 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
.
txBuffer | The buffer that data will be copied into |
floatToPack | The float that will be copied |
index | The 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
.
txBuffer | The buffer that data will be copied into |
doubleToPack | The double that will be copied |
index | The 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.
txBuffer | The buffer that data will be copied into |
hours | |
minutes | |
seconds | |
milliseconds | |
milliseconds32nds | |
index | The 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.
txBuffer | The buffer that data will be copied into |
day | |
month | |
year | Should be between 1900 and 2155 |
index | The 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
.
txBuffer | The buffer that data will be copied into |
stringToPack | The string that will be copied from |
index | The 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.
txBuffer | The buffer that data will be copied into |
stringToPack | The string that will be copied from |
index | The 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.
rxBuffer | The byte array to get the bytes from |
numberToUnpack | The number of bytes to retrieve |
startIndex | The index to start retrieving from |
byte Opto22.HART.HART.UnpackU08 | ( | byte[] | rxBuffer, |
int | index | ||
) |
Retrieves an unsigned byte from the specified index of rxBuffer
rxBuffer | The byte array to get the byte from |
index | The index to retrieve from |
sbyte Opto22.HART.HART.UnpackS08 | ( | byte[] | rxBuffer, |
int | index | ||
) |
Retrieves a signed byte from the specified index of rxBuffer
rxBuffer | The byte array to get the byte from |
index | The index to retrieve from |
UInt16 Opto22.HART.HART.UnpackU16 | ( | byte[] | rxBuffer, |
int | index | ||
) |
Retrieves a UInt16 from the specified index of rxBuffer
rxBuffer | The byte array to get the data from |
index | The index to start retrieving from |
Int16 Opto22.HART.HART.UnpackS16 | ( | byte[] | rxBuffer, |
int | index | ||
) |
Retrieves a Int16 from the specified index of rxBuffer
rxBuffer | The byte array to get the data from |
index | The index to start retrieving from |
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.
rxBuffer | The byte array to get the byte from |
index | The index to start retrieving from |
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.
rxBuffer | The byte array to get the byte from |
index | The index to start retrieving from |
UInt32 Opto22.HART.HART.UnpackU32 | ( | byte[] | rxBuffer, |
int | index | ||
) |
Retrieves a UInt32 from the specified index of rxBuffer
rxBuffer | The byte array to get the data from |
index | The index to start retrieving from |
Int32 Opto22.HART.HART.UnpackS32 | ( | byte[] | rxBuffer, |
int | index | ||
) |
Retrieves a Int32 from the specified index of rxBuffer
rxBuffer | The byte array to get the data from |
index | The index to start retrieving from |
float Opto22.HART.HART.Unpackf32 | ( | byte[] | rxBuffer, |
int | index | ||
) |
Retrieves and converts the bytes of a float from the specified index of rxBuffer
rxBuffer | The byte array to get the data from |
index | The index to start retrieving from |
double Opto22.HART.HART.Unpackd64 | ( | byte[] | rxBuffer, |
int | index | ||
) |
Retrieves and converts the bytes of a double from the specified index of rxBuffer
rxBuffer | The byte array to get the data from |
index | The index to start retrieving from |
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
rxBuffer | The byte array to get the data from |
index | The index to start retrieving from |
hours | The variable to place the calculated hours in |
minutes | The variable to place the calculated minutes in |
seconds | The variable to place the calculated seconds in |
milliseconds | The variable to place the calculated milliseconds in |
millisecond32nds | The 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
rxBuffer | The byte array to get the data from |
index | The index to start retrieving from |
day | The variable to place the calculated day in |
month | The variable to place the calculated month in |
year | The 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
rxBuffer | The byte array to get the data from |
numberOfChars | The number of characters to retrieve |
index | The index to start retrieving from |
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.
rxBuffer | The byte array to get the data from |
numberOfBytes | The number of bytes that the Packed ASCII data takes up in rxBuffer , NOT the expected number of characters to be returned. |
index | The index to start retrieving from |
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.