Starter Kit Manual

WirelessHART Starter Kit Manual

Version 1.00

Date: December 01, 2011

Richard-Reitzner-Allee 6

85540 Haar Germany

Phone (++49) 89 45656-0 Fax (++49) 89 45656-399

Copyright 2011 by Softing Industrial Automation GmbH All rights reserved.

Page 2 of 41 WirelessHART Starter Kit Manual Confidential

File: Starter Kit Manual Version: 1.00

© 2011 SOFTING Industrial Automation GmbH No part of this document may be reproduced (printed material, photocopies, microfilm or other method) or processed, copied or distributed using electronic systems in any form whatsoever without prior written permis-sion of SOFTING Industrial Automation GmbH. The manufacturer reserves the right to make changes to the scope of supply as well as changes to technical data, even without prior notice. A great deal of attention was given to the quality and functional integrity in de-signing, manufacturing and testing the system. However, no liability can be assumed for potential errors that might exist or for their effects. Should you find errors, please inform your distributor of the nature of these errors and the circumstances under which they occur. We will be responsive to all reasonable ideas and will follow them up, taking measures to improve the product if necessary. We call your attention to the fact that the company name and trademark as well as product names are, as a rule, protected by trademark, patent and product brand laws. All rights reserved.



Contents

1. Introduction 6

2. Content of the WirelessHART Starter Kit 7

3. Getting Started 9 3.1. Regulatory Issues 9 3.2. Quick Start 9

4. Softing Field Device 11 4.1. Key Features and Functionality 12 4.2. Supported Commands 12 4.3. Factory Default Configuration 14

5. WD-H Development Board 15 5.1. Hardware 15 5.2. Board Setup 15 5.3. RS232 Interface 17 5.4. Pin Header 17 5.5. Schematic 18 5.6. Assembly Print 19 5.7. Development Board and PC Field Device 19

6. PC Field Device Software 20 6.1. Installation and Setup 21

6.1.1. System Requirements 21 6.1.2. Installation Steps 21

6.2. PCFD configuration 21 6.2.1. Command Line Switches 21 6.2.2. PCFD output 22 6.2.3. Implemented HART Commands 22

6.3. User Command Line Interface 22 6.4. Description of the XML Value File 23

6.4.1. General Structure of the XML Document 23 6.4.2. Comments 24 6.4.3. Data Type Syntax 24 6.4.4. Known Data Types 24 6.4.5. XML examples 24 6.4.6. Supported Values 25 6.4.7. Varying process values 27

6.5. Literature references 27 6.6. Microsoft Windows DLL dependencies 28

7. WDHI: WD-H interface example software of the communication API of the WD-H 29 7.1. WDHI Architecture 29

7.1.1. Requirement for the HOST 29 7.1.2. WDHI Source Files 30 7.1.3. WDHI Software Layers 31

7.1.3.1. PHY: Hardware Abstraction Layer 31



7.1.3.2. DLL: Serial Framing and Timing 31 7.1.3.3. API 31 7.1.3.4. RTOS 31 7.1.3.5. Host interface 32

7.2. Software Interfaces provided by the WDHI 32 7.2.1. WDHI Component Interface 32 7.2.2. Payload interface 33

7.3. Software Interfaces required by the WDHI 35 7.3.1. Host framework function 35 7.3.2. Payload Interface 38 7.3.3. Usage of RTOS 38



Modification Record

Date Version Author Description Status 1

15.06.11 0.1 KNA First draft B 28.09.11 0.2 KNA Update B 29.09.11 0.3 KNA Merge manual: starter kit v 0.2, FD v 0.3, PCFD v 0.7, WDHI v 0.2,

Dev Board v 0.3 B

29.09.2011 0.4 KNA Included net setup net id and join key B 18.11.2011 0.5 HTZ Finalizing, Layout, Structure, Spelling B

Test Record

Date Version Inspector Remarks/feedback by Status 2

Terms and Abbreviations

References / Sources

1Status: V=submitted, F=released; otherwise, in process (B=in process) 2Status: F=released; otherwise, submitted (B=returned for reworking)



1. Introduction

The WirelessHART Starter Kit is used to evaluate the functionality of the WirelessHART protocol defined by the HART Communication Foundation3. The Starter Kit offers an easy-to-use access to the complex world of the wireless low power mesh networks. The WirelessHART Starter Kit covers all technical levels from a pure application view down to the documentation of interfaces of the in-cluded hardware components. With the WirelessHART Starter Kit a user can simply build, evaluate, monitor and work with a WirelessHART network to get a vivid impression of the capabilities of Wire-lessHART.

3 www.hartcomm.org



2. Content of the WirelessHART Starter Kit



The WirelessHART Starter Kit contains the following components:

4 www.pepperl-fuchs.com

pos Component No. of components

Usage

1 Development Board includ-ing WD-H

1 Evaluation and development platform to interface microcontrollers or a PC to the WD-H

2 Field Devices 3 Field devices can run without any additional configu-ration or components. They are stand-alone Wireles-sHART devices able to join a WirelessHART net-work. They contain a temperature sensor and a bat-tery voltage sensor.

3 Antenna 4 2dBi dipole antenna for the 2.4 GHz band 4 Gateway 1 WirelessHART Gateway from Pepperl and Fuchs4 5 Gateway ante 5 Gateway Power Supply 1 Used to provide power to the WirelessHART gateway

