HartTools
HartX 7.4
Software Documentation
Revision: 7.4.1
Date: 14.02.2014
Software Solution for Hart Communication in
Windows .NET applications.
LabVIEW, Excel, Visual Studio and more.
Borst Automation
Neue Reihe 33
DE-27474 Cuxhaven
GERMANY
Fon: +49 (0)4741 6985100
Fax: +49 (0)6432 6985102
http://borst-automation.com
Copyright© 1998-2014 Borst Automation, Walter Borst, Cuxhaven, GERMANY
Hart® is a registered trademark of the Hart Communication Foundation
Windows® is a registered trademark of Microsoft Corporation
LabVIEW® is a registered trademark of National Instruments Corporation
HartTools
HartX 7.4.1 / 14.02.2014 Contents 1
Contents
Overview.................................................................................. 2
Installation ...................................................................................... 2
64 Bit Platforms .......................................................................... 2
32 Bit Platforms .......................................................................... 2
Getting Started with LabVIEW ......................................................... 3
Setting a Reference to HartX ........................................................ 4
Registering the License ................................................................ 4
Reading two Process Variables ...................................................... 6
Getting Started with Visual Studio ................................................... 9
Getting Started with Excel ............................................................. 12
Distribution of Applications............................................................ 16
Typical Service Processing Program Flow ...................................... 16
Architecture ................................................................................... 17
Examples ............................................................................... 18
C# .................................................................................................. 18
Coding Details .......................................................................... 19
Visual Basic.................................................................................... 20
Locating the Reference to HartX .................................................. 21
Coding Details .......................................................................... 21
Coding Examples ...................................................................... 22
Functional Description ........................................................... 23
Properties ...................................................................................... 23
Operation/Control ..................................................................... 23
Parameter Properties ................................................................. 24
X-Properties (Any Command) ..................................................... 26
Methods ......................................................................................... 27
DoAction .................................................................................. 27
DoCommand ............................................................................ 27
Close ....................................................................................... 28
GetHartUnit .............................................................................. 28
FillBuffer .................................................................................. 28
ValidateLicense ......................................................................... 28
Events ............................................................................................ 28
Hart Information .................................................................... 29
Commonly Used Commands ........................................................... 29
Example Unit Codes ....................................................................... 35
Packed ASCII Codes ....................................................................... 36
Device Status ................................................................................. 37
Appendix ................................................................................ 37
Abbreviations ................................................................................. 37
HartTools
HartX 7.4.1 / 14.02.2014 Installation����2
Overview
The .NET Component HartX is implementing the Hart
communication protocol by resolving all the real time
requirements and coding as well as decoding issues.
The implementation of the Hart Protocol does not contain any
restriction to frame lengths like in Hart 5.x (e.g.). Therefore the
all communication functions can be used for devices supporting
Hart 5, Hart 6 or Hart 7.
Before using the communication the component has to select a
com port of the PC. This can be any com port from 1 to 255
including virtual com ports as they are used for USB like the
hart modems of MACTek® or Microflex.
Installation
Install the package into a directory of your choice. Open one of
the solutions provided in the example paths.
Note: The projects were generated with Visual Studio 2010.
Trying the examples with an earlier Version of Visual Studio will
not work.
64 Bit Platforms
The 64 Bit DLLs located in x64 should be copied to the Windows
system path for 64 bit DLLs (e.g. C:\Windows\System32). For
compatibility reasons the path is still named System32 even it
contains exclusively 64 bit DLLs.
The 32 Bit DLLs located in x86 should be copied to the 'Windows
over Windows 64' path (e.g. C:\Windows\SysWOW64).
32 Bit Platforms
On 32 bit platforms only the 32 bit DLL from x86 should be
copied to the Windows system path (e.g.
C:\Windows\System32).
HartTools
HartX 7.4.1 / 14.02.2014 Getting Started with LabVIEW����3
Getting Started with LabVIEW
As already said in the overview HartX is not a .NET control but a
.NET component. This is also named an assembly. Thus HartX is
not introduced by using the .NET container of LabVIEW nor the
VISA interface. It is done much simpler.
The example is not very complex. It is reading process variable
1 and 2 from a HART device and connecting the values to two
simple meters.
If you have installed HartTools 7.4 the vi of the example is
located in the path:
Hart Tools 7.4\Examples\HartX\LabVIEW\UsingHart.vi.
The application contains only one block diagram.
The following starts with an empty vi and explains step by step
how to integrate the HartX. The main issue about HartX is that
the user has not to deal with serial communications. The only
thing is to set the com port number.
HartTools
HartX 7.4.1 / 14.02.2014 Getting Started with LabVIEW����4
Setting a Reference to HartX
To get a reference to HartX open the functions
palette, navigate to
Connectivity->.NET->Constructor and place it
on the wiring diagram.
The window Select .NET constructor appears. Click 'Browse' and
select the BaHartX74.dll in the directory .\x86.
Select the object BaHartX74,
click OK and the reference is
ready.
You can now see the reference
on the diagram.
Registering the License
The first thing the application has to do is to
register the license. This is done by the method
ValidateLicense.
For this you pick an Invoke Node from the
functions palette and place it on the diagram.
In the invoke node you have to select the
method ValidateLicense.
Before you do this you have to connect the 'new
reference' output of the Constructor with the
'reference input' of the Invoke Node.
HartTools
HartX 7.4.1 / 14.02.2014 Getting Started with LabVIEW����5
The method needs two parameters to be
passed, the sUserName and the sLicense. These
two parameters are realized by constant strings
from the functions palette
Programming->String->String Constant.
Insert the required texts into the
constants and wire it to the
parameters.
The only step left before you start building the while loop is to
provide a com port number for HartX.
For this you need a property node to be
placed on the diagram.
Select the property, connect the
reference output of the Validate License
method with the reference input of
the Property Node. Then select the
property cComPort and make it
writable. This is done by pointing
to the property and using the right
mouse button for the context
menu which provides the option
'Change to Write'.
To give it a value you can use a
Numeric Constant from the
functions palette (Programming->Numeric->Numeric Constant).
Before inserting the number of
the com port and wiring it to
the property you have to set
the type of the numeric
constant to I8. The left window
is showing up if you write click
the property and select
'Properties' from the context
menu which opens for the
property.
� Initialization of HartX
completed
HartTools
HartX 7.4.1 / 14.02.2014 Getting Started with LabVIEW����6
Reading two Process Variables
Now the startup of HartX is completed and a while loop is
required to continuously read out the processing variables of the
device.
If you don't have to have a HART device ready to try this
example you may still continue because the HartX is supporting
a simulation mode for the reading of PVs.
First of all a while loop is required. Pick a while loop from the
functions palette and place it on the diagram. Then get a stop
button from the controls palette and wire it with the loop
condition.
Now four more properties of HartX are needed. Two for reading
and two for writing.
The Boolean property SimPvEnabled allows to enable the
process variable simulation of HartX. The float property
SimAmplitude allows to adjust the Amplitude in the simulation
mode.
The property SimAmplitude is controlled by a Knob
(Modern->Numeric->knob). The simulation mode is switched by
a boolean control
(Express->Button & Switches->Toogle Switch).
For the display of the two PVs simple meters are taken
(Siver->Numeric->Meter) and connected to the properties
p03Pv1 and p03Pv2.
We are almost done with that but the simulation will not run yet
because the HartX does not have an automatic trigger internally
which would run the simulation state machine. This will be
achieved be introducing the method DoAction which is usually
triggering the HART communication (see documentation of
methods).
� No HART device needed
to continue.
HartTools
HartX 7.4.1 / 14.02.2014 Getting Started with LabVIEW����7
The diagram is now looking as shown below.
The last step therefore is to place the method DoAction in the
diagram and wire it with a constant byte which is set to 3. In
the while loop this method will be called continuously. Usually
action 3 is executing command 3 to get the process variables. If
the simulation is switched on, no action will be performed.
However, also in simulation the action method is delaying 200
milliseconds to simulate the timing behavior of the
communication process.
Thus the final diagram looks as the following.
It is very obvious that the user who is programming a HART
application has not to care about serial communications or
decoding and encoding stuff. The only setting for serial
communications is the com port number.
HartTools
HartX 7.4.1 / 14.02.2014 Getting Started with LabVIEW����8
If you have a HART device connected you could use FrameAlyst
to watch the communication if the simulation mode is switched
off.
Before starting to accept the command 3 requests HartX is
automatically sending command 0 to retrieve the unique
identifier from the device.
HartTools
HartX 7.4.1 / 14.02.2014 Getting Started with Visual Studio����9
Getting Started with Visual Studio
Open Visual Studio and create a new project for a Windows
Forms Application.
The HartX72 component is not installed automatically into the
toolbox of Visual Studio. If the component is registered on your
computer you can select it from the .NET Framework
Components list by right-clicking the tollbox and selecting the
context menu entry 'Choose Items'.
HartTools
HartX 7.4.1 / 14.02.2014 Getting Started with Visual Studio����10
Otherwise you would have to select the DLL of the component
directly.
The next step would be to insert the component into your
application.
After this you can set some of the properties to the initial
values.
HartTools
HartX 7.4.1 / 14.02.2014 Getting Started with Visual Studio����11
A button and a text box are used to perform some action.
It is very few code that is needed. The most things of Hart
communication are handled by the control.
using System; using System.Text; using System.Windows.Forms; namespace HartXtest { public partial class frmMain : Form { public frmMain() { InitializeComponent(); } private void butGetTagName_Click( object sender, EventArgs e) { butGetTagName.Enabled = false ; butGetTagName.Refresh(); txtTagName.Text = "-/-" ; txtTagName.Refresh(); if (HartX.DoCommand(13) == BaHartX74. EN_LastError .ERR_Success) { txtTagName.Text = HartX.p13TagName; } else { txtTagName.Text = "Error!" ; } butGetTagName.Enabled = true ; } } }
The HartX is automatically sending command 0 to connect to
the device and to get the unique identifier.
HartTools
HartX 7.4.1 / 14.02.2014 Getting Started with Excel����12
Getting Started with Excel
Before you can start to use VBA in Excel you have to activate
the developer tabs in Options->Customize Ribbon.
To be sure that your macros (VBA program) are saved too you
have to store the file as macro-enabled workbook.
The example is using a button for starting and a textbox for the
com port number.
HartX is not a .net control but only a component. Therefore it
has to be addressed by a reference. VBA does not accept a
reference to the dll but to the type library (tlb) file.
The reference has to be set in the code
Window which is opened by the
selection of ‘View Code’ in the
Developer tab.
In the code window the
menu Tools has the menu
item References. After a
click on this option the
reference select Window
opens.
HartTools
HartX 7.4.1 / 14.02.2014 Getting Started with Excel����13
Click on browse and navigate to the tlb of the HartX.
Next is to declare an object using the HartX reference.
The example is coded in the event procedure of the button.
HartTools
HartX 7.4.1 / 14.02.2014 Getting Started with Excel����14
The first call of the HartX should be the call of the
ValidateLicense method in order to set the HartDLL into a
functional mode.
However the simulation of PVs also works without any License
code.
The only thing to do for the
communications is to set
the com port to which the
Hart device is connected
to.
The property
SimPvEnabled is setting
the simulation mode of the
HartX. If this mode is set
the PVs are simulate
between values set by the
SimulateAmplitude property.
The ‘main program’ of the example is a for loop reading two PVs
from the device for 20 times and writing the results to the
worksheet.
The call of DoAction is
driving the simulation of
the PVs and simulates a
delay of 200 ms like the
communication would do.
In the case the simulation
is switched of DoAction
would run the Hart protocol
activities. After running the example the worksheet will look as
below.
HartTools
HartX 7.4.1 / 14.02.2014 Getting Started with Excel����15
Running it with the simulation switched off, the example will
communicate with the real device.
The worksheet may look like it is shown below.
If you run FrameAlyst during the session you can see the
communication activities.
Before starting to accept the command 3 requests HartX is
automatically sending command 0 to retrieve the unique
identifier from the device.
HartTools
HartX 7.4.1 / 14.02.2014 Distribution of Applications����16
Distribution of Applications
The user have to provide a copy of the component DLL and the
driver DLL (BaHartX.dll and BaHartDrv74.dll). The best way is to
provide a copy of the 32 bit DLLs (x86) as well as a copy of the
64 bit DLLs (x64). The files should be copied to the Windows
system paths for 32 and 64 bit DLLs.
Note: Be sure that the first call of your application is a call of
the validation function of the DLL (HartX.ValidateLicense)
passing a valid license code and the correct user name to the
component DLL (the assembly).
Typical Service Processing Program Flow
Figure 1: HartX Service Flow
BHDrv_OpenChannel Register at a com port
BHDrv_ConnectByAddr Get the unique identifier
of the device
BHDrv_DoCommand
BHDrv_IsServiceCompleted
BHDrv_FetchConfirmation
Poll for service
completion
Get the resulting data
HartX.DoCommand
HartX.DoCommand
These services are automatically performed by
HartX if necessary.
HartTools
HartX 7.4.1 / 14.02.2014 Architecture����17
Architecture
Figure 2: The Internal Structure of the DLL
The figure above shows that the HartX is using is using its own
thread for the real time application. Thus the calling thread may
be of any kind. Even if HartX is waiting for the completion of the
service it is taking the calling thread into sleep mode.
Figure 3: The DLL can be used by different Threads
HartX may be called from several threads. The functions and
communication services are thread safe.
User Application
HartX Functions
Service Handler
Hart Protocol Thread
PC Com Port
Done?
Start Service
No
Yes
Sleep 10 ms
Real time
functionality
HART MODEM
BaHartX74.dll
BaHartX74.dll(1)
User Application
Thread 1 Thread 2 Thread 3
BaHartX74.dll(2)
BaHartX74.dll(3)
HartTools
HartX 7.4.1 / 14.02.2014 C#����18
Examples
While the example for C# is very differentiated showing the use
of the x properties the example for Visual Basic is very simple,
demonstrating that using HartX in another language
environment is not a problem.
C#
The communication settings are serving the c properties thus
controlling the behavior of the Hart communication.
Setting and getting the tag name is just an example how the
normal data properties are used.
However the most important functionality is the evaluation of
the content of the request respectively the response buffer.
Here you may encode and decode data in a buffer which is used
together with the execute command function.
With this example it should be explained how the usage of the x
properties is working. In the following the sequence is described
how command 35 is prepared to be send.
HartTools
HartX 7.4.1 / 14.02.2014 C#����19
In the following the lower range is set to -20.0 °C and the upper
range to 200.0 °C.
Step Description
1 Enter 35 into Cmd in the 'Execute Command' group.
2 Enter 9 into Data Len in the 'Execute Command' group.
3 Enter Offset 0
4 Select type int8
5 Enter value 32
6 Click insert
7 Select type Float
8 Enter offset 1
9 Enter value 200.0
10 Click insert
11 Enter offset 5
12 Enter value -20.0
13 Click insert
The display is now
The application is now ready to send command 9 if the button
send in 'Execute Command' is clicked.
Coding Details
The initialization is very simple.
private void frmMain_Load( object sender, System. EventArgs e) { ... HartX.ValidateLicense( "Valid User Name" , "Valid License Key" ); }
Code Snippet 1: Initialization in Form_Load
HartTools
HartX 7.4.1 / 14.02.2014 Visual Basic����20
Most of the services are conducted in the ExecuteCommand
method.
private EN_LastError ExecuteCommand( byte byCommand) { EN_LastError enErr = EN_LastError .ERR_UndefinedError; lblExecuting.Text = "Executing Command " + byCommand.ToString() + " ..." ; lblExecuting.Visible = true ; ClearResponses(); if (UseCommSettings()) { enErr = HartX.DoCommand(byCommand); SetLastError(enErr); if (enErr == EN_LastError .ERR_Success) { txtRsp1.Text = HartX.cResponse1.ToStr ing( "000" ); txtRsp2.Text = HartX.cResponse2.ToStr ing( "000" ); RefreshHexDisplay(); } } lblExecuting.Visible = false ; txtLastError.Focus(); return enErr; }
Code Snippet 2: The Method ExecuteCommand
Getting the measured values is also very simple
private void butGetPVs_Click( object sender, System. EventArgs e) { //... if (ExecuteCommand(3) == EN_LastError .ERR_Success) { txtPV1val.Text = HartX.p03Pv1.ToString( ); lblPV1unit.Text = HartX.p03Pv1UnitStrin g; txtPV2val.Text = HartX.p03Pv2.ToString( ); lblPV2unit.Text = HartX.p03Pv2UnitStrin g; txtPV3val.Text = HartX.p03Pv3.ToString( ); lblPV3unit.Text = HartX.p03Pv3UnitStrin g; txtPV4val.Text = HartX.p03Pv4.ToString( ); lblPV4unit.Text = HartX.p03Pv4UnitStrin g; }
Code Snippet 3: Getting Data through Command 3
Visual Basic
This is a very simple example only reading the tag name of a
device. However the example is showing only the main
differences of C# and Visual Basic.
Among the language the differences from VB to C# are located
in the environment handling.
HartTools
HartX 7.4.1 / 14.02.2014 Visual Basic����21
Locating the Reference to HartX
Usually it would be enough to use a control which is compiled
for AnyCPU. However, in case of debugging 32 bit and 64 bit
applications on the same machine it may make a difference.
Therefore there are three versions of the HartX DLL on different
application locations.
Target CPU Directory
Any Application
x86 Subdirectory x86
x64 Subdirectory x64
There are two ways to get the HartX available in a VB project.
The first is through the toolbox. If the control is not showing up
automatically you may use choose items and the browse
function to select the HartX DLL in the right directory.
The other way could be to get set a reference to it. This may be
done by double clicking My Project and select References in the
project environment.
Coding Details Private Sub frmMain_Load( ByVal sender As System. Object , ByVal e As System. EventArgs ) _ Handles MyBase.Load HartX.ValidateLicense( "Valid User Name" , "Valid License" ) HartX.cComPort = 1 End Sub
Code Snippet 4: Initialization is very short
Private Sub butGetTag_Click( ByVal sender As System. Object , ByVal e As System. EventArgs ) _ Handles butGetTag.Click txtTagName.Text = "Reading..." txtTagName.Refresh() HartX.cNoPreambles = 5 If HartX.DoCommand(13) = BaHartX74. EN_LastError .ERR_Success Then txtTagName.Text = HartX.p13TagName Else txtTagName.Text = "Error!" End If End Sub
Code Snippet 5: Reading the Tag Name through Command 13
HartTools
HartX 7.4.1 / 14.02.2014 Visual Basic����22
Coding Examples
Command 35 (Set Range) private void SetRange_Example() { byte UnitCode = 0; float UpperRangeValue = 0.0f; float LowerRangeValue = 0.0f; HartX.xReqLen = 9; // Size of data in request = 9 (1 byte, 2 floats) HartX.xOffset = 0; // Unit code at index 0 in request HartX.xInt8 = 32; // Unit code for °C HartX.xOffset = 1; // Upper range at index 1 in request HartX.xFloat = 200.0f; // Upper range value = 200.0 HartX.xOffset = 5; // Lower range at index 5 in request HartX.xFloat = -20.0f; // Lower range value = -20.0 if ( HartX.DoCommand(35) == EN_LastError .ERR_Success ) { // Read back the values from the response HartX.xOffset = 0; // Unit code at index 0 in response UnitCode = HartX.xInt8; HartX.xOffset = 1; // Upper range at index 1 in response UpperRangeValue = HartX.xFloat; HartX.xOffset = 5; // Lower range at index 5 in response LowerRangeValue = HartX.xFloat; } }
Command 18 (Write Tag, Descriptor, Date)
This command is executed if action ACT_WrTagDescrData is
conducted. However, it could also be performed by using the x-
properties.
private void SetTagDescDate_Example() { string TagName = "" ; string Descriptor = "" ; byte Day = 0; byte Month = 0; byte Year = 0; HartX.xReqLen = 21; // Size of data in request = 21 // (Tag(6), Descr(12), Day(1), Month(1), Year(1) HartX.xOffset = 0; // Tag name at index 0 HartX.xPackedASCLen = 6; HartX.xPacked_ASCII = "lit120" ; HartX.xOffset = 6; // Descriptor name at index 6 HartX.xPackedASCLen = 12; HartX.xPacked_ASCII = "descriptor" ; HartX.xOffset = 18; // Day at index 18 HartX.xInt8 = 28; HartX.xOffset = 19; // Month at index 19 HartX.xInt8 = 12; HartX.xOffset = 20; // Year at index 20 HartX.xInt8 = 113; if ( HartX.DoCommand(18) == EN_LastError .ERR_Success ) { // Read back the values from the response HartX.xOffset = 0; HartX.xPackedASCLen = 6; TagName = HartX.xPacked_ASCII; HartX.xOffset = 6; HartX.xPackedASCLen = 12; Descriptor = HartX.xPacked_ASCII; HartX.xOffset = 18; Day = HartX.xInt8; HartX.xOffset = 19; Month = HartX.xInt8; HartX.xOffset = 20; Year = HartX.xInt8; } }
HartTools
HartX 7.4.1 / 14.02.2014 Properties����23
Functional Description
Properties
Operation/Control
Name Type Acc Description
cAddrMode byte R/W 0: Use Poll Address 1: Use Long Address 2: Use Short Tag
cComPort 0: None 1-254: Com port number 255: Reserved
cAddrTag string Short tag name used for addressing. The string should have a length of 8 and should contain only capital letters.
cBaudRate byte Not yet implemented
cNoPreambles Number of preambles to be sent with a request (typically 5)
cPollAddress Poll address used to get the unique ID (0..63)
cNewPollAddress Poll address to be set in the slave using action ACT_WrPollAddr.
cNumRetries Number of retries in case of error (0..255)
cMasterRole The initial master role when starting communications 0: Primary Master 1: Secondary Master
cRetryIfBusy Indicates if the control should retry as long as the device is responding with busy1. 0: false >0: true
cUnId0 Long address byte 1
cUnId1 Long address byte 2
cUnId2 Long address byte 3
cUnId3 Long address byte 4
cUnId4 Long address byte 5
cRcvLen RO Length of the received data package
cResponse1 Response code for the command
cResponse2 Device status
1 This could cause a very large delay, has to be handled with care.
HartTools
HartX 7.4.1 / 14.02.2014 Properties����24
Parameter Properties
These properties are used to get portions of data from the
recently conducted command.
Command 0 (Read unique ID)
Usually this command is automatically executed if the control is
not yet 'connected' to the device (unique identifier unknown).
Name Type Acc Description
p00Device byte RO Device ID (8 bit)
p00DeviceNumber uint 3 byte unique device ID
p00HardwRev byte Hardware revision
p00SoftwRev Software revision
p00VendorID Manufacturer/Vendor identifier
Command 1 (Read Primary Variable)
Name Type Acc Description
p01Pv float RO Value of process variable 1
p01PvUnit byte Unit code of process variable 1
p01PvUnitString string String for the unit of process variable 1
Command 2 (Read Current and Percentage)
Name Type Acc Description
p02Current float RO Value of the current output [mA]
p02Percent Value of the percentage 0..100 %
Command 3 (Read dynamic variables)
Name Type Acc Description
p01Pv float RO Value of process variable 1
p01PvUnit byte Unit code of process variable 1
p01PvUnitString string String for the unit of process variable 1
p02Pv float Value of process variable 2
p02PvUnit byte Unit code of process variable 2
p02PvUnitString string String for the unit of process variable 2
p03Pv float Value of process variable 3
p03PvUnit byte Unit code of process variable 3
p03PvUnitString string String for the unit of process variable 3
p04Pv float Value of process variable 4
p04PvUnit byte Unit code of process variable 4
p04PvUnitString string String for the unit of process variable 4
HartTools
HartX 7.4.1 / 14.02.2014 Properties����25
Command 12 (Read Message)
Name Type Acc Description
p12Message string R/W Hart message, the string should have a length of 32
Command 13 (Read Tag, Descriptor, Date)
Name Type Acc Description
p13DateDay byte R/W Day of month 1..31
p13DataMonth Month of the year 1..12
p13DateYear Year as offset to 1900
p13Descriptor string String of 16 characters for the description
p13TagName string String of 8 characters for the short tag
Command 14 (Read Transducer Information)
Name Type Acc Description
p14LoSensLimit float RO Lower sensor limit
p14MinSpan Minimum span
p14SensLimUnit byte Unit code for the sensor information (values)
p14SensSerNum uint 24 bit sensor serial number
p14UpSensLimit float Upper sensor limit
Command 15 (Read Device Information)
Name Type Acc Description
p15AlmSelCode byte RO Alarm selection code
p15LabDistCode Label distributor code
p15LoRange float Lower range value
p15RangeUnit byte Unit code for the range values
p15UpRange float Upper range value
p15WrProtCode byte Write protection
0: None >0: Write protected
p15XferFuncCode Transfer function code
HartTools
HartX 7.4.1 / 14.02.2014 Properties����26
X-Properties (Any Command)
These properties are used to handle any command.
Name Type Acc Description
xReqLen byte R/W Defines the length of the request data buffer
xOffset Defines the offset into the buffer for coding and decoding
xStringLen Defines the length of a string for coding and decoding
xPackedASCLen Defines the length of a packed ascii string
xHexDataDump string Returns a string with the hex dump of the buffer with a length of xReqLen
xInt8 byte Sets or gets an 8 bit integer value in/from the buffer
xInt16 ushort Sets or gets an 16 bit integer value in/from the buffer
xInt24 uint Sets or gets an 24 bit integer value in/from the buffer
xInt32 uint Sets or gets an 32 bit integer value in/from the buffer
xFloat float Sets or gets a float value in/from the buffer
xString string Sets or gets a string of xStringLen in/from the buffer
xPacked_ASCII string Sets or gets a packed ascii string of xPackedASCLen in/from the buffer. It very important to set the property xPackedASCIILen before accessing the property xPackedASCII. The format PackedASCII stores 4 characters in three octets (24 bits), using only 6 bits for each character. The xPackedASCIILen has to be set to the number of octets used to store the string. Possible values are 3,6,9.. etc.. For instance a xPackedASCIILen of 3 allows to access a string of a length of four characters. See also: Fehler! Verweisquelle konnte nicht gefunden werden..
HartTools
HartX 7.4.1 / 14.02.2014 Methods����27
Methods
DoAction
EN_LastError DoAction( EN_Action Action)
BaHartX74.dll
Parameter Type Description
Action In ACT_None(0) Perform no action
ACT_RdPv(1) Read the primary process variable and the unit (Command 1). Update p01 properties.
ACT_RdCurrPerc(2) Read the value for the current (4..20 mA) and the pv in % (Command 2). Update p02 properties.
ACT_RdAllPv(3) Read all available process variables (Command 3). Update p03 properties.
ACT_RdMessage(4) Read the message (Command 12). Update p12 property.
ACT_RdTagDescrDate(5) Read Tag, Descriptor and Date (Command 13). Update p13 properties.
ACT_RdSensLimits(6) Read sensor limit data (Command 14). Update p14 properties.
ACT_RdRange(7) Read range data (Command 15). Update p15 properties.
ACT_WrMessage(8) Write message (Command 17). Use the p12 property.
ACT_WrTagDescrData(9) Write Tag, Descriptor and Date (Command 18). Use p13 properties.
ACT_WrPollAddr(10) Write a new poll address into the device. Use cNewPollAddress for this action.
ACT_ResetStatus(11) Forces the control to forget the unique identifier of the most recently connected HART device.
Returns
EN_LastError (0 = Success)
The DoAction method is mainly used to handle the parameter
properties.
DoCommand
EN_LastError DoCommand(byte Command)
BaHartX74.dll
Parameter Type Description
Command In HART command number
Returns
EN_LastError (0 = Success)
The method is performing a Hart command. For the data send
with the request it is using xReqLen and the internal data buffer
with the data bytes.
HartTools
HartX 7.4.1 / 14.02.2014 Events����28
Close
void Close()
BaHartX74.dll
Has to be called when the application terminates.
GetHartUnit
string GetHartUnit( byte UnitCode)
BaHartX74.dll
Parameter Type Description
UnitCode In HART unit code
Returns
Visible string for the unit code
FillBuffer
void FillBuffer( byte FillValue)
BaHartX74.dll
Parameter Type Description
FillValue In Byte to fill the buffer with (usually 0 or 0xff)
ValidateLicense
void ValidateLicense( string UserName, string License)
BaHartX74.dll
Parameter Type Description
UserName In User name provided by Borst Automation
License In License code provided by Borst Automation
Usage
HartX.ValidateLicense( "30 - Days- Trial - User - License" , "ZUEjdhuI - tz45 - klER - fgTT - JkHfuIzEwr7u" );
Events
Events are not yet implemented in HartX.
HartTools
HartX 7.4.1 / 14.02.2014 Commonly Used Commands����29
Hart Information
The following is not replacing any specification and is not
showing the details which are needed for an implementation.
The details has to be taken from the Hart specifications which
are provided by the Hart Communication Foundation
(http://de.hartcomm.org/).
That the listed commands are most commonly used is not the
opinion of the HCF but the opinion of the author of this
document.
Commonly Used Commands
No Title Request Data Response Data
Universal
00 Read Unique Identifier
None 0 int8 254
1 Manufacturer ID
2 Short device ID
3 Number preambles request
4 Hart revision
5 Device revision
6 Software revision
7 Hw rev and signaling code
8 Flags
9 int24 DevUniqueID
12 int8 Number preambles response
13 Maximum number device variables
14 int16 Configuration change counter
16 int8 Extended device status
17 int16 Extended manufacturer code
19 Extended label distributor code
21 int8 Device profile
01 Read Primary Variable
None 0 int8 PV Units
1 float Primary variable
02 Read Current and Percent of Range
None 0 float Current
1 float Percent of range
03 Read Current and Dyn. Variables
None 0 float Current
4 int8 PV1 units code
5 float PV1 value
9 int8 PV2 units code
10 float PV2 value
14 int8 PV3 units code
15 float PV3 value
19 int8 PV4 units code
20 float PV4 value
06 Write Polling Address
0 int8 Polling Address 0 int8 PV Units
1 int8 Loop current mode 1 int8 Loop current mode
HartTools
HartX 7.4.1 / 14.02.2014 Commonly Used Commands����30
No Title Request Data Response Data
Universal
07 Read Loop Configuration
None 0 int8 Polling address
1 Loop current mode
08 Read Dyn. Vars Classification
None 0 int8 PV1 classification
1 PV2 classification
2 PV3 classification
3 PV4 classification
09 Read Device Variables with Status
0 int8 Slot0: Device variable code 0 int8 Extended device status
1 Slot1: Device variable code 1 Slot0: Device variable properties
2 Slot2: Device variable code 1 int8 Device variable code
3 Slot3: Device variable code 2 Device variable classification
4 int8 Slot4: Device variable code 3 Device variable units code
5 Slot5: Device variable code 4 float Device variable value
6 Slot6: Device variable code 8 int8 Device variable status
7 Slot7: Device variable code 9 struct Slot1: Device variable properties
17 Slot2: Device variable properties
25 Slot3: Device variable properties
33 struct Slot4: Device variable properties
41 Slot5: Device variable properties
49 Slot6: Device variable properties
57 Slot7: Device variable properties
65 time Time stamp slot0
11 Read Unique ID by Short Tag
0 pac6 Tag name (packed ascii) 6 bytes = 8 characters
Same as command 0 read unique identifier
12 Read Message None 0 pac24 Message (packed ascii) 24 bytes = 32 characters
13 Read Tag, Descriptor, Date
None 0 pac6 Short tag (packed ascii) 6 bytes = 8 characters
6 pac12 Descriptor (packed ascii) 12 bytes = 16 characters
18 int8 Day
19 Month
20 Year (offset to 1900)
14 Read Primary Variable Transducer Information
None 0 int24 Transducer serial number
3 int8 Units code
4 float Upper transducer limit
8 Lower transducer limit
12 Minimum span
15 Read Device Information
None 0 int8 Alarm selection code
1 Transfer function code
2 Units code
3 float PV upper range value (for 20 mA)
7 PV lower range value (for 4 mA)
11 PV damping value
15 int8 Write protect code
16 Reserved, must be set to 250
17 PV analog channel flags
16 Read Ass. Num None 0 int24 Final assembly number
HartTools
HartX 7.4.1 / 14.02.2014 Commonly Used Commands����31
No Title Request Data Response Data
Universal
17 Write Message Same as response command 12 Same as response command 12
18 Write Tag, Descriptor, Date
Same as response command 13 Same as response command 13
19 Write Ass. Num Same as response command 16 Same as response command 16
20 Read Long Tag None 0 str32 Long tag: 32 ISO Latin-1 characters
21 Read Unique ID by Long Tag
0 str32 Long tag: 32 ISO Latin-1 characters Same as command 0 read unique identifier
22 Write Long Tag Same as response command 20 Same as response command 20
38 Reset Config Changed Flag
None None
0 int16 Configuration change counter 0 int16 Configuration change counter
48 Read Additional Device Status
None
0 int8[5] Transmitter specific status 0 int8[5] Transmitter specific status
6 int8[2] Operating mode
6 int8 Extended device status 6 int8 Extended device status
7 Device operating mode 7 Device operating mode
8 int8[3] Analog output status
8 int8 Standard status 0 8 int8 Standard status 0
9 Standard status 1 9 Standard status 1
10 Analog channel saturated 10 Analog channel saturated
11 int8[3] Analog output fixed
11 int8 Standard status 2 11 int8 Standard status 2
12 Standard status 3 12 Standard status 3
13 Analog channel fixed 13 Analog channel fixed
14 int8[3] Transmitter specific status
14 int8[10] Transmitter specific status 14 int8[10] Transmitter specific status
Common Practice
33 Read Device Variables
0 int8 Slot0: Device variable code 0 Slot0: Device variable properties
1 Slot1: Device variable code 0 int8 Device variable code
2 Slot2: Device variable code 1 Device variable units code
3 Slot3: Device variable code 2 float Device variable value
6 struct Slot1: Device variable properties
12 Slot2: Device variable properties
18 Slot3: Device variable properties
34 Write Prim. Var. Damping
0 float PV 1 damping value 0 float PV 1 damping value
35 Write Prim. Var. Range Values
0 int8 Units code 0 int8 Units code
1 float Upper range value 1 float Upper range value
5 Lower range value 5 Lower range value
36 Set Prim. Var. Upper Range
None None
37 Set Prim. Var. Lower Range
None None
HartTools
HartX 7.4.1 / 14.02.2014 Commonly Used Commands����32
No Title Request Data Response Data
Common Practice
40 Enter/Exit Fixed Current
0 float Current value 0 float Actual current value
42 Device Reset None None
43 Set Primary Variable Zero
None None
44 Write Prim. Var. Units
0 int8 PV 1 units code 0 int8 PV 1 units code
45 Trim Prim. Var. Current Zero
0 float Measured current value 0 float Actual current value
46 Trim Prim. Var. Current Gain
0 float Measured current value 0 float Actual current value
50 Read Dynamic Variable Assignments
None 0 int8 PV 1 variable code
1 PV 2 variable code
2 PV 3 variable code
3 PV 4 variable code
51 Write Dynamic Variable Assignments
0 int8 PV 1 variable code 0 int8 PV 1 variable code
1 PV 2 variable code 1 PV 2 variable code
2 PV 3 variable code 2 PV 3 variable code
3 PV 4 variable code 3 PV 4 variable code
54 Read Device Variable Information
0 int8 Device variable code 0 int8 Device variable code
1 int24 Sensor serial number
4 int8 Units code
5 float Variable upper limit
9 Variable lower limit
13 Variable damping
17 Variable minimum span
21 int8 Variable classification
22 Variable family
23 time Acquisition period
27 bin8 Variable properties
71 Lock Device 0 int8 Lock code 0 int8 Lock code
76 Read Lock State None 0 int8 Lock status
78 Read Aggregated Commands
0 int8 Number of commands requested 0 int8 Extended device status
1 str[] Array of command requests struct { int8 command int8 byteCount int8[] requestData }
1 int8 Number of commands requested
2 str[] Array of command responses struct { int8 command int8 byteCount int8 responseCode int8[] responseData }
HartTools
HartX 7.4.1 / 14.02.2014 Commonly Used Commands����33
No Title Request Data Response Data
Common Practice
792 Write Device Variable
0 int8 Device Variable Code 0 int8 Device Variable Code
1 DV command code 1 DV command code
2 DV units code 2 DV units code
3 float DV value 3 float DV value
7 int8 DV status 7 int8 DV status
103 Write Burst Period
0 int8 Burst message 0 int8 Burst message
1 time Update period 1 time Update period
5 Maximum update period 5 Maximum update period
104 Write Burst Trigger
0 int8 Burst message 0 int8 Burst message
1 Trigger mode selection code 1 Trigger mode selection code
2 Device variable classification for trigger level
2 Device variable classification for trigger level
3 Units code 3 Units code
4 float Trigger level 4 float Trigger level
105 Read Burst Mode Configuration
None 0 int8 Burst mode control code
1 int8 Burst command number
2 int8 Burst command slot 0
3 int8 Burst command slot 1
4 int8 Burst command slot 2
5 int8 Burst command slot 3
0 int8 Burst message 0 int8 Burst mode control code
1 0x1f (31) command expansion
2 DV code slot0
3 DV code slot1
4 DV code slot2
5 DV code slot3
6 DV code slot4
7 DV code slot5
8 DV code slot6
9 DV code slot7
10 Burst message
11 Maximum number of burst messages
12 int16 Extended command number
14 time Update time
18 Maximum update time
22 int8 Burst trigger mode code
23 DV classification for trigger value
24 Units code
25 float trigger value
106 Flush Delayed Responses
None None
2 Used to simulate the value of a device variable
HartTools
HartX 7.4.1 / 14.02.2014 Commonly Used Commands����34
No Title Request Data Response Data
Common Practice
107 Write Burst Device Variables
0 int8 DV code slot 0 0 int8 DV code slot 0
1 DV code slot 1 1 DV code slot 1
2 DV code slot 2 2 DV code slot 2
3 DV code slot 3 3 DV code slot 3
4 int8 DV code slot 4 4 int8 DV code slot 4
5 DV code slot 5 5 DV code slot 5
6 DV code slot 6 6 DV code slot 6
7 DV code slot 7 7 DV code slot 7
8 Burst message 8 Burst message
108 Write Burst Mode Command
0 int8 Command number for the burst response
0 int8 Command number of the burst response
109 Burst Mode Control
0 int8 Burst mode control code 0 int8 Burst mode control code
113 Catch Device Variable
0 int8 Destination DV code 0 int8 Destination DV code
1 Capture mode code 1 Capture mode code
2 Source slave manufacturer ID 2 int8[5] Source slave address
3 Source slave device type
2 int16 Source slave expanded device type
4 int8[3] Source slave device ID
7 int8 Source command number 7 int8 Source command number
8 Source slot number 8 Source slot number
9 float Shed time for this mapping 9 float Shed time for this mapping
7 int8 0x1f (31) command expansion 7 int8 0x1f (31) command expansion
8 Source slot number 8 Source slot number
9 float Shed time for this mapping 9 float Shed time for this mapping
13 int16 Ext source command number 13 int16 Ext source command number
114 Read Caught Device Variable
0 int8 Destination DV code 0 int8 Destination DV code
1 Capture mode code
2 int8[5] Source slave address
7 int8 Source command number
8 Source slot number
9 float Shed time for this mapping
7 int8 0x1f (31) command expansion
8 Source slot number
9 float Shed time for this mapping
13 int16 Ext source command number
523 Read Condensed Status Mapping Array
0 int8 Starting index status map 0 int8 Actual starting index
1 Number of entries to read 1 Number of entries returned
2 int4[] Status map codes array
524 Write Condensed Status Mapping Array
0 int8 Starting index status map 0 int8 Actual starting index
1 Number of entries to write 1 Number of entries returned
2 int4[] Status map codes array 2 int4[] Status map codes array
525 Reset Condensed Status Map
None None
526 Write Status Simulation Mode
0 int8 Status simulation mode 0 int8 Status simulation mode
527 Simulate Status Bit
0 int8 Status bit index 0 int8 Status bit index
1 Status bit value 1 Status bit value
HartTools
HartX 7.4.1 / 14.02.2014 Example Unit Codes����35
Example Unit Codes
1 InH2O
2 InHg
3 FtH2O
4 mmH2O
5 mmHg
6 psi
7 bar
8 mbar
9 g/cm²
10 kg/cm²
11 Pa
12 kPa
13 torr
14 ATM
15 Ft³/min
16 gal/min
17 l/min
18 ImpGal/min
19 m³/hr
20 ft/s
21 m/s
22 gal/s
23 MilGal/day
24 l/s
25 MilL/day
26 Ft³/s
27 Ft³/day
28 m³/s
29 m³/day
30 ImpGal/hr
31 ImpGal/day
32 °C
33 °F
34 °R
35 K
36 mV
37 Ohm
38 Hz
39 mA
40 gal
41 l
42 ImpGal
43 m³
44 ft
45 m
46 bbl
47 in
48 cm
49 mm
50 min
51 sec
52 hr
53 day
54 centi_stokes
55 cpoise
56 uMho
57 %
58 v
59 pH
60 g
61 kg
62 MetTon
63 lb
64 ShTon
65 LTon
70 g/s
71 g/min
72 g/hr
73 kg/s
74 kg/min
75 kg/hr
76 kg/day
77 MetTon/min
78 MetTon/hr
79 MetTon/day
80 lb/s
81 lb/min
82 lb/hr
83 lb/day
84 ShTon/min
85 ShTon/hr
86 ShTon/day
87 LTon/hr
88 LTon/day
89 reserved
90 SGU
91 g/cm³
92 kg/m³
93 lb/gal
94 lb/Ft³
95 g/ml
96 kg/l
97 g/l
98 lb/in³
99 ShTon/Yd³
100 degTwad
101 degBrix
102 degBaum_hv
103 degBaum_lt
104 degAPI
105 Percent_sol_wt
106 Percent_sol_vol
107 degBall
108 proof_vol
109 proof_mass
110 bush
111 Yd³
112 Ft³
113 in³
114-
119 reserved
120 m/h
121-
129 reserved
130 Ft³/h
131 m³/min
132 bbl/s
133 bbl/min
134 bbl/h
135 bbl/day
136 gal/h
137 ImpGal/s
138 l/h
139-
149 reserved
150 percent_StmQual
HartTools
HartX 7.4.1 / 14.02.2014 Packed ASCII Codes����36
151 Ftin16
152 Ft³/lb
153 pF
154-
159 reserved
160 Percent_plato
161-
234 reserved
235 gal/day
236 hl
237 mega-pascals
238 in_H2O_4_degrees_C
239 mm_H2O_4_degrees_C
240-
249 reserved
250 not_used
251 none
252 unknown
253 special
Packed ASCII Codes
PA ASC CHR PA ASC CHR PA ASC CHR PA ASC CHR
0 64 @ 16 80 P 32 32 48 48 0
1 65 A 17 81 Q 33 33 ! 49 49 1
2 66 B 18 82 R 34 34 „ 50 50 2
3 67 C 19 83 S 35 35 # 51 51 3
4 68 D 20 84 T 36 36 $ 52 52 4
5 69 E 21 85 U 37 37 % 53 53 5
6 70 F 22 86 V 38 38 & 54 54 6
7 71 G 23 87 W 39 39 ‘ 55 55 7
8 72 H 24 88 X 40 40 ( 56 56 8
9 73 I 25 89 Y 41 41 ) 57 57 9
10 74 J 26 90 Z 42 42 * 58 58 :
11 75 K 27 91 [ 43 43 + 59 59 ;
12 76 L 28 92 \ 44 44 , 60 60 <
13 77 M 29 93 ] 45 45 - 61 61 =
14 78 N 30 94 ^ 46 46 . 62 62 >
15 79 O 31 95 _ 47 47 / 63 63 ?
HartTools
HartX 7.4.1 / 14.02.2014 Device Status����37
Device Status
As response code 1 is command specific it is documented
together with the command specifications. However response
code 2 is of general nature and contains 8 bit flags with the
following meaning.
Flag Number / Meaning Description
Bit #7 Field Device Malfunction The device has detected a hardware error or failure. Further information may be available through the Read Additional Transmitter Status Command, #48.
Bit #6 Configuration Changed A write or set command has been executed.
Bit #5 Cold Start Power has been removed and reapplied resulting in the reinstallations of the setup information. The first command to recognize this condition will automatically reset this flag. This flag may also be set following a Master Reset or a Self Test.
Bit #4 More Status Available More status information is available than can be returned in the Field Device Status. Command #48, Read Additional Status Information, will provide this additional status information.
Bit #3 Primary Variable Analog
Output Fixed
The analog and digital analog outputs for the Primary Variable are held at the requested value. They will not respond to the applied process.
Bit #2 Primary Variable Analog
Output Saturated
The analog and digital analog outputs for the Primary Variable are beyond their limits and no longer represent the true applied process.
Bit #1 Non Primary Variable Out of
Limits
The process applied to a sensor, other than that of the Primary Variable, is beyond the operating limits of the device. The Read Additional Transmitter Status Command, #48, may be required to identify the variable.
Bit #0 Primary Variable Out of
Limits
The process applied to the sensor for the Primary Variable is beyond the operating limits of the device.
Appendix
Abbreviations
Abbreviation Description
HCF Hart Communication Foundation
DLL Windows: Dynamic Link Library
OSI-ISO: Data Link Layer
HAL Hardware Abstraction Layer
HART Highway Addressable Remote Transducer See also:
http://en.wikipedia.org/wiki/Highway_Addressable_Remote_Transducer_Protocol
HMI Human Machine Interface
ISO International Standards Organisation
MODEM MOdulator DEModulator
NV-memory Non-Volatile memory
OSAL Operating System Abstraction Layer
OSI Open Systems Interconnection
UART Universal Asynchronous Receiver Transmitter