Know Your Device 


A HART Device Description (DD) is fundamentally a model of a HART-compliant field device. To develop a DD you must:

  • Be an expert in the operation, behavior and capabilities of the field device for which you are writing the DD. 
  • Model, using DDL, all the capabilities of the field device including the commands it supports, the data items it contains and the Standard Operating Procedures (SOPs) for configuring and maintaining the field device. 
  • Describe the User Interface to be used by instrument management systems interacting with your field device. End Users will demand that your User Interface provides access to all of the capabilities in your field device. 
  • Test your DD to confirm it correctly models your field device and the User Interface meets your expectations. 


Since the DD is a model of the field device, the DD is as simple or as complex as the field device for which it is written. If the field device is simple, developing the DD will be simple, straightforward and can be completed quickly. If the device is HART-compliant and consistent with HART concepts, the DD will be simpler still. On the other hand, complex devices can take a long time to model and may require many "tricks" (e.g., validity, conditionals, or methods) to be employed in the DD.

While it is important to know or learn DDL, it is much more important to know your field device. In most cases, the best person to write the DD is the person who developed the device. The cost for a device developer to learn DDL is normally far less than the cost to document a device and then teach the device to a DDL expert.


Get the Right Tools


To productively develop your DD you need the DD-IDE. This tool was designed using the accumulated DD Development knowledge of experienced FieldComm Group engineers. This know-how was learned through years of writing DDs, teaching DD Developers and providing technical support to DD Developers worldwide. The DD-IDE tools are designed to allow you to develop a powerful, yet portable, host-independent DD.


The DD-IDE provides all the tools required to develop and test a DD for your field device. The DD-IDE tools:

  • are integrated in a single environment to automate repetitive tasks; 
  • provide wizards to simplify generation of standard constructs; 
  • support testing and debugging of the DD; and 
  • allow for regression testing and validation of the DD. 


A DD is best developed incrementally. This allows the device capabilities to be modeled and confirmed in small manageable chunks. For example, most DD developers incorporate support for the Universal Commands and a simple set of menus first. Then, Common Practice Commands are added and tested one at a time followed by Device Specific Commands.

 

This results in an Edit-Build-Test-Validate cycle that is repeated many times. The DD-IDE provides tools for each step in this cycle including:

  • Edit - Central to the DD-IDE is a powerful DDL knowledgeable editor with wizards and project management capabilities. 
  • Build - Tokenizer and DD Management tools are provided. 
  • Test - The SDC-625 Reference DD Host is provided to facilitate testing of the DD.   
  • Validate - Tools are provided to facilitate validation of the DD. This includes Xmtr-DD that allows you to simulate your device and produce abnormal behavior for testing your DD. 

 

Know the HART Protocol


Your device must be HART-compliant because not all host applications use DDs. DDL-enabled host applications are large, heavyweight applications. Control Systems and I/O Systems, for example, often have real-time requirements or limited capacity that precludes their utilization of DDs. These kinds of host applications use the HART Universal and Common Practice Commands and depend on devices to be fully compliant.


To simplify and expedite DD Development, libraries of Standard DDs that model the HART Protocol are supplied with the HART DD-IDE. Understanding the HART Application Layer is key to understanding these Standard DDs. The DD-IDE provides sample DDs to demonstrate the use of the Standard DDs.


Knowing HART simplifies development of a HART-compliant device. This is important because working around device compliance issues in a DD leads directly to a more complex DD and a longer DD development cycle—more cost to develop, more cost to maintain.


A solid understanding of the HART Protocol, a HART-compliant device, utilization of the Standard DDs and the HART DD-IDE maximizes your DD Development productivity.


FieldComm Group offers training workshops on the HART Protocol. HART Fundamentals is an intensive -day course covering all aspects of the HART Communication Protocol. Students attending this course will leave equipped with knowledge to develop new HART-compatible products, support existing products, and design systems that utilize HART. Students will also learn about the correct ways to test their device and register it with the FieldComm Group.


Learn EDDL & FDI


While knowing your device is the key to writing a good DD, knowledge of EDDL is also required. Device Description Language is a unique class of computer language. It is a text-based language for modeling the behavior of field devices. This uniqueness can make understanding EDDL difficult because it is foreign to the experience of most developers.


EDDL is the HART standard and the only technology endorsed by FieldComm Group for configuration of HART devices. A key element of the HART technology since 1990, EDDL has proven to be a reliable, robust and stable platform for suppliers to consistently define and document the capabilities of HART-enabled products. In March 2004, EDDL was approved as an international standard–IEC 61804-2.


The FieldComm Group provides  EDDL workshops to help developers learn EDDL. The EDDL Specifications are both very specific and easy to read at the same. The FDI Technical Specifications define additional attributes for EDDs and enhancements included in the FDI Package. The Device Integration - Writing EDD and FDI Package Workshop is the fastest way to learn EDDL and provides both classroom lecture and many hours of hands-on, instructor-assisted development time.