including various adpaters 6 Development Board Power

Supply 1 Used to provide power to the development board

including various adpaters 7 Batteries 6 Used to provide power to the Field Devices 8 PC-Field Device Software 1 The PC Field Device Software is software that im-

plements the communication interface to the Wire-lessHART module WD-H. It can run in standard Win-dows XP™/ Windows 7™ machine and can be com-bined with the development board to build a Wireles-sHART device.

9 Serial Cable 1 To connect a PC running the PC Field Device Soft-ware and the development board

10 Coax Cable 1 Used to connect antenna to development board 11 Ethernet Cable 1 Used to connect Gateway and PC 12 Gateway Manual 1 Manual by Pepperl & Fuchs for the WirelessHART

Gateway 13 Starter Kit Manual 1 Includes 14 WD-H Manual 1 Manual for Softing’s WirelessHART module, the

WD-H 15 CD 1 Accommodates documentation and software 16 Getting Started 1 Quick Installation Guide



3. Getting Started

3.1. Regulatory Issues

Before starting a wireless network, please make yourself familiar with the guidelines and local restric-tions about radio communication. WirelessHART operates in the 2.4GHz band, which is regulated by local authorities in every country. The Starter Kit is tested and certified to be used without additional constraints in European countries regulated by the ITU and the USA. 3.2. Quick Start

With the WirelessHART Starter Kit you can build a WirelessHART network in 10 minutes. Follow the steps below:

1) start the WirelessHART gateway a. connect the gateway to your local network b. pre-configuration of the gateway:

i. the gateway is pre-configured to IP-address 192.168.1.1 ii. WirelessHART network is pre-configured to

1. NETID: 0x04CD 2. JOINKEY:

0x44,0x55,0x53,0x54,0x4E,0x,45,0x54,0x57,0x4F,0x52, 0x4B,0x53 0x52,0x4F,0x43,0x4B

c. provide power to the gateway d. try to access the website of the gateway from a pc in the network using a standard

browser on the url: http://192.168.1.1 e. Refer to the Wireless HART gateway manual when encountering any problems with

the network configuration i. If this IP address is not possible in your LAN, connect a PC in a bi-

directional connection and configure the IP settings as appropriate for your LAN

2) Assemble batteries in the Field devices and turn them on a. put two standard AA batteries in each field device b. place the field devices in any location you like, but make sure that they can establish

a radio connection to each other and the gateway. For the first setup: just place them on the same table right next to the gateway

3) Watch the status of the field devices a. after 9 Seconds, the red led “status” must blink fast (2 Hz) b. after some time the flashing-rate should go down to less than one flash per second,

then the device is successfully joined to the gateway c. watch the green “traffic” led on the field device. It should flash with a rate of approx 8

seconds 4) Watch the published sensor values in the website of the gateway

a. parameter -> Wireless Communication -> Instrument List b. select a device in the instrument list by clicking on it c. read the sensor values “PV, SV, TV, QV” on the right hand of the screen

5) Install the PC Field Device on a windows machine a. connect a serial port to the dev board b. start the PC Field Device software with the command line parameter for the serial

port used c. power the dev board by plugging in the power supply for the dev board



d. watch the PC Field Device console (several HART commands should be visible, e.g. command 0, 20)

6) The Development Board should also appear on the website of the gateway a. this may take some time b. advanced users:

i. watch the join process by issuing cmd 769 over the PCFD command line ii. Watch the PC Field Device joining the gateway by observing the console,

especially the “device join state” will change from “active search” to “quaran-tined” and to “operational”

7) Change the topologies by moving the field devices into different locations a. WirelessHART is capable to building a mesh-network, not every device needs to be

in direct radio contact to the gateway, devices can build connections between them to build a multi-hop connection to the gateway

b. When moving field-devices, the network connection can be interrupted when the ra-dio conditions have significantly changed. Then, the devices will automatically re-cover and build a new connection. Reforming of network may take long (up to 1 hour). Please refer to the documentation of the gateway for more details how to speed up this process.



4. Softing Field Device

The field device is a fully HART 7 compliant WirelessHART Field Device. It has onboard sensors and is interoperable with other commercial WirelessHART devices and infrastructure equipment. Please refer to the HART Communication Foundation for more information about WirelessHART. (www.hartcomm.org).

Interface Details Led red Indicates the network status of the field device:

• Blinking at high rate: active search mode • Blinking at 1 second rate: joining the

network • Blinking at 3 second rate: joined the

network Led green Indicates sensor values traffic Power switch Turn on/off the device Maintenance Port HART 7 compliant Maintenance Port Maintenance Port Switch Turn on/off the Maintenance Port. The Mainte-

nance Port should be turned off, when configura-tion is finished to save power

Antenna Batteries Standard 2xAA batteries 1.0-1.5V nominal per

cell

JTAG-Port of the WD-H

WD-H Module

JTAG-Port of the Field Device

Field Device base board

Connector for coaxial cable

Port for HART-ModemHART-Modem

On/Off Switch

Debug-Port(for internal use)

Connector for On/Off Switch

Temperature sensor

Coaxial cable for antenna

On/Off Switch

Battery holder

Label of the Field Device base board

