HART Device Stack - Softing · Chapter 1 - Introduction HART Device Stack - User Manual 5 1 Introduction 1.1 About product The Softing HART Device Stack is an easy portable protocol

© Copyright 2015 Softing Industrial Automation GmbH

Protocol Software for Field Devices

HART Device Stack

User Manual

Version: 062015-EN-1.10

The information contained in these instructions corresponds to the technical status at the time of printing of it and ispassed on with the best of our knowledge. The information in these instructions is in no event a basis for warrantyclaims or contractual agreements concerning the described products, and may especially not be deemed as warrantyconcerning the quality and durability pursuant to Sec. 443 German Civil Code. We reserve the right to make anyalterations or improvements to these instructions without prior notice. The actual design of products may deviate fromthe information contained in the instructions if technical alterations and product improvements so require.

It may not, in part or in its entirety, be reproduced, copied, or transferred into electronic media.

Disclaimer of liability

Softing Industrial Automation GmbH

Richard-Reitzner-Allee 685540 Haar / GermanyTel: + 49 89 4 56 56-0Fax: + 49 89 4 56 56-488Internet: http://industrial.softing.comEmail: [email protected]: [email protected]

The latest version of this manual is available in the Softing download area at: http://industrial.softing.com.

Table of Contents

HART Device Stack - User Manual 3

Table of Contents

Chapter 1 ..................................................................................5Introduction

................................................................................................ 51.1 About product

................................................................................................ 51.2 About this document

...................................................................................................... 5Document history 1.2.1

...................................................................................................... 5Target group 1.2.2

...................................................................................................... 6Conventions used 1.2.3

Chapter 2 ..................................................................................7System requirements

................................................................................................ 72.1 General requirements

................................................................................................ 82.2 Renesas M16C specific requirements:

................................................................................................ 82.3 Supported platforms

Chapter 3 ..................................................................................9Key features

Chapter 4 ..................................................................................10Software architecture

................................................................................................ 104.1 Software Components

................................................................................................ 114.2 HART Stack API for a HART device

Chapter 5 ..................................................................................12Short instructions

Chapter 6 ..................................................................................13List of supported HART commands

Chapter 7 ..................................................................................14HART stack porting guideline

................................................................................................ 147.1 Overview

................................................................................................ 147.2 Procedure

Chapter 8 ..................................................................................16Build your own device

................................................................................................ 168.1 Device identification and configuration

................................................................................................ 178.2 Device data base

................................................................................................ 178.3 Define dynamic variables

................................................................................................ 188.4 Define device variables

................................................................................................ 198.5 Mapping of device variables to dynamic variables

................................................................................................ 198.6 Device specific status

................................................................................................ 198.7 HART command implementation

................................................................................................ 208.8 User Application

................................................................................................ 208.9 Sensor Application

................................................................................................ 218.10 Sensor API Modes: Push and Pull

................................................................................................ 218.11 Sample Application

HART Device Stack - User Manual

Table of Contents

4

...................................................................................................... 21Command 150 – Read RAMP Sensor configuration 8.11.1

...................................................................................................... 22Command 151 – Write RAMP Sensor configuration 8.11.2

................................................................................................ 228.12 Sample device-specific commands

...................................................................................................... 23Command 128 – Set Device ID 8.12.1

...................................................................................................... 23Command 129 – Set Expanded Device Type 8.12.2

...................................................................................................... 24Command 131 – Set Additional Configuration Parameters 8.12.3

...................................................................................................... 25Command 132 – Set Sensor Polling Timeout 8.12.4

...................................................................................................... 25Command 133 – Get Sensor Polling Timeout 8.12.5

...................................................................................................... 25Command 136 – Read Firmware Version String 8.12.6

...................................................................................................... 26Command 139 – Set MSA Bit and Extended Device Status 8.12.7

...................................................................................................... 26Command 140 – Reset Extended Device Status 8.12.8

...................................................................................................... 26Command 141 – Modify Extended Status 8.12.9

...................................................................................................... 27Command 143 – Reset to Factory Defaults 8.12.10

Chapter 9 ..................................................................................28Software component interfaces

................................................................................................ 289.1 Configuration module

................................................................................................ 319.2 Sensor application

................................................................................................ 319.3 Operating system interface

................................................................................................ 429.4 Low power interface

Chapter 1 - Introduction


1 Introduction

1.1 About product

The Softing HART Device Stack is an easy portable protocol software solution toimplement a field device communication fully to HART 7.5. It includes all universalcommands and some common practice commands.

1.2 About this document

Read this manual before starting

For damages due to improper connection, implementation or operation Softingrefuses any liability according to our existing warranty obligations.

This document refers to the HART protocol release by the HART CommunicationFoundation (www.hartcomm.org). The protocol stack covers all relevant parts of theprotocol layers from Hardware Abstraction up to the Application level. Two main scenariosare covered by the HART stack protocol implementation: first, to provision a stand-alonewired HART field device with a stack and second, to enable a wireless field device forcompliant HART communication with low power consumption and interoperability viamaintenance port.

1.2.1 Document history

Document version Modifications compared to previous version

1.00 - initial version none

1.10 Document completely reworked:

New structure according to Softing standard structure.

New Chapter "Building your own device".

New section "Low power interface".

1.2.2 Target group

The reader of this document should be familiar with HART communication protocol andthe HART communication specifications.

http://www.hartcomm.org

Chapter 1 - Introduction

6 HART Device Stack - User Manual

1.2.3 Conventions used

The following conventions are used throughout Softing customer documentation:

Keys, buttons, menu items, commands andother elements involving user interaction areset in bold font and menu sequences areseparated by an arrow

Open Start Control Panel Programs

Buttons from the user interface are enclosedin brackets and set to bold typeface

Press [Start] to start the application

Coding samples, file extracts and screenoutput is set in Courier font type