Develop Your EDD


1. Create uniquely named source files.


All DDL source files which are registered to the FieldComm Group are stored and tokenized in a single directory. This means that all source files are required to have unique filenames so that files from all Manufacturers and device types are not over-written when DDs are added to the library. In addition, all DD source files, including image files (*.jpg, *.gif, *.png), must reside in the same directory without the use of sub-directories.


There are 6 extension types which are accepted for FieldComm Group registration: *.ddl, *.dd, *.h,*.jpg, *.gif, and *.png


NOTE: OTHER FILE EXTENSIONS WILL NOT BE ACCEPTED FOR DD REGISTRATION


The best practice for file names is to use the Expanded Device Type concatenated with the Device Revision as a prefix to all source files in the submission package. For example, a device with Expanded Device Type 0x1111 and Device Revision 0x23 would have source files named 111123_main.ddl, 111123_icon.jpg, 111123_menus.dd. Using this file name convention allows for easy recognition of your files and ensures the file names are unique to your product.


2. Identify 


In the main source file, identify the manufacturer and device, as well as the EDD revision.


Main DDL File (*.ddl) – Every DD must have one DDL source file with its DDL objects defined in it.

  • The filename must use extension *.ddl and there must only be one *.ddl file for each DD registration. If more than one source file is desired, additional DDL Include Files (see below) may be added to the registration submission.
  • This *.ddl file must have the MANUFACTURER construct declared within it and it shall have string values for the manufacturer and device type (which are defined in devices.cfg). Do not specify actual numeric values in this declaration.

    Correct:
    MANUFACTURER FCG, DEVICE_TYPE _SAMPLE1, DEVICE_REVISION 1, DD_REVISION 1

    Incorrect:
    MANUFACTURER 249, DEVICE_TYPE 249, DEVICE_REVISION 1, DD_REVISION 1


DDL Include Files (*.dd) – Any additional files which contain DDL objects may be created (if desired). The filename must use the extension *.dd.

Definitions (*.h) – This file must only contain macros and/or #defines. There must not be any DDL objects defined in this file. Developers must include the Standard DD Library macros.h and methods.h files.

Images (*.jpg, *.gif, and *.png) – The PATH attribute for IMAGE must contain a unique filename without a specific path so that all image files reside in the same directory with the other source files.

Correct:

PATH “26ef01error.gif”


Incorrect:

PATH “pics\\ 26ef01error.gif”



Please do not submit the entire project working directory.

 3. Importing Standard HART DDs

All devices must adhere to a valid revision of the HART Communications Protocol Specification.  The HART Standard DDs are designed to completely model and represent these specifications:

  • HART 5 DD must IMPORT Universal Rev 5, DD Rev 2 (Univ5_2.ddl) and Common Practice Rev 7, DD Rev 4 (Cmn7_4.ddl)
  • HART 6 DD must IMPORT Universal Rev 6, DD Rev 2 (Univ6.ddl) and Common Practice Rev 8, DD Rev 2 (Common8.ddl)
  • HART 7 DD must IMPORT Universal Dev Rev 7, DD Rev 2 (Univ7.ddl), Common Practice Rev 9, DD Rev 2 (Common9.ddl)
  • All DDs must IMPORT the latest Common Tables Specification (HCF_SPEC-183) Standard
    • Currently - Dev Rev 20, DD Rev 4 
  • Generally:
4. HART Standard DD Commands

All HART commands and the data referenced in the Standard DDs must not be altered (i.e., REDEFINE) unless the HART protocol specification explicitly allows for the command to be modified within a  device. 

If the HART protocol allows truncation of a command in a device, then the command must be modified to match in the DD. The DD must use an exact subset of the Standard DD command without any user defined VARIABLEs added or additional modifications.
For example, typical modifications may include but not limited to:

  • Command 3 may be redefined (only if less than 4 dynamic variables are supported)
  • Command 8 may be redefined (only if less than 4 dynamic variables are supported)
  • Command 9 may be redefined to less than 8 slots of device variables only if the revision of the HART protocol allows for it.
  • Command 48 may be redefined only if all data bytes are not supported.
  • All process measurements (i.e., Device Variables) must be modeled using a COLLECTION and its name and device variable code added to the ARRAY OF COLLECTION “deviceVariables”
  • All non-truncatable (and non-modifiable) Commands as defined in the HART protocol must be used as specified in the Standard DDs and must not be redefined.

5. HART Standard DD Data (i.e., VARIABLEs including references via COLLECTIONs/ARRAYs)

  • The Enumerated value and description for VARIABLEs manufacturer_id, private_label_distributor, and device_type may be redefined if the Manufacturer/Expanded Device Type code is not listed in the Common Tables DD
  • HANDLING may be redefined to READ & WRITE only if there is a Write Command for a VARIABLE
  • DISPLAY_FORMAT & EDIT_FORMAT may be redefined
  • DEFAULT_VALUE may be redefined
  • REFRESH_ACTIONS may be redefined

  • All other attributes as specified in the Standard DDs must not be redefined.