Label of the WD-H

Antenna connector

JTAG-Port of the WD-H

WD-H Module

JTAG-Port of the Field Device

Field Device base board

Connector for coaxial cable

Port for HART-ModemHART-Modem

On/Off Switch

Debug-Port(for internal use)

Connector for On/Off Switch

Temperature sensor

Coaxial cable for antenna

On/Off Switch

Battery holder

Label of the Field Device base board

Label of the WD-H

Antenna connector



4.1. Key Features and Functionality

Feature Explanation Compliant HART 7.2 protocol Tested against HCF Compliance Kit 192, 193 Low power operation The field device can run several months on bat-

teries for long-term tests Maintenance Port The field Device has a Maintenance-Port that

can be used to configure HART and Wireles-sHART parameters such as network id and en-cryption keys5

Temperature sensor The user does not have to care about HART commands, The HART stack has an abstraction to separate the user application and the HART stack completely. The user does not have to care about timing, framing, packet generation

Ready-to-use configuration The field device is pre-configured to work with standard commercial gateways

4.2. Supported Commands

Softing’s Field Device supports commands that are mandatory for a compliant HART 7 Wireles-sHART Field device. Command number

Command Type Universal (u) / common practice (c) / wireless (w) / burst /(b)

Explanation

0 U Read Unique Identifier 1 U Read Primary Variable 2 U Read Loop Current 3 U Read Dynamic Variables and Loop Current 6 U Write Polling Address 7 U Read Loop Configuration 8 U Read Dynamic Variable Classification 9 U Read Device Variables with Status 11 U Read Unique Identified Assoc. with tag 12 U Read Message 13 U Read Tag, Descriptor, Date 14 U Read Primary Variable Transducer Information 15 U Read Device Information 16 U Read Final Assembly Number 17 U Write Message 5 Refer to the specification of the HART foundation for more information about the “Maintenance Port”



18 U Write Tag, Descriptor, Date 19 U Write Final Assembly Number 20 U Read Long Tag 21 U Read Unique Identifier Associated with long tag 22 U Write Long Tag 31 W Extend 8 to 16 Bit command 38 C Reset Configuration Changed Flag 41 C Perform self test 42 C Perform Device Reset 48 U Read Additional Device Status 54 C Read device variable Information 59 C Write Number of response preambles 78 C Read Aggregated Commands 79 C Write Device Variable 90 C Read Real-time-clock 106 C Flush delayed responses 103 B Write burst period 104 B Write burst trigger 105 B Read burst mode configuration 107 B Write burst device variables 108 B Write burst mode command number 109 B Burst mode control 115 B Read event notification summary 116 B Write event notification bit mask 117 B Write event notification timing 118 B Event notification control 119 B Acknowledge event notification 768-976 W All mandatory WirelessHART commands 128, 129, 131, 132, 133, 135, 139, 140, 141, 143

Device specific com-mands

reserved

Table 1 - supported commands



4.3. Factory Default Configuration

The factory default configuration can be reloaded by the following procedure:

1. turn off the device 2. turn on the maintenance port 3. turn off the device 4. wait for the green led to light constantly 5. within 8 seconds, turn off the maintenance port 6. wait for the device to join the networks, don’t turn it off before

Factory default values:

Item Value Unique ID Like given on the label Burst Messages 1 burst message: 8s period, burst cmd 3 WirelessHART network id 0x4CD WirelessHART join key 0x44,0x55,0x53,0x54,0x4E,0x45,0x54,0x57,

0x4F,0x52,0x4B,0x53,0x52,0x4F,0x43,0x4B WirelessHART active shed time 4000s WirelessHART join mode Join on power up WirelessHART long tag “Softing HART dev LONGTAG (ascii)” WirelessHART message “Message of Softing HART Device”



5. WD-H Development Board

5.1. Hardware

This board was designed to give the customer a test bench for evaluating the WirelessHART imple-mentation running on the WD-H module. The evaluation board has two different interfaces that can be used for an integration test. These interfaces are:

• Size: 55 x 70 mm • Power supply 5.0V • Electrical isolated RS232 interface • Pin header with access to all module signals

o Output low 0 to 0.6 V o Output high 2.4 to 3.0 V o Input low 0 to 0.9 V o Input high 2.1 to 3.0 V

The development board is powered by using the delivered power supply. The board generates the 3.0V supply for the WirelessHART module. 5.2. Board Setup

Attention: The Development Board is designed for th e use in laboratory environment only! Do not use the board in productive industrial envir onments!

Use only enclosed equipment to run the WirelessHART Development Board! The following picture shows the WirelessHART module mounted on the development board. The different connectors and there functionality can be seen.



Figure 1: Development Board Overview

To start working with the board the following steps must be done:

1) Connect the delivered power supply unit to the mains and on the other side to the power supply jacket on the development board.

2) Connect the development board to your PC via the enclosed serial cable. Remark: The slide switch has to be switched on (Figure 1 shows switch in ON position). The RS232 ON/OFF switch influences only the RS232 connector. The RS232 interface signals on the pin header are available at any time.

Power supply jacket

Reset Button JTAG Interface MMCX Antenna connector

RS232 Connector

RS232 ON/OFF-Switch

Pin Header



5.3. RS232 Interface

The RS-232 interface is available at the DSUB9 header X260. This is a female header.