MaxDlsapAddressSupported=23

Filenames and directories are written in italic Device description files are located in C:\StarterKit\delivery\software\DeviceDescription files

CAUTION

CAUTION indicates a potentially hazardous situation which, if not avoided, mayresult in minor or moderate injury.

Note

This symbol is used to call attention to notable information that should befollowed during installation, use, or servicing of this device.

Hint

This symbol is used when providing you with helpful user hints.

Chapter 2 - System requirements


2 System requirements

The HART Device Stack protocol implementation is highly portable., under the followinggeneral requirements:

Requirement Details

Supporting operating system RTOS must support:

multiple tasks with >2 different priorities

pre-emptive scheduling

counting semaphores

mailboxes

events for task (>=8bit mask size)

priority inversion

Non-volatile memory Access to non-volatilememorylikeEEPROM, Flash

Low frequency oscillator Typically 32768 Hz Oscillator

FSK HART Physical layer AcircuitimplementingtheFSKphysicallayerfor the HART protocol (e.g. FSK HARTmodem)

CPU CPU clock can be chosen to be less than 4MHz,see platformspecificrequirementsections.

HW-Timer 1 hardware timer, resolution <1ms

For controller-specific requirements see following sections. Porting the source code toanother platform may result in different memory and performance requirements.

2.1 General requirements

General requirements for the HART stack protocol implementation are:

Requirement Details

Supporting operating system RTOS must support:

multiple tasks with >2 different priorities


counting semaphores

mailboxes

events for task (>=8bit mask size)

priority inversion

Non-volatile memory Access to non-volatilememorylikeEEPROM, Flash

Chapter 2 - System requirements


Requirement Details

Low frequency oscillator Typically 32768 Hz Oscillator

FSK HART Physical layer AcircuitimplementingtheFSKphysicallayerfor the HART protocol (e.g. FSK HARTmodem)

CPU CPU clock can be chosen to be less than 4MHz,see platformspecificrequirementsections.

HW-Timer 1 hardware timer, resolution <1ms

For controller specific requirements see following sections. Porting the source code toanother platform may result in different memory and performance requirements.

2.2 Renesas M16C specific requirements:

Requirement Details

CPU Current setup uses 4 MHz CPU clock

Memory, burst support RAM: 6 k ROM: 35 k

2.3 Supported platforms

Currently, the HART protocol stack is implemented on a Renesas M16C controller usingembOS RTOS with suitable periphery like UART, NV-RAM etc. The code is highly portableto other architectures and semiconductor families.

Chapter 3 - Key features


3 Key features

Feature Explanation

Compliant HART 7.5 protocol Tested against HCF Compliance Kit 192 V3.0

Burst The HART stack implements a compliantburst module

Low power operation The HART stack provides interfaces for low power operation e.g. it can be applied tobattery-operated devices

Software framework The HART stack is embedded in a powerfuland flexible software framework providing aprogramming structure and abstractionmethodology

Example code The code is ready to run and prepared with a user component

HART Command abstraction and userinterface

The HART stack has an abstraction toseparate the user application and the HARTstack completely. The user does not have tocare about timing, framing and packetgeneration.

Push and pull Sensor interface Comfortable interface to update local sensorvalues based on automatic periodic requestsfrom the HART stack (pull) or active userupdates (push)

Chapter 4 - Software architecture


4 Software architecture

4.1 Software Components

Component overview

Module list

Software Module Description

Data Link Layer Managing framing, CRC, timing, token control

Command Distributor Distribution and queuing of HART commands

Burst Module ExecutionofBurstCommands,controlandupdateofburstmessage, publishing sensor values

Command Handler Handling of the supported HART commands

Configuration ConfigurationoftheDeviceandtheparametersoftheHART protocol

NV Memory Permanent storage of parameters and states like required by theHART specification

Sensor Application Implementation of sensor-related HART commands, monitoringand mirroring of all local sensor values, post processing andvariable assignment. Push and pull sensor update support

Device Status Control of the HART device status

Chapter 4 - Software architecture


Software Module Description

Timer Generic Software module for Software timers used throughoutthe system

Operating System Interface to the underlying operating system. The HART DeviceStack requires an OS.

User Application The implementation of the field device logic, mainly the control ofsensors and the device hardware. This component has aninterface to the sensor application to update the sensor valuesused by the HART stack

4.2 HART Stack API for a HART device

The user-application resides in the Component User Application and uses theConfiguration as well as the Sensor Application interface. It can furthermore also use othercomponents like the Timer and so on.

A typical user application looks like this (pseudo code):

Void user_task(void)

{

Configuration.writePVunitcode(TEMP_FAHRENHEIT);

While (1)

{

Sleep(30s)

Temp =My_sensor_read();

sensorApp.update(PV,temp);

}

}

In the initialization, the user sets parameters like the variable mapping and the variable unitcodes. Then, all the user has to do is to update periodically the sensor value, all burst andother HART- related functionality is handled by the stack.

Chapter 5 - Short instructions


5 Short instructions

When using the HART stack for a stand-alone HART device, the following steps have tobe worked through to obtain a running HART application:

1. Porting the Hardware abstraction layer to the HOST processor

a. byte-oriented data control via a serial interface (typically UART)

b. hw timer for the timer component

c. I/O control for HART-handshaking

2. Porting the operating system

a. Use a currently supported RTOS or

b. implement the wrapper for the OS used on the HOST processor

3. Implementing the User Application

a. Implement a driver for your sensor

b. Update the sensor values in the hart stack

Afterwards, you can read the sensor values over a compliant HART master by e.g. issuingcommand 1 or install a burst to periodically get the sensor value.

Chapter 6 - List of supported HART commands


6 List of supported HART commands

Commandnumber

Explanation Universal (u), / common practice(c), device specific command (d),burst (b)

0 Read unique id ( u )

1 Read primary variable ( u )

