Professional Documents
Culture Documents
Version: 062015-EN-1.10
The information contained in these instructions corresponds to the technical status at the time of printing of it and is
passed on with the best of our knowledge. The information in these instructions is in no event a basis for warranty
claims or contractual agreements concerning the described products, and may especially not be deemed as warranty
concerning the quality and durability pursuant to Sec. 443 German Civil Code. We reserve the right to make any
alterations or improvements to these instructions without prior notice. The actual design of products may deviate from
the 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.
The latest version of this manual is available in the Softing download area at: http://industrial.softing.com.
Table of Contents
Table of Contents
Chapter 1 Introduction
..................................................................................5
1.1 About product ................................................................................................ 5
1.2 About this document
................................................................................................ 5
1.2.1 Document ......................................................................................................
history 5
1.2.2 Target group
...................................................................................................... 5
1.2.3 Conventions used
...................................................................................................... 6
Chapter 2 System requirements
..................................................................................7
2.1 General requirements
................................................................................................ 7
2.2 Renesas M16C ................................................................................................
specific requirements: 8
2.3 Supported platforms
................................................................................................ 8
Chapter 3 Key features
..................................................................................9
Chapter 4 Software architecture
..................................................................................10
4.1 Software Components
................................................................................................ 10
4.2 HART Stack API
................................................................................................
for a HART device 11
Chapter 5 Short instructions
..................................................................................12
Chapter 6 List of supported HART commands
..................................................................................13
Chapter 7 HART stack porting guideline
..................................................................................14
7.1 Overview ................................................................................................ 14
7.2 Procedure ................................................................................................ 14
Chapter 8 Build your own device
..................................................................................16
8.1 Device identification
................................................................................................
and configuration 16
8.2 Device data base
................................................................................................ 17
8.3 Define dynamic
................................................................................................
variables 17
8.4 Define device................................................................................................
variables 18
8.5 Mapping of device
................................................................................................
variables to dynamic variables 19
8.6 Device specific
................................................................................................
status 19
8.7 HART command ................................................................................................
implementation 19
8.8 User Application
................................................................................................ 20
8.9 Sensor Application
................................................................................................ 20
8.10 Sensor API Modes:
................................................................................................
Push and Pull 21
8.11 Sample Application
................................................................................................ 21
1 Introduction
This document refers to the HART protocol release by the HART Communication
Foundation (www.hartcomm.org). The protocol stack covers all relevant parts of the
protocol layers from Hardware Abstraction up to the Application level. Two main scenarios
are covered by the HART stack protocol implementation: first, to provision a stand-alone
wired HART field device with a stack and second, to enable a wireless field device for
compliant HART communication with low power consumption and interoperability via
maintenance port.
Keys, buttons, menu items, commands and Open Start Control Panel
other elements involving user interaction are Programs
set in bold font and menu sequences are
separated by an arrow
Buttons from the user interface are enclosed Press [Start] to start the application
in brackets and set to bold typeface
Coding samples, file extracts and screen MaxDlsapAddressSupported=23
output is set in Courier font type
Filenames and directories are written in italic Device description files are located in C:
\StarterKit\delivery\software\Device
Description files
CAUTION
CAUTION indicates a potentially hazardous situation which, if not avoided, may
result in minor or moderate injury.
Note
This symbol is used to call attention to notable information that should be
followed during installation, use, or servicing of this device.
Hint
This symbol is used when providing you with helpful user hints.
2 System requirements
The HART Device Stack protocol implementation is highly portable., under the following
general 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
For controller-specific requirements see following sections. Porting the source code to
another platform may result in different memory and performance 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
Requirement Details
Low frequency oscillator Typically 32768 Hz Oscillator
For controller specific requirements see following sections. Porting the source code to
another platform may result in different memory and performance requirements.
3 Key features
Feature Explanation
Compliant HART 7.5 protocol Tested against HCF Compliance Kit 192 V3.0
Burst The HART stack implements a compliant
burst module
Low power operation The HART stack provides interfaces for low
power operation e.g. it can be applied to
battery-operated devices
Software framework The HART stack is embedded in a powerful
and flexible software framework providing a
programming structure and abstraction
methodology
Example code The code is ready to run and prepared with
a user component
HART Command abstraction and user The HART stack has an abstraction to
interface separate the user application and the HART
stack completely. The user does not have to
care about timing, framing and packet
generation.
Push and pull Sensor interface Comfortable interface to update local sensor
values based on automatic periodic requests
from the HART stack (pull) or active user
updates (push)
4 Software architecture
Module list
Operating System Interface to the underlying operating system. The HART Device
Stack requires an OS.
User Application The implementation of the field device logic, mainly the control of
sensors and the device hardware. This component has an
interface to the sensor application to update the sensor values
used by the HART stack
5 Short instructions
When using the HART stack for a stand-alone HART device, the following steps have to
be 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. issuing
command 1 or install a burst to periodically get the sensor value.
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 from
your 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 think
about where to place a newly created file within this structure. Only platform independent
files should make it in the base folder.
The target folder comprised all files that are dependent on the target hardware or target
application, 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 suitable
build process which is aware of compiling and linking files from different sources into one
binary 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 hardware
components and make the code compile again. After that hardware modules can be
implemented one after another.
This basically includes:
platform-specific setups/settings (e.g. setup processor modes, interrupt sources, pin
setup, 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 it
enables developers to test the code after each step.
In this order, as a first step, the underlying platform should be correctly initialized and
working. 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 first
pick the basic ones like OS abstraction layer and timer, since both components are
almost used by any other component.
After that we recommend implementing the hardware HART interface and then all other
modules which are left over.
If everything is implemented according to hardware interface and underlying functions, the
HART stack should work as expected.
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
With the current HART Device Stack the following common practice commands are
implemented:
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 and
disassemble 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 specific
commands. Here, the Field Device developer should implement the command handler of
his device specific commands.
Currently some device specific commands are implemented as example (refer to Sample
device-specific commands 22 ). These examples have to be removed from a real device.
Finally, for any new implemented command, the command number together with the
command 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.12.7 Command 139 – Set MSA Bit and Extended Device Status
Set Extended Device Status to force setting of “More Status Available” bit.
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
Parameter
* data (output) a pointer to the location where the function will write the
value
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 the
long tag of the device
Parameter
Description
Called to update a sensor reading to the HART stack. The HART stack will use these
values to answer commands 1,3,9 etc. The values will be mirrored in the HART and will
stay readable any time until a new update changes the value.
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
Parameter
Description
Called to terminate the RTOS and halt the system. Before halting, the pFunc is called for
clean-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. Make
sure that after calling enter_critical_region() the RTOS will always be re-enabled by
calling the enter_critical_region().
T_OS_STATUS task_create
(T_OS_TASK_INFO* pTaskInfo, T_OS_TASK* pTaskHandle)
Parameter
pTaskInfo (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;
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 created
and task- init and task-main functions are registered.
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_STATUS
mailbox_cr
eate
(T_OS_MBOX
_INFO*
pMboxInfo,
T_OS_MBOX*
pMboxHandle,
T_OS_TASK
taskHandle,
T_OS_EVENT
taskEvent);
Parameter
pMboxHandle
(output) a pointer where the mailbox handle of the created mailbox is
stored
taskHandle
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 the
given memory space. Additionally task events of a specified task can be mapped to
incoming messages (new messages will automatically raise the given event(s)).
Parameter
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 calling
task.
Parameter
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 internal
message memory.
Return value
OS_STATUS_OK always
Description
Set the given event (mask) to the specified task
Parameter
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 events
will not be touched.
Parameter
Return value
cleared events which were actually pending
Description
Clear pending events of a given task
T_ MEM_ STATUS
me m_ p o o l _ c r e a t
e (
T_ MEM_ POOL _ I NFO*
p Bl o c k I n f o , T_ MEM_ POOL *
p Po o l Ha n d l e
Parameter
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 be
provided by the pBlockInfo parameter. The operating system only cares about the
memory pool management not about the actual memory space. The user of this function
must allocate enough space for the memory pool.
Parameter
Return value
MEM_STATUS_OK if a memory block was available, error code if e.g. no memory
available
Description
Get a block of memory from the given memory pool.
Parameter
Return value
MEM_STATUS_OK if a memory block was available, error code if e.g. pool and
memoryblock pointer do not match.
Description
Return a block of memory from the given memory pool to free it up for the next usage.
Parameter
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
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).
Parameter
Return value
OS_STATUS_OK if the semaphore with the given handle exists and is either owned or
now taken by the requesting module. OS_STATUS_ERROR otherwise.
Description
Check if given semaphore is available (non-blocking) and get it.
Parameter
Return value
OS_STATUS_OK if the semaphore with the given handle exists and was taken
OS_STATUS_ERROR otherwise
Description
Request given semaphore regardless of availability (blocking). If the semaphore is not
available, this function will block until the semaphore can be acquired.
Parameter
Return value
OS_STATUS_OK if the semaphore with the given handle exists and is owned by the
task 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 interrupts
function 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
Parameter
Return value
OS_STATUS_OK when successful, OS_STATUS_ERROR if idle function was already
set (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 system
when all other tasks have completed.
How to:
Use hal_init_sleep() function to setup sleep mechanism
Then simply call sleep() with sleep duration in RTC ticks as argument (the function
will go to sleep for the given time plus additional overhead of about 1.36 ms which are
about 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 at
platform 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^30 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){}
Richard-Reitzner-Allee 6
85540 Haar / Germany
Tel: + 49 89 4 56 56-0
Fax: + 49 89 4 56 56-488
Internet: http://industrial.softing.com
Email: info.automation@softing.com
Support: support.automation@softing.com