Pin Number DSUB9 Interface Signal 1 N.C. 2 RXD 3 TXD 4 DTR 5 GND 6 N.C. 7 RTS 8 CD 9 N.C.

Table 2: RS232 pin out 5.4. Pin Header

There is a 20 pin header X110 to get an easier access to the WD-H module signals. The meaning and the direction of each pin is described in the following table. The direction is seen from the WD-H module, i.e. an output pin shall be an input of the field device controller. The pins are connected the same way like the pins of the WD-H module and have a direct connection to the WD-H. Pin 3, 4,8,11 are connected to the serial RS232 connection, but can also be accessed over the pin header. When doing so, the RS232-port must be switched “off”.



5.5. Schematic

Page 19 of 41 WD-H Manual Confidential

30.11.2011: File: Starter Kit Manual Version: 1.00

5.6. Assembly Print

5.7. Development Board and PC Field Device

The Development Board can be used in combination with the PC Field device. Simply start the PC Field Device on a personal computer under Windows and connect the serial line to the Development Board. The WD-H on the Development Board can then join a wireless network. See chapter 6



6. PC Field Device Software

The PC Field Device (PCFD) is a stand-alone, command line based PC application which runs on Microsoft Windows machines and provides a HART 7 field device refer-ence implementation in combination with the WD-H WirelessHART module. It emulates a complete HART 7 field device and provides all necessary functionality to build up a complete WirelessHART field device together with a WD-H module. The PCFD and the WD-H use communicate over a serial connection using HART pro-tocol frames www.hartcomm.org. The configuration and response payloads of com-mands can simply be changed by editing an XML file which contains name–value map-pings for several variables.

cmp Ov erv iew

Preconfigured Field Device

WD-H HW

PC

PCFD SW

Softing Interface (RS232)



6.1. Installation and Setup

6.1.1. System Requirements

The provided installer as well as the PCFD executable is designed to work with Micro-soft Windows XP as well as with Microsoft Windows 7. In addition, at least one free se-rial port is required to enable wired HART communication with the Softing WD-H mod-ule. USB-to-serial converters could also be used, if no serial port is directly available. The connection between the PC and the Softing WD-H must be established using the provided cable (standard RS-232 cable – ‘straight’).

6.1.2. Installation Steps

Just run the provided setup.exe installer file and follow the instructions. This will extract and copy all required components to an arbitrary folder. When the installer has finished, open a new terminal window and change to the folder which was selected as installation directory. Just type PCFD.exe to run the PC field device. For further details and configu-ration see next chapter.

6.2. PCFD configuration

6.2.1. Command Line Switches

The PCFD can be configured using command line switches which allow the user to se-lect the serial communication port as well as the baud rate to be used. Furthermore an XML file with variable configuration values must be specified as command line argu-ment (see also chapter 6.3). If you call the PCFD.exe with no argument the following help message should be dis-played:

PCFD.exe [options] xml_filename -p, --port Set the serial port of the Softing API (HART), e.g. "com1" for the first comport on windows. -b, --baudrate Set the baudrate, e.g. 19200 -h, --help Print this help message. xml_filename Path to XML file containing process values etc. Default values are: - com1 - 19200 baud Examples: # use comport 3 instead of the default port PCFD.exe -p com3 myxmlfile.xml



To use the provided example.xml with the PCFD which just sets all configuration vari-ables to valid values, type:

#>> PCFD.exe example.xml Press “CTRL + C” to exit the PCFD. The application may require a few seconds to ter-minate. Generally there is no need to change the baud rate if standard Softing WD-H modules are used. To get started with defining own variable values, it is recommended to make a copy of the given example.xml file and rename it. Instead of changing values directly in the example file keep the provided file as backup and make changes only in the re-cently created copy and pass the filename as argument to the PCFD.exe as shown above.

6.2.2. PCFD output

When the XML file is parsed correctly the PCFD will print out a list with all value names and the corresponding values. Otherwise if an XML parse error occurred the output pro-vides detailed information about the error. During normal run only incoming commands will generate terminal outputs. The request and response information of every processed command is printed with one blank line between each request: REQ [...] RSP [...] REQ [ <cmd number> ] (L:<len>) | <rsp payload> RSP [ <cmd number> ] (L:<len>) | (RC:<rsp code> DS: <dev status(hex)>) | <rsp payload> REQ [...] RSP [...]

6.2.3. Implemented HART Commands

The PCFD currently implements the following HART commands. All other commands are also answered but without any payload contained in the response and the response code is set to “Response Code – Not Implemented” which corresponds to 64. List of implemented HART Commands: 0, 1, 2, 3, 6, 7, 8, 9, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 38, 41, 42, 48, 54, 59, 78, 79, 90, 106

6.3. User Command Line Interface

The PCFD also implements a command line interface to send any valid and allowed command to the WD-H. This is done by typing the command with space-separated pay-load directly into the console when running the PCFD software. The syntax is “cmd a b