2 Read loop current ( u )

3 Read dynamic variables ( u )

6 Write polling address ( u )

7 Read loop configuration ( u )

8 Read dynamic variable classification ( u )

9 Read device variables ( u )

11 Read unique id with tag ( u )

12 Read message ( u )

13 Read tag, descriptor, date ( u )

14 Read primary transducer information ( u )

15 Read device information ( u )

16 Read final assembly number ( u )

17 Write message ( u )

18 Write tag, descriptor, date ( u )

19 Write final assembly number ( u )

20 Read long tag ( u )

21 Read unique id with long tag ( u )

22 Write long tag ( u )

31 Extended command wrapper ( c )

38 Reset configuration change flag ( u )

41 Perform self test ( c )

42 Reset device ( c )

48 Read additional status ( u )

50 Read dynamic variable assignment ( c )

54 Read device variable information ( c )

59 Write number of preambles ( c )

103 Write burst period ( b )

104 Write burst trigger ( b )

105 Read burst mode configuration ( b )

107 Write burst device variables ( b )

108 Write burst mode command number ( b )

109 Burst mode control ( b )

Chapter 7 - HART stack porting guideline


7 HART stack porting guideline

This section provides an overview and a step-by-step porting guideline which enablesdevelopers to run Softing’s HART stack on almost every platform which supports acommon RTOS.

7.1 Overview

Make sure that the whole development setup is complete before you start. This includes

Target platform compiler tool-chain and development software

Development hardware, development board, etc. including HART connection HART-modem(s), one for the slave and one for the master, PC, etc.

PC development tools and software (i.e. HART-master script)

Once the setup is complete, you should first get the latest HART protocol stack code fromyour contact partner at Softing.

Basically the source code will contain at least two top level folders:

base

target

The base folder contains all platform and customer application independent code like high-level component implementation and application level code. Make sure to always thinkabout where to place a newly created file within this structure. Only platform independentfiles should make it in the base folder.

The target folder comprised all files that are dependent on the target hardware or targetapplication, i.e. which have to be adopted within the project implementation.

7.2 Procedure

First step is to setup a platform and compiler specific make process or another suitablebuild process which is aware of compiling and linking files from different sources into onebinary file. Best thing to do here is to have a look at the existing makefile process setup.

We recommend first implementing just stubs or empty modules/files of hardwarecomponents and make the code compile again. After that hardware modules can beimplemented one after another.

This basically includes:

platform-specific setups/settings (e.g. setup processor modes, interrupt sources, pinsetup, etc.)

OS abstraction (only necessary if not using embOS)

hardware timer files, including RTC, etc.

hardware HART interface (i.e. RX, TX, handshaking)

sensor driver implementation

The module order stated above is also the suggested order of implementation, as itenables developers to test the code after each step.

Chapter 7 - HART stack porting guideline


In this order, as a first step, the underlying platform should be correctly initialized andworking. This contains pin direction setup, CPU clock source selection, general UART/communication setup, etc.

If this all works, the next step would be moving on to other modules now, you should firstpick the basic ones like OS abstraction layer and timer, since both components arealmost used by any other component.

After that we recommend implementing the hardware HART interface and then all othermodules which are left over.

If everything is implemented according to hardware interface and underlying functions, theHART stack should work as expected.

Chapter 8 - Build your own device


8 Build your own device

With Softing’s HART Device Stack as framework, you are enabled to develop your ownField Device.

The following sections guide you to integrate your Sensor Application into the HARTDevice Stack framework.

8.1 Device identification and configuration

The following information needs to be defined for each device:

Manufacturer ID

Device Type

Device Revision

Max Number of Device Variables

HART Protocol Major Revision

Software Revision Level

Hardware Revision Level

Physical Signaling Code

Minimum Number of Preambles required within Master requests

Minimum Number of Preambles send with response messages to Master

Device ID

Flags

Private Label Distributor Code

Device Profile

Polling Address

Loop Current Mode

Short Tag

Descriptor

Date Code

Write Protect Code

Final Assembly Number

Long Tag

This information must be defined in:

variable devConfigDefault contained in module target\sys\src\config_comp.c



command 0 handler fdu_process_unique_id() contained in module base\appl\src\fd_universal.c

The majority of information listed above is contained in command 0 responses that areused to return identity information about the Field Device.

For detailed information, refer to “Universal Command Specification” (HCF_SPEC-127,Rev 7.1) and “Common Tables Specification” (HCF_SPEC-183, Rev 23.0).

8.2 Device data base

All universal commands and a sub-set of common practice commands are alreadyimplemented in the Softing HART Device Stack.

The universal command handlers are implemented in module base\appl\src\fd_universal.c and the common practice command handlers are implemented in modulebase\appl\src\fd_common.c.

The storage of information needed to fill universal and common practice commandresponses with the required values as well as the storage of received values received withcommand requests, must be implemented by the Field Device Developer.

For detailed information, refer to “Universal Command Specification” (HCF_SPEC-127,Rev 7.1) and “Common Practice Command Specification” (HCF_SPEC-151, Rev 10.0).

8.3 Define dynamic variables

A Dynamic Variable consists of a Device Variable and an analog channel.

Each Field Device may support up to four Dynamic Variables, Primary Variable (PV),Secondary Variable (SV), Tertiary Variable (TV) and Quaternary Variable (QV).

The PV needs to be supported by each Field Device, the others are optional variables.

For the Dynamic Variable PV the following information needs to be provided to someuniversal command handler functions in module base\appl\src\fd_universal.c.

PV Loop Current

PV Percent of Range

PV Transducer Serial Number

PV Transducer Limits/Span Units Code

PV Upper Transducer Limit

PV Lower Transducer Limit

PV Minimum Span

PV Alarm Selection Code

PV Transfer Function Code

PV Upper/Lower Range Units Code

PV Upper Range Value



