hartx 7borst-automation.com/manuals/ba-hartx-7.4.1.pdf · 2016-11-21 · hartx 7.4.1 / 14.02.2014...

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

[email protected]

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


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


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


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


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


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


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


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


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


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


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


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


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





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


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).


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)


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)


p02Current float RO Value of the current output [mA]

p02Percent Value of the percentage 0..100 %

Command 3 (Read dynamic variables)


p01Pv float RO Value of process variable 1



p02Pv float Value of process variable 2









HartTools


Command 12 (Read Message)


p12Message string R/W Hart message, the string should have a length of 32

Command 13 (Read Tag, Descriptor, Date)


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)


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)


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


X-Properties (Any Command)

These properties are used to handle any command.


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


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


UnitCode In HART unit code

Returns

Visible string for the unit code

FillBuffer

void FillBuffer( byte FillValue)

BaHartX74.dll


FillValue In Byte to fill the buffer with (usually 0 or 0xff)

ValidateLicense

void ValidateLicense( string UserName, string License)

BaHartX74.dll


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


10 float PV2 value


15 float PV3 value


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



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



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


33 struct Slot4: 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



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



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



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



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



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



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




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



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



4 int8 DV code slot 4 4 int8 DV code slot 4




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

hartx 7borst-automation.com/manuals/ba-hartx-7.4.1.pdf · 2016-11-21 · hartx 7.4.1 / 14.02.2014...

Documents