c d e”, where cmd is a command that can be executed via a maintenance port and “a b c d e” are the space-separated optional parameters. Here an example of a user issuing cmd 42 to reset the device and cmd 771 to start to join. The user types “42” and hits re-turn and then “771 1 0 0 0 0” and hits return. The red marked lines are the user inputs to the running console1. …. 42 send user request OUT - REQ [ 42 ] (L: 0) | IN - RSP [ 42 ] (L: 0) | (RC: 0 DS: x00) | IN - REQ [ 64519 ] (L: 1) | [00] OUT - RSP [ 64519 ] (L: 0) | (RC: 64 DS:0x0040) | [ ] IN - REQ [ 0 ] (L: 0) | [] OUT - RSP [ 0 ] (L:22) | (RC: 0 DS:0x0040) | [FE1234050700000400ABCDEF05000001000B16000081] 771 1 0 0 0 0 send user request OUT - REQ [ 771 ] (L: 5) | 01 00 00 00 00 IN - RSP [ 771 ] (L: 5) | (RC: 0 DS: x00) | 01 00 00 00 00 IN - REQ [ 64518 ] (L: 6) | [000000016702] OUT - RSP [ 64518 ] (L: 0) | (RC: 64 DS:0x0040) | [ ] IN - REQ [ 0 ] (L: 0) | [] OUT - RSP [ 0 ] (L:22) | (RC: 0 DS:0x0040) | [FE1234050700000400ABCDEF05000001000B16000081] IN - REQ [ 20 ] (L: 0) | [] OUT - RSP [ 20 ] (L:32) | (RC: 0 DS:0x0040) | [2021227468697320697320746865206C6F6E6720746167203 635343332313000]

6.4. Description of the XML Value File

6.4.1. General Structure of the XML Document

The general structure of an XML configuration document looks like the following:

<?xml version="1.0" encoding='UTF-8'?> <configuration_values> 

<value name="value_name"> xxx_value_xxx </value> ...

1 The console keeps running and printing during user input. If the user input is interleaved by an output print of the PCFD (e.g. reporting an incoming command) the user should go on typing and hit return at the end. The user command will still be valid and will be executed



... </configuration_values>

6.4.2. Comments

Comments may be added as necessary using the standard XML comment tag: 

Multi-line comments are also allowed: 

6.4.3. Data Type Syntax

The PCFD uses variables of different kind of types, e.g. integers, strings, etc. The val-ues within the XML document must apply to a specific syntax which is described in the following subsections. The data type of a variable is not directly defined within XML documents but it is implicitly defined via the variable name–data type mapping given the table in chapter 6.4.6.

6.4.4. Known Data Types

uint8 a 8-bit unsigned integer value, 0...255 uint16 a 16-bit unsigned integer value, 0...65536 uint24 a 24-bit unsigned integer value, 0...16.777.216 float a floating point number, single precision (4 bytes), IEEE-754 (see also

HCF_SPEC-099r9.0) pack8 a string of length 8 which can be packed to a 6 byte integer value by packing

each character to a 6-bit value, allowed ordinal values are 32..95 (see also HCF_SPEC-0.99r9.0 for full ASCI character sets)

pack16 the same as above, except the length of the string is 16 characters pack32 the same as above, except the length of the string is 32 characters latin32 string of length 32 using the “Latin-1” encoding (see also HCF_SPEC-

0.99r9.0 for full ISO Latin-1 character table) date date value, day, month, year time time value, hours, minutes, seconds

6.4.5. XML examples

See also XML demo file example.xml for more examples and next section “Supported Values”. uintx values can be given in decimal or hexadecimal format, e.g. 123, 10, 0x10,

0x88



float values can be integer values or floating point numbers with a ‘.’ as separator, e.g. 2, 2.25, -35.123

packx must be a string of the specified length (shorter strings will be padded with zeros), only a subset of the standard ASCI character set is allowed (ordinal values 32…95), e.g. “@ABCDEFG” (pack8), “HIJKLMNO12345678” (pack32)

latin32 must be a string of length 32, e.g. “AbCdEfGhIjKlMnOp(&)¶®©|ÖÄÜöäü÷*~ ” in latin-1 encoding

date must be given as string in the form of “DD.MM.YYY”, e.g. “15.01.2011 ” time must be given as string in the form of “hh:mm:ss”, e.g. “15:37:11 ”

6.4.6. Supported Values

The following table shows the variable name, type and default value of all required vari-ables. If a variable is not defined within the XML document, the default value below is used instead.

Variable name Value type Unit/Information Default value

expanded_device_type uint16 see common table 12 0x0000

min_preambles_M2S uint8 5

device_revision uint8 0

software_revision uint8 0

hardware_revision uint8 0

physical_signaling_code uint8 see common table 10 0x04

flags uint8 see common table 11 0x00

device_id uint24 0x000000

min_preambles_S2M uint8 5

max_number_device_variables uint8 99

configuration_change_counter uint16 0x0000

extended_device_status uint16 see common table 17 0x0000

manufacturer_code uint16 see common table 8 0x0000

private_label_distributor uint16 0x0000

device_profile uint8 see common table 57 0x00

pv_unit_code uint8 see common table 2 32

pv_value float unit see pv_unit_code 1.0

2 Common tables are defined by the HART Communication Foundation, specification documents can be ac-cessed by members of the HART Communication Foundation




pv_classification uint8 see common table 21 68

pv_status uint8 0

pv_device_variable_family_code uint8 see common table 20 250

pv_device_variable_command_code uint8 see common table 19 0x00

pv_loop_current float in mA 20.0