PV Lower Range Value

PV Damping Value

PV Analog Channel Flags

Depending on the number of Dynamic Variables the command 3 handler functionfdu_process_read_dynamic() in module base\appl\src\fd_univeral.c needs to be updatedto respond only the supported Dynamic Variables.

For detailed information, refer to “Command Summary Specification” (HCF_SPEC-099,Rev 9.0) and “Universal Command Specification” (HCF_SPEC-127, Rev 7.1).

8.4 Define device variables

Device Variables provide process related information and the Device Variable’s valuereflects the connect process value, like temperature, pressure and so on.

When all Device Variables are added, the total number of Device Variables needs to beset as Max Number of Device Variables (see also Device identification and configuration

).

As required by the HART specification, the Device Variables Percent Range (DeviceVariable Code 244), Loop Current (245), Primary Variable (246), Secondary Variable(247), Tertiary Variable (248) and Quaternary Variable (249) are already implemented inSofting’s HART Device Stack.

The Field Device Developer must define the information (see list below) of these existingDevice Variables.

If more Device Variables are required, a Field Device developer may define the neededamount of Device Variables with the following information:

Device Variable Code

Device Variable Transducer Serial Number

Device Variable Limits/Span Units Code

Device Variable Upper Transducer Limit

Device Variable Lower Transducer Limit

Device Variable Damping Value

Device Variable Minimum Span

Device Variable Classification Code

Device Variable Family

Device Variable Acquisition Period

Device Variable Properties

Device Variable Value

Device Variable Status

16



Device Variables should be declared and defined in module target\sys\src\config_comp.c.

If additional Device Variables are defined, the command 9 handler functionfdu_process_read_device_variables() in module base\appl\src\fd_universal.c needs to beupdated to consider those additional Device Variables.

For detailed information, refer to “Command Summary Specification” (HCF_SPEC-099,Rev 9.0), “Common Practice Command Specification” (HCF_SPEC-151, Rev 10.0) and“Common Tables Specification” (HCF_SPEC-183, Rev 23.0).

8.5 Mapping of device variables to dynamic variables

Four of the Device Variables can be mapped to Dynamic Variables PV, SV, TV and QV(see also Define dynamic variables ). With the current HART Device Stack, thismapping is fixed and cannot be changed during runtime.

The command 3 handler function in module base\appl\src\fd_universal.c and thecommand 50 handler function in module base\appl\src\fd_common.c needs to be updatedaccordingly.

For detailed information, refer to “Command Summary Specification” (HCF_SPEC-099,Rev 9.0), “Universal Command Specification” (HCF_SPEC-127, Rev 7.1), “CommonPractice Command Specification” (HCF_SPEC-151, Rev 10.0) and “Common TablesSpecification” (HCF_SPEC-183, Rev 23.0).

8.6 Device specific status

The current HART Device Stack supports 6 Device Specific Status Bytes.

The device specific status bytes have to be updated in command 48 function handlerfdu_process_read_additional_status() in module base\appl\src\fd_universal.c.

If more device specific status bytes are required, the command 48 function handler mustbe modified in accordance with “Universal Command Specification” (Rev 7.1).

For detailed information, refer to “Command Summary Specification” (HCF_SPEC-099,Rev 9.0) and “Universal Command Specification” (HCF_SPEC-127, Rev 7.1).

8.7 HART command implementation

To implement HART commands, the following three modules are available:

base\appl\src\fd_universal.c

base\appl\src\fd_common.c

target\appl\src\fd_devspecific.c

The module fd_universal.c contains the command handler for all universal commandsspecified in “Universal Command Specification” (Rev 7.1). Here, the Field Devicedeveloper only needs to assemble and disassemble the command requests andresponses properly.

The module fd_common.c contains the command handler for a subset of the commonpractice commands specified in “Common Practice Command Specification” (Rev 10.0).If additional common practice commands are required, this module is intended toimplement them.

17



With the current HART Device Stack the following common practice commands areimplemented:

41 – Perform Self Test

42 – Perform Device Reset

50 – Read Dynamic Variable Assignment

54 – Read Device Variable Information

59 – Write Number Preambles

Like for universal commands, the Field Device developer needs to assemble anddisassemble the command requests and responses properly.

The command 41 is implemented to respond SUCCESS on request. For a real Device,this needs to be filled with functionality or maybe skipped.

The module fd_devspecific.c contains the command handler for device specificcommands. Here, the Field Device developer should implement the command handler ofhis device specific commands.

Currently some device specific commands are implemented as example (refer to Sampledevice-specific commands ). These examples have to be removed from a real device.

Finally, for any new implemented command, the command number together with thecommand handler function must be entered in the command handler table commandInfo[]contained in module base\core\src\command_handler_comp.c.

For detailed information, refer to “Universal Command Specification” (HCF_SPEC-127,Rev 7.1) and “Common Practice Command Specification” (HCF_SPEC-151, Rev 10.0).

8.8 User Application

The User application is contained in module target\sys\src\sensor_usrappl_comp.c.Within this component a local variable sensUsrData of data typeT_SENSOR_USERAPPL_DATA is defined to handle the process values from thesensor(s).

That structure T_SENSOR_USERAPPL_DATA, contains a section “/*--- sensor values ---*/” where the value and status component of the process related Device Variables aredeclared. Currently this section contains the value and status components for the SampleRAMP sensor. This sample must be removed and replaced with the accordingcomponents from the real sensor application.

The User Application is realized as a Task that is periodically resumed to update thevalues from the sensor application, needed to update the according Device Variable/Dynamic Variable values in the commands #1, #3 and #9.

8.9 Sensor Application

From HART Stack size the Sensor Implementation requires three interface functions thatare called from the User Application Task:

Init() initialize all Sensor related variables, CPU peripherals and so on if needed

Start() start the Sensor if possible

22