6. HART Standard DD Labels/Descriptions

It is imperative that you use the labels and the help strings exactly as they are defined in the Standard DDs.  These strings have been chosen to appropriately reflect the HART Specifications and governed by the UTF-8 Standard DD which allow for multiple language translations. 


  • The following Command 48 data bytes may have its LABEL and descriptions redefined:

device_specific_status_0, device_specific_status_1, device_specific_status_2, device_specific_status_3, device_specific_status_4, device_specific_status_5, device_specific_status_14, device_specific_status_15, device_specific_status_16, device_specific_status_17, device_specific_status_18, device_specific_status_19, device_specific_status_20, device_specific_status_21, device_specific_status_22, device_specific_status_23, device_specific_status_24


  • All other HART Data Strings (labels/descriptions) as specified in the Standard DDs must not be redefined.

NOTE: If an incorrect, incomplete or missing label/description is found in the Standard DDs, please contact Technical Services in advance of DD Registration submission.


7. User Interface
  • The following mandatory root menus and must be defined in the DD: root_menu, device_root_menu, process_variables_root_menu, diagnostic_root_menu, offline_root_menu*, and maintenance_root_menu*
    • Note: The HART Working Group made an exception for requiring offline_root_menu and maintenance_root_menu in EDDs. The menus are required for FDI Device Packages only. Developers must include a reference in the submission "readme.txt" that states: "As per WG PD20013, request to be exempt from requiring offline_root_menu and maintenance_root_menu root menus."
  • The PATH attribute for IMAGE must contain a unique filename without a specific path so that all image files reside in the same directory with the other source files.   

8. Build and Test 

  • The submitted source shall not produce any errors when built by the Tokenizer, else this will cause the test campaign to fail, resulting in the invoicing of the testing services fee. 

    • If there are changes required to the Standard DDs, the manufacturer must document the changes and request approval in advance of the EDD submission.  An approved Change Request (CR#) is required and this shall be noted in the Readme file as part of the EDD submission package. (See: How to file Change Requests.)

    • All deviations from the current HART Protocol specifications must have a supportive document (CR#, AR# or PD#) which was approved prior to the submission date. This includes: 

      • REDEFINE of standard variables or commands

      • ADD enumerations or bit enumerations

      • REDEFINE of a data type of an existing item in the symbol table

      • Commands which are defined by HART Protocol Specifications but have not been released in the Standard DD library (i.e. Condensed Status Commands).


  • Errors produced by host simulator software must be resolved prior to submitting the EDD for testing at FieldComm Group, else this will cause the test campaign to fail, resulting in the invoicing of the testing services fee. Examples include, but not limited to:
    • Tlink errors, linkage errors
    • Member List failed to find member errors
    • Command Data Item failed to resolve errors

    • Index in Reply does not match Index in Request errors

    • Reference-Array deviceVariables's getByIndex() failed to getItemByIndex for index value errors
    • Command validity rule failure errors


  • The FDI Reference Runtime Environment (RRTE) should be used to explore the resulting FDI Device Package contents and EDD while connected to the live device.


EDD Do’s/Don’ts

  • A DD revision is used as a minor modification of the DD in which the HART application layer is not affected (example: text of the menu user interface is changed).

  • A Device revision is a change to the device where the HART application layer has been modified (i.e. data was added, new command added, etc.), see HCF_SPEC-99, section 6.

  • Do not use preprocessor directives (i.e., #if #ifdef and #ifndef, etc.) on HART Standard DD IMPORTs, COMMANDs and VARIABLEs without advanced written authorization.

  • Do not use preprocessor macro __TOKVER__ to remove COMMANDs and/or VARIABLEs from DD without advanced written authorization.  The HART database must be identical in all Tokenized versions of the DD (see sample DDs in HART DD-IDE for known exceptions).

  • Do not completely redefine a Standard DD VARIABLE without advanced written authorization.

  • Do not use DD Host Application specific DD Items/built-ins (in conjunction with preprocessor directives) in a DD which is not supported by the HART Tokenizers and all HART DD Hosts.

  • Do not use DD Host Application specific names for the naming of source filenames and/or DDL Items (i.e., symbol names – names of VARIABLEs, MENUs, etc.).  A Registered DD must be designed to work on all DD HART hosts so please use generic functional names such as STYLE or type of DD Host.  For example, for naming a MENU for a DD Host Window’s application (i.e., non-limited display hosts)  use a naming convention like Window_SetupSensor or LDH_SetupSensor.  Similarly, for Handhelds (i.e., limited display hosts)  use a naming convention like Table_SetupSensor or HH_detailed_setup

  • Do not use any special #defines or macros. The IMPORTs need to be standardized by the macros already defined in macros.h and to not use any special user-generated macros that might modify the Standard EDDs to work in a way that was not intended.