pv_percentage_range float in percent 50.0

sv_unit_code uint8 see common table 2 45

sv_value float unit see sv_unit_code 2.0

sv_classification uint8 see common table 21 69

sv_status uint8 0

tv_unit_code uint8 see common table 2 8

tv_value float unit see tv_unit_code 3.0

tv_classification uint8 see common table 21 70

tv_status uint8 0

qv_unit_code uint8 see common table 2 21

qv_value float unit see qv_unit_code 4.0

qv_classification uint8 see common table 21 71

qv_status uint8 0

polling_address uint8 0

loop_current_mode uint8 see common table 16 0x01

tag pack8 12345678

message pack32 “String text message of length 32”

descriptor pack16 “16 bytes descptr”

pv_transducer_serial uint24 0x000000

pv_transducer_code uint8 see common table 250

pv_transducer_upper_limit float 0x7fa00000

pv_transducer_lower_limit float 0x7fa00000

pv_transducer_minimum_span float 0x7fa00000

pv_alarm_selection_code uint8 see common table 6 250

pv_transfer_function_code uint8 see common table 3 0x00

pv_upper_range_value float 20.0




pv_lower_range_value float 5.0

pv_damping_value float 2.0

write_protect_code uint8 see common table 7 0x00

pv_analog_channel_flags uint8 see common table 26 0x00

final_assembly_number uint24 0x112233

long_tag str32 “AAAAAA-AAbbbbbbbbCCCCCCCCdddddddd”

current_date date <Current date>

current_time time <Current time>

clock_last_set_date date <Current date>

clock_last_set_time time <Current time>

rtc_flags uint8 see common table 42 0x00

If any of the values is not defined in the configuration file a warning is printed and the default value is used. The other way round, if a value is defined in XML but unknown, the value is also ignored and a warning is added to the output.

6.4.7. Varying process values