Execute() update the Sensor’s process value

The intention is to use the Sample Sensor implementation target\appl\src\sens_sample.cas reference/example for real Sensor implementation.

8.10 Sensor API Modes: Push and Pull

Push Mode: The Sensor Application forces the update of the Process Values

Pull Mode: The HART stack need to request the update of the Process Values

In either way, it must be ensured that the process-related values are updated.

8.11 Sample Application

The Sample Application is implementing a RAMP Sensor that simulates a ramp value thatcounts up from a minimum value to a maximum value with a defined increment step.

The minimum, maximum, increment and update period values can be configured overdevice specific HART commands. The command 150 can be issued to read the currentconfiguration and the command 151 can be issued to write/change the currentconfiguration.

The RAMP Sensor implementation is located in module target\appl\src\sens_sample.c.

8.11.1 Command 150 – Read RAMP Sensor configuration

Request Data Bytes

Byte Data Type Description

None

Response Data Bytes


0 – 3 Float RAMP Minimum value

4 – 7 Float RAMP Maximum value

8 – 11 Float RAMP Increment value

12 – 13 Unsigned-16 RAMP Update Period (units of ms).Defines in what time periods the actualRAMP value is incremented by the RAMPIncrement value.



8.11.2 Command 151 – Write RAMP Sensor configuration

Request Data Bytes





12 – 13 Unsigned-16 RAMP Update Period (units of ms). Defines in whattime periods the actual RAMP value is incremented bythe RAMP Increment value.

Response Data Bytes





12 – 13 Unsigned-16 RAMP Update Period (units of ms). Defines in whattime periods the actual RAMP value is incremented bythe RAMP Increment value.

8.12 Sample device-specific commands

Besides the Sample Sensor Application related device specific commands 150 and 151(see also Command 150 – Read RAMP Sensor configuration and Command 151 –Write RAMP Sensor configuration ) the following device specific commands areimplemented in current HART Device Stack as example.

128 – Set Device ID

129 – Set Expanded Device Type

131 – Set Additional Configuration Parameters

132 – Set Sensor Polling Timeout

133 – Get Sensor Polling Timeout

136 – Read Firmware Version String

139 – Set MSA Bit and Extended Device Status

140 – Reset Extended Device Status

141 – Modify Extended Status

143 – Reset to Factory Defaults

These commands are intended for testing purposes and need to be removed from a realdevice.

21

22



8.12.1 Command 128 – Set Device ID

Change the Device ID.

Request Data Bytes


0 – 2 Unsigned-24 Device ID

3 – 9 Unsigned-8 Security

Fixed: 0x53, 0x4F, 0x46, 0x54, 0x49, 0x4E, 0x47

Response Data Bytes


0 – 2 Unsigned-24 Device ID

8.12.2 Command 129 – Set Expanded Device Type

Change Expanded Device Type.

Request Data Bytes


0 – 1 Unsigned-16 Expanded Device Type


Fixed: 0x53, 0x4F, 0x46, 0x54, 0x49, 0x4E,0x47

Response Data Bytes


0 – 1 Unsigned-16 Expanded Device Type



8.12.3 Command 131 – Set Additional Configuration Parameters

Change additional configuration parameters.

Request Data Bytes


0 Unsigned-8 Minimum number of Preambles requiredfor the request messages from Master toSlave

1 Unsigned-8 Device Revision Level

2 Unsigned-8 Software Revision Level

3 Unsigned-8 Hardware Revision Level

4 Unsigned-8 Physical Signaling Level

5 Bits Flags

6 Unsigned-8 Minimum number of Preambles to be sentwith the response message from Slave toMaster

7 Unsigned-8 Max Device Variables

8 – 9 Unsigned-16 Manufacturer Identification Code

10 – 11 Unsigned-16 Private Label Distributor Code

12 Unsigned-8 Device Profile


Fixed: 0x53, 0x4F, 0x46, 0x54, 0x49, 0x4E,0x47

Response Data Bytes


0 Unsigned-8 Minimum number of Preambles requiredfor the request messages from Master toSlave

1 Unsigned-8 Device Revision Level

2 Unsigned-8 Software Revision Level

3 Unsigned-8 Hardware Revision Level

4 Unsigned-8 Physical Signaling Level

5 Bits Flags

6 Unsigned-8 Minimum number of Preambles to be sentwith the response message from Slave toMaster

7 Unsigned-8 Max Device Variables

8 – 9 Unsigned-16 Manufacturer Identification Code

10 – 11 Unsigned-16 Private Label Distributor Code

12 Unsigned-8 Device Profile



8.12.4 Command 132 – Set Sensor Polling Timeout

Set the Sensor Polling Timeout.

Request Data Bytes


0 – 3 Unsigned-32 Sensor Polling Timeout (units of ms)


Fixed: 0x53, 0x4F, 0x46, 0x54, 0x49, 0x4E, 0x47

Response Data Bytes


0 – 3 Unsigned-32 Sensor Polling Timeout (units of ms)

8.12.5 Command 133 – Get Sensor Polling Timeout

Get the Sensor Polling Timeout.

Request Data Bytes


None

Response Data Bytes


0 - 3 Unsigned-32 Sensor Polling Timeout (units of ms)

8.12.6 Command 136 – Read Firmware Version String

Read the Firmware Version string.

Request Data Bytes


None

Response Data Bytes


0 - 8 Unsigned-8 FW Version



8.12.7 Command 139 – Set MSA Bit and Extended Device Status

Set Extended Device Status to force setting of “More Status Available” bit.

Request Data Bytes


0 Bits Extended Field Device Status

1 - 7 Unsigned-8 Security

Fixed: 0x53, 0x4F, 0x46, 0x54, 0x49, 0x4E,0x47

Response Data Bytes



8.12.8 Command 140 – Reset Extended Device Status

Reset the Extended Device Status.