To not only support constant values but also varying process values (variables: PV, SV, TV, QV) a special symbol (‘#’) can be prepanded to a specific value within the XML file. The designated value is then increased by 1.0 every second . The varying-process-values mechanism is not limited to a single variable; it is possible to configure all process values with varying values. Examples: <value name="sv_value" >#2.25 </value> <value name="qv_value" >#0.00 </value>

6.5. Literature references

The documents referred to here are released by the HART Communication Foundation and are accessible by members of this organization

• “Universal Command Specification ”, HCF_SPEC-127r7.1, contains descrip-tions for command 0-22, 38, 48

• “Common Practice Command Specification ”, HCF_SPEC-151r9.1, contains descriptions for command 33-119, 512, 513



• “Common Tables Specification ”, HCF_SPEC-183r19.0, contains common ta-bles and values

• “Command Summary Specification ”, HCF_SPEC-099r9.0, contains general information, datatypes and status descriptions

6.6. Microsoft Windows DLL dependencies

The PCFD was built against standard Microsoft Windows libraries, the following files must therefore be present on the target system where the PCFD runs on:

• ole32.dll - WINDOWS\system32\ole32.dll • OLEAUT32.dll - WINDOWS\system32\OLEAUT32.dll • USER32.dll - WINDOWS\system32\USER32.dll • SHELL32.dll - WINDOWS\system32\SHELL32.dll • KERNEL32.dll - WINDOWS\system32\KERNEL32.dll • WSOCK32.dll - WINDOWS\system32\WSOCK32.dll • ADVAPI32.dll - WINDOWS\system32\ADVAPI32.dll • WS2_32.dll - WINDOWS\system32\WS2_32.dll • MSWSOCK.dll - WINDOWS\system32\MSWSOCK.dll

The files should be included in any standard Microsoft Windows XP and Windows 7 in-stallation.



7. WDHI: WD-H interface example software of the com munication API of the WD-H

WDHI is the abbreviation for Wireless Device HART Interface. Please refer to the manual and appli-cation notes of the WD-H product to get information about physical connection, link layer framing etc. This document focuses only on an explanation of the software example to implement a communica-tion between the WD-H and a field device. With the WDHI, a field device can easily be enabled with an interface to the WD-H to build a complete system. All aspects of error handling, framing and tim-ing are covered in the WDHI source code.

7.1. WDHI Architecture

7.1.1. Requirement for the HOST

When implementing the WDHI on a host system the WDHI requires several subjects: Requirement Area Value Code size3 ROM/Flash memory of the Host ~5k Memory Size RAM memory of the HOST ~1k Control of interrupts SW framework of the HOST Enabling/disabling interrupts Tasks RTOS (when used) 1 Serial Module HW Modules of HOST for

frame communication 1 serial module like UART

3 Code sizes have been evaluated on a ARM7 core

Field Device Host Processor

WD-H Modu-le

WDHI Source Code

Field Device Firmware (Application and Sensor Driver)

serial interface

Software API

WDHI Source Code and focus of this documentation



I/O HW Pins of the HOST for pro-tocol handshaking

2

Timer Software or hardware-timer 1

7.1.2. WDHI Source Files

These source files are extracted from the implementation of Softing’s Field device of the Wireles-sHART Starterkit. They do not form a complete project nor do they include a full implementation of a field device. These files can be understood as a reference implementation for the interface to the WD-H. Files that belong to the hardware abstraction layer of this example code include and use further inter-faces and functions of modules not described here. Implementation of the HAL is always platform-specific and not in the scope of this documentation. File Content wdhi.c Implementation of the WDHI: basis functionality

to interface a field device with the WD-H includ-ing packet creating, packet reception

wdhi_if.h Interface declaration of the WDHI wdhi_comp.h Declaration and defines for the wdhi implementa-

tion defines.h For global file identification hart_common.h Global definitions for HART commands and re-

turn codes cfg_cc.h Global definitions for compiler, types and con-

versions wdhi_hal_hw.h wdhi_hal_cfg.h

Abstraction layer for registers of I/O and UART on Freescale MC13224

wdhi_hal.h Interface declaration of the hal-functions platform_freescale.h Definitions for the freescale MC13224 wdhi_hal.c Implementation of the HAL for the MC13224

including packet transmission and reception over UART, control of handshake lines, timing of characters and gaps



7.1.3. WDHI Software Layers

7.1.3.1. PHY: Hardware Abstraction Layer

The HAL of the WDHI implements the necessary control of the underlying hardware used by the WDHI. The according files must be adjusted to the underlying platform

7.1.3.2. DLL: Serial Framing and Timing

The DLL (Data Link Layer) includes the implementation of handshaking, framing, error check, re-peating and rejecting of messages. This layer must not be achanged

7.1.3.3. API

The API is the user interface to the WDHI. It provides function to control the WDHI and to receive and transmit HART commands to and from the WD-H

7.1.3.4. RTOS

This module is the wrapper for the underlying real time operation system. The use of an RTOS is highly recommended

WDHI Software

PHY: Hardware Abstraction Layer

DLL: Serial Framing and Timing, Control of Handshaking

API: User API for request, response Optional: Interface to RTOS

Host interface



7.1.3.5. Host interface

The host interface is needed by the WDHI to use external functions like timer, control of interrupts 7.2. Software Interfaces provided by the WDHI

Function Description bool wdhi_init() Call to initialize the WDHI bool wdhi_start() Call to start operation of WDHI bool wdhi_stop() Call to stop /interrupt the operation of the WDHI bool wdhi_request_transmit( T_HART_BUFFER *HARTbuffer );

Call to trigger a request to the WDHI

bool wdhi_response_confirm( T_HART_BUFFER *HARTbuffer );

Call to answer to a request from the WDHI

void wdhi_set_local_address( uint8_t *longAddress );

Obsolete, don’t use

7.2.1. WDHI Component Interface

bool wdhi_init( void )

Parameter

-

Return value

-

Description

Call this to initialize the wdhi software component



bool wdhi_start( void )

Parameter

-

Return value

-

Description

Call this to start operation of the WDHI

bool wdhi_stop( void )

Parameter

-

Return value

-

Description

Call this to stop operation of the WDHI, the start() can be called afterwards

7.2.2. Payload interface

The payload request interface is used to communicate commands between the host and the WD-H The request / response-interface uses HARTbuffers. A HARTbuffer is a structures which are used to store and exchange HART command requests and responses. They contain the payload of the HART command and all side information required, i.e. the HART command number, response code, payload length and control information for command distribution and identification. The definition is as following: typedef struct { uint16_t command; uint16_t uniqueID; uint8_t source; uint8_t sourceHART; uint8_t responseCode; uint8_t payloadLength; uint8_t payload[ HART_PAYLOAD_LENGTH_MAX ]; } T_HART_BUFFER;

Element Description



uint16_t command Command number of the request or response. uint16_t uniqueID Unique identification used by the creator of a HART request to identify the re-

sponse. A processing module shall not alter the response. In HART responses used for publishing the unique ID has a special function, identifying the service used for publish (see chapter Fehler! Verweisquelle konnte nicht gefunden werden.Fehler! Verweisquelle konnte nicht gefunden w erden. ).

uint8_t source Control handle used for command distribution. Must be set by the creator of the request (see Fehler! Verweisquelle konnte nicht gefunden werden. ).

uint8_t sourceHART Additional information to indicate which master sent the request. uint8_t responseCode If the HARTbuffer is used to store a response, the responseCode is stored here. uint8_t payloadLength Real length of the payload. uint8_t payload[] Buffer to store the request or response payload. Currently size of the buffer is

128 bytes.

bool wdhi_request_transmit( T_HART_BUFFER *HARTbuff er )

Parameter

T_HART_BUFFER *hartRequest

Reference to HARTbuffer containing the request.

Return value

-

Description

Called by the host to send a request to the WD-H (via WDHI). the function makes a copy of the HARTBuffer, which can be freed after the return of the request()-call. After completion of the request on the remote side, the wdhi_response_indicate() will be called

bool wdhi_response_confirm( T_HART_BUFFER *HARTbuff er )

Parameter

T_HART_BUFFER *hartRequest

Reference to HARTbuffer containing the res.

Return value

-

Description

Called by the host to give the response to a previously received request. The function makes a copy of the HARTBuffer, which can be freed after the return of the call



7.3. Software Interfaces required by the WDHI

Function Description void wdhi_os_enable_interrupts( void ); Called to globally enable interrupts void wdhi_os_disable_interrupts( void ); Called to globally disable interrupts void wdhi_timer_init( void ); Called to initialize the timer used by the WDHI void wdhi_timer_start( uint64_t ticks, T_WDHI_TIMER handler );

Called to start the wdhi timer and give callback function

void wdhi_timer_cancel( void ); Called to cancel a previous start of the wdhi timer

bool wdhi_request_indicate( T_HART_BUFFER *HARTbuffer );

Called when a request is incoming

bool wdhi_response_indicate( T_HART_BUFFER *HARTbuffer );

Called when a response is incoming

bool wdhi_os_task_create( T_WDHI_TASK main );

Called to setup a task in the host RTOS

void wdhi_os_event_signal( T_WDHI_EVENT events );

Called to send an event to the wdhi-task

T_WDHI_EVENT wdhi_os_event_wait(_WDHI_EVENT events );

Called to blocking-wait for an event

T_WDHI_EVENT wdhi_os_event_clear( T_WDHI_EVENT events );

Called to clear obsolete events

7.3.1. Host framework function

These functions must be provided as general functionality to the WDHI

void wdhi_os_enable_interrupts( void )

Parameter -

Return value

-

Description

Called by the WDHI to enable interrupts globally. This is needed for protection against concurrent access of data from main-loop or task and interrupts



void wdhi_os_disable_interrupts( void )

Parameter -

Return value

-

Description

Called by the WDHI to disable interrupts globally. This is needed for protection against concurrent access of data from main-loop or task and interrupts

void wdhi_timer_init( void )

Parameter -

Return value

-

Description

Called by the WDHI once at the startup to initialize the timer for the WDHI. Here, the host can initialize the timer (software or hardware) for the WDHI.

void wdhi_timer_start( uint64_t ticks, T_WDHI_TIMER handler )

Parameter uint64_t ticks T_WDHI_TIMER handler

Timeout of the timer of the WDHI in the unit “ticks”. One tick is 1/32768 s The function to be called back when timer lapses. T_WDHI_TIMER is a “void fkt(void)”

Return value

-

Description

The WDHI expects the timer callback to be called when the timeout occurs.



uint8_t wdhi_device_status_get( void )

Parameter -

Return value

-

Description

The WDHI the host to return the current HART status byte

void wdhi_device_status_cold_start_reset( void )

Parameter -

Return value

-

Description

Called by the WDHI to reset the cold start flag in the device status of the host HART device. This occurs on reception of the first command



7.3.2. Payload Interface

The interface uses HART Buffer (see chapter 7.2.2)

bool wdhi_request_indicate( T_HART_BUFFER *HARTbuff er );

Parameter

T_HART_BUFFER * HARTbuffer

Reference to HARTbuffer containing the request.

Return value

-

Description

Called by the WDHI on an incoming command request. The given HARTbuffer is only valid during execution of this function. Any reference to the Buffer must be release after returning. The user-application must make a copy of the buffer during execution and not hold any reference after return

bool wdhi_response_indicate( T_HART_BUFFER *HARTbuf fer );

Parameter

T_HART_BUFFER * HARTbuffer

Reference to HARTbuffer containing the response.

Return value

-

Description

Called by the WDHI on an incoming command response. The given HARTbuffer is only valid during execution of this function. Any reference to the Buffer must be release after returning. The user-application must make a copy of the buffer during execution and not hold any reference after return

7.3.3. Usage of RTOS

The use of an RTOS on the Host system is highly recommended. Without the use of an RTOS, ma-jor functionality of handling of packets and preparing frames will be executed in the context of inter-rupts. This introduces relevant latencies to the overall Host system. With the use of an RTOS, interrupt service routines can be kept small and efficient, all other process-ing can be executed in the context of tasks to support priorities of operations in the host system.



For turning on and off the RTOS, use the define in wdhi_if.h #define WDHI_RTOS_USE When the expression is defined, then the WDHI expects an underlying RTOS When using an RTOS, the user must implement a wrapper to the calls of the RTOS. The following functions must be implemented:

Bool wdhi_os_task_create(T_WDHI_TASK main)

Parameter

T_WDHI_TASK main

Reference to the structure holding all information about the task needed for the WDHI The T_WHDI_TASK type must be implemented as needed

Return value

True on successful creation of the task False if task was not created

Description

The WDHI calls this function to install it’s own task inside the hosting RTOS.



Bool wdhi_os_event_signal(T_WDHI_EVENTS events)

Parameter

T_WDHI_EVENTS events

A bit mask containing bits set on active events. The T_WDHI_EVENTS is typically defined as UINT8

Return value

True on successful sending the event mask False if error occurred

Description

The WDHI calls this function to send events to its task

T_WDHI_EVENTS wdhi_os_event_wait(T_WDHI_EVENTS even ts)

Parameter


A bit mask containing bits set on events that the WDHI is waiting for. T_WDHI_EVENTS is typically defined as UINT8

Return value

The bitmask containing the events that have been send to the task

Description

The WDHI calls this function to wait for events in its task and to yield control to the os if no events are there. This function should block.



T_WDHI_EVENTS wdhi_os_event_clear(T_WDHI_EVENTS eve nts)

Parameter


A bit mask containing bits set on events that can be cleared. T_WDHI_EVENTS is typically defined as UINT8

Return value

The bitmask containing the events that are still available for the task

Description

The WDHI calls this function to clear event that have been processed or are irrelevant.

Documents

Starter Kit Manual