Request Data Bytes



Fixed: 0x53, 0x4F, 0x46, 0x54, 0x49, 0x4E,0x47

Response Data Bytes


None

8.12.9 Command 141 – Modify Extended Status

Modify Extended Device Status.

Request Data Bytes




Fixed: 0x53, 0x4F, 0x46, 0x54, 0x49, 0x4E,0x47

Response Data Bytes


None



8.12.10 Command 143 – Reset to Factory Defaults

Reset Field Device to Factory Default Settings.

Request Data Bytes



Fixed: 0x53, 0x4F, 0x46, 0x54, 0x49, 0x4E,0x47

Response Data Bytes


None

Chapter 9 - Software component interfaces


9 Software component interfaces

The following chapters contain descriptions of several modules used by the HART Stack.

9.1 Configuration module

T_OS_STATUS

Enum

typedef enum {

CFG_HARTDLL_POLLING_ADDRESS,

CFG_HARTDLL_LOOP_CURRENT_MODE,

CFG_DEVCONFIG_DEVICEID,

CFG_DEVCONFIG_EXPDEVICETYPE,

CFG_DEVCONFIG_PREAMBLE_NUMBERS,

CFG_DEVCONFIG_PREAMBLE_NUMBERS_MS,

CFG_DEVCONFIG_TAG,

CFG_DEVCONFIG_LONGTAG,

CFG_DEVCONFIG_MESSAGE,

CFG_DEVCONFIG_DESCRIPTOR,

CFG_DEVCONFIG_DATE,

CFG_DEVCONFIG_ASSEMBLYNO,

CFG_DEVCONFIG_DEVREVISION,

CFG_DEVCONFIG_SWREVISION,

CFG_DEVCONFIG_HWREVISION,

CFG_DEVCONFIG_PHYSICALSIGNALING,

CFG_DEVCONFIG_FLAGS,

CFG_DEVCONFIG_MAXNODEVVARS,

CFG_DEVCONFIG_MANUFID,

CFG_DEVCONFIG_PRIVLABELDISTRIB,

CFG_DEVCONFIG_DEVPROFILE,

CFG_DEVCONFIG_SENSOR_POLLTIME,

CFG_DEVPVCONFIG_UNIT,

CFG_DEVPVCONFIG_CLASS,

CFG_DEVPVCONFIG_SERIAL,

CFG_DEVPVCONFIG_TRANSDLIMLOW,

CFG_DEVPVCONFIG_TRANSDLIMHIGH,

CFG_DEVPVCONFIG_TRANSDMINSPAN,

CFG_DEVPVCONFIG_UPDATETIME,

CFG_DEVPVCONFIG_ALARMCODE,

CFG_DEVPVCONFIG_TRANSFERFCTCODE,

CFG_DEVPVCONFIG_LIMUNITSCODE,



CFG_DEVPVCONFIG_UPPERRANGE,

CFG_DEVPVCONFIG_LOWERRANGE,

CFG_DEVPVCONFIG_DAMPINGVALUE,

CFG_DEVPVCONFIG_ANALOGCHNLFLAGS,

CFG_DEVPVCONFIG_PROPERTYCODE,

CFG_DEVSVCONFIG_UNIT,

CFG_DEVSVCONFIG_CLASS,

CFG_DEVSVCONFIG_SERIAL,

CFG_DEVSVCONFIG_TRANSDLIMLOW,

CFG_DEVSVCONFIG_TRANSDLIMHIGH,

CFG_DEVSVCONFIG_UPDATETIME,

CFG_DEVSVCONFIG_TRANSDMINSPAN,

CFG_DEVSVCONFIG_DAMPINGVALUE,

CFG_DEVSVCONFIG_PROPERTYCODE,

CFG_DEVTVCONFIG_UNIT,

CFG_DEVTVCONFIG_CLASS,

CFG_DEVTVCONFIG_SERIAL,

CFG_DEVTVCONFIG_TRANSDLIMLOW,

CFG_DEVTVCONFIG_TRANSDLIMHIGH,

CFG_DEVTVCONFIG_UPDATETIME,

CFG_DEVTVCONFIG_TRANSDMINSPAN,

CFG_DEVTVCONFIG_DAMPINGVALUE,

CFG_DEVTVCONFIG_PROPERTYCODE,

CFG_DEVQVCONFIG_UNIT,

CFG_DEVQVCONFIG_CLASS,

CFG_DEVQVCONFIG_SERIAL,

CFG_DEVQVCONFIG_TRANSDLIMLOW,

CFG_DEVQVCONFIG_TRANSDLIMHIGH,

CFG_DEVQVCONFIG_UPDATETIME,

CFG_DEVQVCONFIG_TRANSDMINSPAN,

CFG_DEVQVCONFIG_DAMPINGVALUE,

CFG_DEVQVCONFIG_PROPERTYCODE,

CFG_MNGMT_ID_NO

}T_CONFIG_MNGMT_ID

Description

Various management selection to configure the HART stack



Bool config_set( uint8_t mngmtId, unit8_t *data)

Parameter

mngmtId

*data

(input) Number of management to be controlled

(input) a pointer to the data to be used for configuration

Return value

True for successful execution of the management command

False an error occurred

Description

This function can be called to change a configuration parameter of the HART stack likethe long tag of the device

Bool config_get( uint8_t mngmtId, unit8_t *data)

Parameter

mngmtId

*data

(input) Number of management to be controlled

(output) a pointer to the location where the function will write thevalue

Return value

True for successful execution of the management command

False an error occurred

Description

This function can be called to read a configuration parameter of the HART stack like thelong tag of the device



9.2 Sensor application

Void sensor_API_update(uint8_T deviceVariable,float *value)

Parameter

deviceVariable

*value

The selection of the process value to be updated (one of..)

SENSOR_VARIABLE_PRIMARY_VALUE,SENSOR_VARIABLE_SECOND_VALUE,SENSOR_VARIABLE_THIRD_VALUE,SENSOR_VARIABLE_BATTERYLIFE,

A pointer to the float value

Return value

-

Description

Called to update a sensor reading to the HART stack. The HART stack will use thesevalues to answer commands 1,3,9 etc. The values will be mirrored in the HART and willstay readable any time until a new update changes the value.

9.3 Operating system interface

The operating system abstraction is mainly used to provide portability of the HART stackon different operating systems. Several OS features are required that are used by theHART stack.

multiple tasks with priorities


event handling

binary semaphores

priority inversion to resolve resource conflict

For efficiency and portability, dynamic memory handling is not part of the operating systemabstraction.

The operating system is implemented in a component with two interfaces:

1. the Component Interface to init ,start and stop the OS and

2. the OS Interface to be used by other components to use the RTOS functionality oftasks, mailboxes, events etc.



T_OS_STATUS

Enum

typedef enum T_OS_STATUS

{ OS_STATUS_OK,

OS_STATUS_ERROR,

OS_STATUS_BUSY,

OS_INVALID_TASK_HANDLE,

OS_INVALID_MBOX_HANDLE,

OS_TOO_MANY_MAILBOXES,

OS_MBOX_INFO_MISSING,

OS_MBOX_MEMORY_MISSING,

OS_MBOX_INVALID_MSG_SIZE,

OS_MBOX_INVALID_SIZE,

OS_MBOX_HANDLE_MISSING,

OS_EMPTY_MBOX,

OS_FULL_MBOX,

OS_INVALID_SEMA_HANDLE,

OS_TOO_MANY_SEMAPHORES,

OS_SEMA_NOT_REQUESTED,

OS_SEMA_HANDLE_MISSING,

OS_TOO_MANY_TASKS,

OS_INVALID_TASK_DATA

} T_OS_STATUS;

Description

Various return codes for the os-interface functions

T_OS_STATUS terminate( (void) *pFunc(void))

Parameter

pFunc The clean-up function to call before termination

Return value

This function will not return

Description

Called to terminate the RTOS and halt the system. Before halting, the pFunc is called forclean-up



void enter_critical_region(void)

Parameter

None

Return value

void

Description

Called to disable the scheduler of the RTOS. There will be no task switches anymore

void leave_critical_region(void)

Parameter

None

Return value

void

Description

Called to re-enable the scheduler of the RTOS after calling enter_critical_region. Makesure that after calling enter_critical_region() the RTOS will always be re-enabled bycalling the enter_critical_region().



T_OS_STATUS task_create

(T_OS_TASK_INFO* pTaskInfo, T_OS_TASK* pTaskHandle)

Parameter

pTaskInfo

pTaskHandle

(input) Pointer to a struct holding all relevant information for the task:

typedef struct {

void (*p_task_main)(void);

void (*p_task_init)(void);

char* taskName;

uint8_t* taskStack;

uint16_t taskStacksize;

uint8_ttaskPriority; priority

} T_OS_TASK_INFO;

(output) handle to the task created

Return value

OS_STATUS_OK when successfully completed, error code if error during execution

Description

Called by a software component to install a task in the RTOS. The task is only createdand task- init and task-main functions are registered.

T_OS_TASK task_get_current (void)

Parameter

None

Return value

Returns the task currently executed

Description

This function returns the handle of the currently running task to the caller



T_OS_STATUSmailbox_create(T_OS_MBOX_INFO*pMboxInfo,

T_OS_MBOX*pMboxHandle,

T_OS_TASKtaskHandle,T_OS_EVENTtaskEvent);

Parameter

pMboxInfo

pMboxHandle

taskHandle

taskEvent

(input) Pointer to a struct of Information about the mailbox to becreated

(output) a pointer where the mailbox handle of the created mailbox isstored

(input) taskHandle - if this is a valid task handle the mailbox is setupto signal events to this task everytime a message is received. Set thetask handle to OS_TASK_NULL if you don't want to assign events.

(input) event - The events (mask) to set automatically

Return value

OS_STATUS_OK when successfully completed, error code if error during execution

Description

This function creates a new mailbox with the provided mailbox information within thegiven memory space. Additionally task events of a specified task can be mapped toincoming messages (new messages will automatically raise the given event(s)).



T_OS_STATUS message_get ( T_OS_MBOX mbosHandle, void*pMsg)

Parameter

mboxHandle

pMsg

(input) the mailbox to receive from

(output) a pointer to the received message

Return value

OS_STATUS_OK when successfully completed, error code if error during execution(e.g. no message there)

Description

Try to get incoming messages of the given mailbox represented by the mailbox handle.When no messages are available at call time, this function does not block the callingtask.

T_OS_STATUS message_send ( T_OS_MBOX mbosHandle, void*pMsg)

Parameter

mboxHandle

pMsg

(input) the mailbox to receive from

(output) a pointer to the received message

Return value

OS_STATUS_OK when successfully completed, error code if error during execution(e.g. no space availble)

Description

The given message pointer location is copied from the source to the mailbox internalmessage memory.



T_OS_STATUS event_signal (T_OS_TASK taskHandle, T_OS_EVENTtaskEvent)

Parameter

taskHandle

taskEvent

(input) the receiving task

(input) events to be set (bitmask)

Return value

OS_STATUS_OK always

Description

Set the given event (mask) to the specified task

T_OS_EVENT event_wait (T_OS_EVENT event)

Parameter

event (input) events to be set (bitmask)

Return value

the events signaled since the function was called

Description

All events given in the event parameter will be cleared after return! Other pending eventswill not be touched.

T_OS_EVENT event_clear (T_OS_EVENT event)

Parameter

event (input) event flags which should be cleared

Return value

cleared events which were actually pending

Description

Clear pending events of a given task



T_MEM_STATUSmem_poo l _c r ea te (

T_MEM_POOL_ I NFO*pBl oc k I n f o , T_MEM_POOL*pPoo l Hand l e

Parameter

pBlockInfo

pPoolHandle

(input) info about the memory pool:

typedef struct T_MEM_POOL_INFO {

char* pPool;

uint16_t blockSize;

uint16_t numberOfBlocks;

} T_MEM_POOL_INFO;

(output) handle to the pool created

Return value

MEM_STATUS_OK when successfully completed, error code if error during execution

Description

This function creates and sets up a new memory pool. All necessary information beprovided by the pBlockInfo parameter. The operating system only cares about thememory pool management not about the actual memory space. The user of this functionmust allocate enough space for the memory pool.



T_MEM_STATUS mem_get (T_MEM_POOL poolHandle, void** ppBlock)

Parameter

poolHandle

ppBlock

(input) select the memory pool via a handle

(output) pointer to the memory block returned

Return value

MEM_STATUS_OK if a memory block was available, error code if e.g. no memoryavailable

Description

Get a block of memory from the given memory pool.

T_MEM_STATUS mem_release (T_MEM_POOL poolHandle, void** ppBlock)

Parameter

poolHandle

pBlock

(input) select the memory pool via a handle

(output) pointer to the memory block returned

Return value

MEM_STATUS_OK if a memory block was available, error code if e.g. pool andmemoryblock pointer do not match.

Description

Return a block of memory from the given memory pool to free it up for the next usage.

uint8_t mem_get_num_free_blocks( T_MEM_POOL poolHandle)

Parameter

poolHandle (input) select the memory pool via a handle

Return value

Number of free blocks in a memory pool.

Description

Get number of available blocks of the given memory pool.



T_OS_STATUSsemaphore_create(T_OS_SEMAPHORE* pSemaHandle)

Parameter

pSemaHandle (output) the semaphore created

Return value

OS_STATUS_OK when successfully completed, error code if error during execution(max number of semaphores reached).

Description

Create new binary semaphore (mutex).

T_OS_STATUS semaphore_check(T_OS_SEMAPHORE semaHandle)

Parameter

semaHandle (input) select the semaphore to be taken (checked)

Return value

OS_STATUS_OK if the semaphore with the given handle exists and is either owned ornow taken by the requesting module. OS_STATUS_ERROR otherwise.

Description

Check if given semaphore is available (non-blocking) and get it.

T_OS_STATUS semaphore_wait(T_OS_SEMAPHORE semaHandle)

Parameter

semaHandle (input) select the semaphore to wait for

Return value

OS_STATUS_OK if the semaphore with the given handle exists and was takenOS_STATUS_ERROR otherwise

Description

Request given semaphore regardless of availability (blocking). If the semaphore is notavailable, this function will block until the semaphore can be acquired.



T_OS_STATUS semaphore_post(T_OS_SEMAPHORE semaHandle)

Parameter

semaHandle (input) select the semaphore to release

Return value

OS_STATUS_OK if the semaphore with the given handle exists and is owned by thetask OS_STATUS_ERRORotherwise

Description

Release a previously requested semaphore.

Void disable_interrupts(void)

Parameter

None

Return value

void

Description

Disable interrupts globally, make sure to call the corresponding disable interruptsfunction as many times as this function was called to actually enable interrupts again.Disabling and enabling can be nested and are counted.

Void enable_interrupts(void)

Parameter

None

Return value

void

Description

enable interrupts globally



T_OS_STATUS set_idle_function( void (*pIdleFunction)(void))

Parameter

pIdleFunction The pointer to the idle function

Return value

OS_STATUS_OK when successful, OS_STATUS_ERROR if idle function was alreadyset (the idle function can only be set once).

Description

Hook a function into the idle task. This function will run as lowest priority in the systemwhen all other tasks have completed.

9.4 Low power interface

Sleep operation - setup sleep and wakeup clocks.

How to:

Use hal_init_sleep() function to setup sleep mechanism

Then simply call sleep() with sleep duration in RTC ticks as argument (the functionwill go to sleep for the given time plus additional overhead of about 1.36 ms which areabout 45 RTC ticks (32768Hz))

Additional Information:

We use hibernate mode (modes: hibernate|doze) with RTC clock as time source

We use the "wake-up timer" with relative sleep times (not RTC wake-up counter)

Needful steps:

Define following preprocessor macro: #define SLEEP

Implement the wakeup isr function (hw_sleep.c): void ISR_WAKEUP(void){}

This handler is used to get out of the sleep again. The irq event flag is cleared atplatform irq handling level.

Implement the main sleep function (hw_sleep.c): void sleep(uint32_t time){}

This is the main sleep function.- max sleep time is: 32768s (means 2 3̂0 ticks)- uses hibernation

Make sure the RTC is running.param[in] time - if 0, return immediately, if time > MAX_SLEEP_TICKS, set time to MAX_SLEEP_TICKS

Implement the sleep initialization function (hw_sleep.c): void hal_init_sleep(void){}



Set pins and retention states etc.

Set the appropriate values for following macros (timer_comp.c):

#define MIN_SLEEP_TIME534 // Min sleep time in RTC ticks

#define SLEEP_SAFETY_TIME 380 // Sleep preparation and wake-up time delay correction

#define SLEEP_STANDARD_TIME 65536 // If there is no active timer, fixed sleeptime (for now: 262ms)

Richard-Reitzner-Allee 685540 Haar / GermanyTel: + 49 89 4 56 56-0Fax: + 49 89 4 56 56-488Internet: http://industrial.softing.comEmail: [email protected]: [email protected]

Softing Industrial Automation GmbH

Documents

HART Device Stack - Softing · Chapter 1 - Introduction HART Device Stack - User Manual 5 1 Introduction 1.1 About product The Softing HART Device Stack is an easy portable protocol