Scope

  • Early adopters of FDI technology have reported problems with the configuration of the FF Standard DD Library that comes with the new FDI IDE installation.  In many cases, they believe it should be downgraded to older versions of the standard library that are compatible with existing device projects they wish to enhance with the new FDI Technology.


  • Developers who wish to register updated/enhanced EDD files for previously registered Foundation Fieldbus products seem to resist using or upgrading their FF Standard DD Library installations because they believe doing so will make it impossible to tokenize the DDL code they created and registered on previous device projects.


  • FieldComm Group recommends that all developers use the most recent release of the FF Standard DD Library available for any device or EDD project.  This can help prevent interoperability issues and delays in product/EDD registration.


  • This support article is meant to address the reasons for some of the problems encountered by early adopters of the FDI IDE, and should dispel the myth that an older EDD project cannot be upgraded by using the latest Standard Library Release. 


Known Issues on PCs Hosting Both FF and HART IDE Tools

HART DD-IDE and FF DD-IDE Are Not Compatible

Both protocol DD IDE tools work with batch scripts that run in a command line environment, and both tools have similar folder structures and share some common file names because they were originally developed from the same set of source code. Relative path statements found in the batch scripts of one of these development tools can allow these scripts to call batch scripts or executables from the other tool, or to otherwise use incorrect files or folders from the other tool. With some effort, mixing these two development tools can be accomplished by carefully managing and updating the Windows environment variables when switching from a project in one tool to an another project in the other tool, but this can make it more difficult and confusing when trying to debug problems, especially for our support staff. For this reason, FieldComm Group does not support using the HART DD-IDE and FF DD-IDE tools together on the same PC. If a developer must use a single PC to do development with both tools, it is best to use Virtual Machines and keep the tools installed in their own Virtual Machine (VM).


FDI Package IDE Not Compatible with HART DD-IDE or FF DD-IDE Tools

The installation folders for the HART and FF EDD Tokenizers and Standard Libraries are the same as those used by the FDI Package IDE tool. Installing the FDI Package IDE on your PC will overwrite any previously existing installation of a tokenizer and standard library. This is true for both HART and FF. FieldComm Group does not support using either the HART DD-IDE or FF DD-IDE on the same PC as the FDI Package IDE.


The FDI Package IDE can be licensed for multiple protocols, and it can build EDD projects as well as FDI Projects. The FDI Package IDE was carefully developed to support projects across multiple protocols without the need to remove one IDE in favor of another. FieldComm Group recommends that EDD Developers migrate to the FDI Package IDE as soon as possible to take advantage of these benefits.


FF Standard Library Installed as part of FDI Package IDE

When using the FF DD-IDE, developers wishing to tokenize and build an EDD Binary must also own a license to the FF Standard Library. The FF Standard Library must be installed separately from the FF DD-IDE, and then the Standard DDs must be built using a series of batch scripts before it is possible to tokenize the EDD.


The FDI Package IDE does not require a developer to purchase or install the FF Standard Library. This FF Standard Library is now included in the installation of the Package IDE, and the standard EDDs are pre-built for end-user convenience. As mentioned in section 2.2, this means any existing installation of the FF Standard Library will be completely overwritten during the installation of the FDI Package IDE.


The same problem can be created in the opposite order. FDI Package IDE users should not install an older copy of the FF Standard Library after they have installed the FDI Package IDE. Doing so will completely overwrite the DDL code and batch scripts that are used to build the FF Standard DD library. Attempting to rebuild the Standard DD library later will lead to unexpected behavior and errors during tokenization.


The version of the FF Standard Library included with the FDI Package IDE will always be the latest version available. FieldComm Group recommends to always use the standard library that is released with the FDI Package IDE, even when working on a regular EDD project.


Working With the FF Standard Library

FF Standard Library Versions


The last official release of the FF Standard Library was version 3.81 in 2014.  This is major version 3 and minor version 81.  Minor version releases include bug fixes and add new features that did not previously exist in the Standard Library, such as new manufacturer identification codes, new reserved item id numbers, or even entirely new FF blocks that have been approved and added to the Foundation Fieldbus specifications. 


Major version releases of the FF Standard Library are necessary when significant improvements are made to the technology to improve interoperability.  New devices should be developed to the latest available Foundation Fieldbus specifications, and including the support for these latest specifications always requires using the newest release of the Standard Library.


At a minimum, FieldComm Group recommends that all developers use Standard Library version 3.81.  This release of the Standard Library has a significant bug-fix for the resource block parameter COMPATIBILITY_REV that is used for DD Forward Compatibility in an EDD Host.  Using library version 3.81 or later will ensure your device project uses the correct reserved item id number for this resource block parameter. 


Three major versions of the FF Standard Library have been released:


  • Library Version 3 is the current major version of the FF Standard Library.  This is most likely what was used on any device that has been developed since 2007. 
  • Library Version 2 would have been used on projects on or before 2007.  Library Version 2 installations of the FF Standard Library does not include the full set of standard function blocks and transducer blocks that exist today in FF specifications. 
  • Library Version 1 would have been used on extremely old projects from the late 90’s and early 2000’s and should not be used for any modern project.   


Reserved Item ID numbers for standardized block and DD items that existed in FF Standard Library Versions 1 and 2 are still fully supported in FF Standard Library Version 3.  Item IDs are not removed from the standard tables as new versions of the library are released.


To help new developers understand the correlation between FF Tokenizer versions and FF Standard Library versions, the following is generally true:


  • More recent FF projects were created using version 5.x of the FF tokenizer, and the EDDs were developed using Standard Library 3.x.  Such projects would have included both DD4 and DD5 binaries that were submitted at the time of product registration. 
  • Older FF projects were created using version 4.x of the FF tokenizer, and the EDDs were developed using Standard Library 2.x.  These older projects would have included only a DD4 binary that was submitted for product registration.





How to Convert FF Standard Library 2 Projects to Use Standard Library 3 Releases

Background Knowledge 

Differences Between LIB2 and LIB3


Two bit string parameters, IO Options and Status Options, are found in several different standard blocks. FF Specifications define unique meanings for each bit in these bit strings, but not every bit can be used in every block type where these parameters exist.


In Standard Library 2, a single item ID is reserved for each of these parameters. All sixteen possible bits for STATUS_OPTS and IO_OPTS are tokenized into a DD the same way, listing every possible bit for each occurrence of these parameters in an EDD. In these Library 2 EDD Binaries, it is possible for an end user to see and to select unsupported bits for these two parameters in an EDD host. Later, when downloading modified values to the device, unsupported bits which were selected by the end user are naturally rejected by the device (as required by FF Specifications), however, this results in discrepancies when comparing the values the host tried to set vs. the values the device accepted and were read back to the user.


EXAMPLE 1: In a EDD developed using Library 2, the IO Options Low Cutoff(bit 10) and Units Conversion(bit 12) will both be shown for every function block that contains the IO_OPTS parameter, even though these two bits of the bit string are only applicable in the AI function block.


EXAMPLE 2: In a EDD developed using Library 2, the Status Options Uncertain if Limited(bit 6) and BAD if Limited(bit 7) will both be shown for every function block that contains the STATUS_OPTS parameter, even though these two bits of the bit string are only applicable in the AI function block.


Standard Library Version 3 brought improvements for these parameters. Each block that supports STATUS_OPTS and IO_OPTS now has unique item id reservations and unique names for the variables represented by these parameters. Devices developed using Library 3 no longer have EDDs that display unsupported bits for these parameters. This leads to a much better user experience when configuring the device, especially in an EDD host. In the examples above, the bits defined to only exist in an AI block will only be seen in an AI block, in both the EDD and the device, if the project is developed using LIB3.


Device Firmware and Library Version Compatibility


Item id numbers of block parameters and block objects not only occur in a DD, they also occur in the function block application of the FF device as part of the object dictionary, which is part of the device’s firmware. The item id numbers for a block object in a DD must always match the item id numbers in the FF object dictionary in device firmware, else a host will not associate the correct variable with the block parameter when the value is read or written in the EDD Host.


If a developer simply uses LIB3 to build an EDD for a device developed with LIB2, mismatched definitions between the EDD and original device firmware will be created for the IO_OPTS and STATUS_OPTS parameters. The Item ID numbers in the EDD would use the newer block specific definitions for IO_OPTS and STATUS_OPTS that were created in LIB3, but the actual device firmware would be using the Item ID for the simple, single definition for these parameters that existed in LIB2. Interoperability problems would result.


To solve this problem, LIB3 provides a way to rebuild the standard EDDs so they contain the older definitions for IO_OPTS and STATUS_OPTS, while still providing all of the other updates that came with the newer Standard Library. This allows a developer to use the latest release of the Standard Library, even when working on EDD updates for older projects. It is not necessary to change between LIB3 and LIB2 when moving from a modern project to a much older FF project. This is accomplished through the use of some simple batch scripts included with LIB3.


How to Build or Rebuild Standard Library 3.x For any EDD Project

If your device was developed with any version of LIB3, and you are using the FF DD-IDE with a newer version of LIB3, simply run the batch files named “make_all_dd4.bat” and “make_all_dd5.bat” inside C:\FF\DDL to build the standard EDD library with normal support for LIB3. To build the appropriate EDD in an FDI Package with support for the normal LIB3 definitions you must also run a third batch script named “make_all_dd6.bat”.

If your device was developed with any version of LIB2, and you wish to use the FF DD-IDE to build a development environment in LIB3 that is compatible with devices developed with LIB2, run the batch files named “make_all_dd4_lib2.bat” and “make_all_dd5_lib2.bat” inside C:\FF\DDL.


If you are using the FDI Package IDE for development, three versions of the standard library must be built, since this tool also supports a DD6 inside of an FDI Package. If you are trying to create an FDI Package for a device developed originally with LIB2, you will also need to run a third batch script named “make_all_dd6_lib2.bat”.


NOTE regarding the FDI Package IDE:

  • Versions of the FDI Package IDE before release 1.3.0 included FF Standard LIB 3, but the Standard DD Library was either not built, or it was pre-built to support LIB2 projects by mistake. Please run the batch scripts as described above to rebuild the library as necessary for the needs of your original device project.
  • FDI Package IDE version 1.3.0 (November 2018) and all future releases of the FDI Package IDE includes LIB3 with the FF Standard Library pre-built for LIB3 projects. A developer will only need to rebuild the library if the device firmware for the project originally supported IO_OPTS and STATUS_OPTS as they were defined in LIB2.


Possible Pitfalls During Conversion

FF Tokenizer Name Changes Cause Batch Script Errors When Rebuilding the Standard Library

The names of the executables for the FF tokenizer and pre-tokenizer found in the FF DD-IDE were always “ffpretok.exe” and “ff_tok32.exe” through FF DD-IDE release 1.2.1 (tokenizer 5.2.1).  When the FDI Tokenizer was developed, these same file names were given to the pre-tokenizer and tokenizer that builds DD6 EDDs for an FDI Package. As a result, when DD4 and DD5 support was later added to the FDI Package IDE, the older pre-tokenizer and tokenizer had to be renamed to “ff5pretok.exe” and “ff5_tok32.exe” to differentiate between the two different FF tokenizer tools.


The batch scripts included with the released installers for the FF Standard Library will refer to the DD4 and DD5 tokenizer by their original filenames (“ffpretok.exe” and “ff_tok32.exe”). The FDI Package IDE did not exist the last time the FF Standard Library was released (i.e. version 3.81 in 2014).


If a developer has already installed the FDI Package IDE, but then runs one of the old installation packages for the FF Standard Library, all of the batch files and standard library sources will be overwritten with those from the older FF Standard Library. When an attempt is made to build the Standard DD Library with the batch scripts, all of them will call only the FDI Tokenizer, and there will be a considerable amount of errors displayed in the command line console.


If a developer has already installed the FDI Package IDE, and then attempts to use the FF Standard Library folder from a previous FF DD-IDE project by overwriting the folder installed by the FDI Package IDE with the one from their older project, the same problem will occur. The batch scripts will not properly rebuild the standard DD library because they call what is now the FDI tokenizer. If the standard DD binaries build at all, they will only be DD6 EDDs.


While FieldComm Group does not recommend doing so, developers wishing to change the FF Standard Library used by the FDI Package IDE need to carefully follow the steps outlined in the last section of this support article in order to avoid this pitfall.


Tokenizer Name Change in FF DD-IDE 1.2.2

FF DD-IDE version 1.2.2, released in 2017, uses the newer executable names of “ff5pretok.exe” and “ff5_tok32.exe”. If a developer were to install this tokenizer over a previously installed FDI Package IDE, it would cause no known problems to the FDI IDE environment, because the batch scripts to build the library that were installed by the FDI Package IDE will not be changed by the installation of the FF DD-IDE.


However, at the time of the release of this document, no new installation package of the FF Standard Library has been released with batch scripts that call the DD4 and DD5 tokenizers by their new names except the Standard Library that is included with the installation of the FDI Package IDE.


Developers using the latest release of the FF DD-IDE will need to customize the batch scripts in their existing FF Standard Library folders so they can continue to build the Standard DD Library by calling the appropriate tokenizer by name.


To fix this, each of the six “make_all_” batch files found in C:\FF\DDL must be edited in a simple text editor. Perform a “replace all” using the search item “fftok” and replace it with “ff5tok”. Save each batch file. Now run the batch files necessary to build the Standard Library so it will support your EDD project by using the appropriate support for either LIB2 or LIB3.


Workarounds for an Older Project While Keeping the Latest Standard Library in the FDI Package IDE

Developers using the latest Standard Library that comes pre-installed with the FDI Package IDE may sometimes find a problem when tokenizing the DDL code of an older device project if something new was added to the standard library that has the same variable name as a manufacturer specific item defined in their DDL code. This will cause the tokenizer to report errors for a “redefinition” when something found in the symbols.txt file is already defined in the standard library.


Example 1: A developer replaced the FF DD-IDE with the FDI Package IDE. A new project was created and it used their existing DDL code for the DD4 and DD5 binaries that were previously created using standard library 3.80.  These DD4 and DD5 binaries were registered with their most recent device revision.


When attempting to build their first FDI Package for this same device revision, the FDI Tokenizer reported:


“Error 518 - The type of item DEVICE_TAG was redefined”. 


A variable DEVICE_TAG was defined in their device's DDL code. The problem was that the same variable name "DEVICE_TAG" now existed as a standard parameter in one of the new standard block profiles included in the standard library (3.82) that was installed with FDI Package IDE 1.3.0.


The original symbols.txt file for the device included:


member DEVICE_TAG record 0xC0014901


DEVICE_TAG is now the name of a standard parameter in an ISA100 block that was added to DD Library 3.81.


One possible solution is to change this name slightly in the DDL to something like ”__DEVICE_TAG” and the references in the rest of the DDL code could be updated to use the same slightly modified variable name. Updating the symbols.txt file in the same way completed the workaround, while also preserving the state of the newer standard library installation that came with the FDI IDE.  After making this change, the developer’s original source files tokenized normally in the FDI Package IDE.


Example 2: Early adopters of a new common practice resource block parameter "COMPATIBILITY_REV" built DD files without using a standard library that included a definition for this block parameter. As a result, the developer’s DDL code for the resource block had to define this parameter, and the FF Tokenizer generated a custom item id number for it since no specific definition was found in the Standard Library prior to release 3.81.  Device firmware also used this custom item id number that had been generated by the tokenizer, and the device and DDs were registered with this customization.


When trying to tokenize the original DDL code in the FDI Package IDE, the installed Standard DD Library (3.82) now includes a standard definition for this parameter, so the tokenizer reports:


“Error 518 - The type of item COMPATIBILITY_REV was redefined”. 

 

One possible solution is to find the standard text file in the FF Standard Library that includes the definition for COMPATIBILITY_REV. This parameter definition was found at the end of the symbols.txt file for standard parameters in “C:\FF\DDL\RELEASE\000000\0100\symbols.txt”. To make this newer library build a DD compatible with the old project and device firmware, the developer added a hash tag to the last line of the file where this definition was found:


#member COMPATIBILITY_REV parameter 0xC0020867


The symbols.txt file for standard parameters was then saved. The Standard DD Library was then rebuilt using the appropriate batch scripts as described in section 4.2.3. This removed the standard parameter definition for COMPATIBILITY_REV from the local copy of the Standard DD Library. The original DDL then tokenized without errors, and the EDD inside the FDI Package matched the firmware of the original registered device for the COMPATIBILITY_REV parameter.


Of course, a future project should use the newer reservation for COMPATIBILITY_REV. In this case, the developer should immediately reverse the change made to the standard parameters symbols.txt file and rebuild the Standard DD Library to ensure such a mistake is not made again on their next device project!


How to Move the FDI Package IDE to an Older Version of the FF Standard Library

Background

FieldComm Group recommends that developers use the FF Standard Library that is included with the installation of the FDI Package IDE.  Using the information above, it is possible to rebuild the Standard DD Library in a way that supports any past or present device project.  


If all other attempts to build your old EDD project fail, but you still wish to build an FDI Package for this old EDD project, carefully follow the following instructions.


Assumptions

  • The developer is currently using a version of the FF DD-IDE to work with their DDL project.
  • The developer currently has the preferred DD Standard Library on their PC and is using it with the FF DD-IDE.
  • Any existing symbols.txt files and DD Binary files on your computer have been backed up. The standard location where these are found is “C:\FF\DDL\Release”.
  • Any existing DDL Source files that may exist on your computer have been backed up. Refer to the project settings in the FF DD-IDE if you are unsure of the location of your project source files.
  • After backing up all information related to your project(s), the FF DD-IDE is uninstalled using the add/remove programs tool in the Windows Control Panel.

Steps to Move to an Older Standard Library

  • Make a copy of the folder that contains the library you are currently using, “C:\FF\DDL” to “C:\FF\DDL_SAVED”. 
  • From the Windows Control Panel add/remove programs tool, uninstall the FF Standard DD Library if it is found there. 
  • If a “C:\FF\DDL” folder remains with any contents after the FF Standard DD Library has been uninstalled, delete this folder.
  • Install the FDI Package IDE and all associated components, pre-requisites, etc. as described in the user guide of the FDI Package IDE. 
  • After the FDI Package IDE is installed, a new “C:\FF\DDL” folder will exist on your hard drive.  This is the latest version of the Standard Library. Since you do not wish to use the newer library at this time, rename the folder “C:\FF\DDL” to “C:\FF\DDL_NOT_USING”.  Don’t delete the folder.  Keeping the newer library folder will allow a developer to change back to the latest release once the need for the customized library has been met.  Any new project should use the library installed with the FDI Package IDE.
  • Rename the DDL folder you saved earlier from “C:\FF\DDL_SAVED” back to “C:\FF\DDL”.
  • Verify your original MANUFAC_ID and DEV_TYPE folder structure is still found inside the “C:\FF\DDL\Releases” folder, and make sure your original symbols.txt file for your device project is found inside the appropriate folder.  The symbols.txt file has all the symbols that were automatically generated by the FF tokenizer for device specific items not defined in the Standard Library.  These symbols are part of the device firmware and must not change. 

IMPORTANT: If the symbols.txt file is not found when the next DD binary is built, the tokenizer will auto-generate a completely new symbols.txt file that will not match the existing device firmware.        

  • Go to the “C:\FF\DDL_NOT_USING” folder.  Select all nine of the “make” batch scripts in this folder and copy them to the “C:\FF\DDL” folder.  This will overwrite the six existing batch files there, and add three new batch files for building and testing the DD6 standard block library for FDI.  These nine batch files use the correct path statements and ultimately call the two different FF tokenizers and pre-tokenizers by their correct names as they are found within the FDI Package IDE. 
  • Depending on the needs of your project, run the three scripts from “C:\FF\DDL” to build the appropriate version of the DD Library that matches your device’s firmware:
    • If you need to build the version 3.x compatible library, run “make_all_dd4.bat”, “make_all_dd5.bat”, and “make_all_dd6.bat”, one at a time, until each one is completed.
    • If you need to build the version 2.x compatible library, run “make_all_dd4_lib2.bat”, “make_all_dd5_lib2.bat”, and “make_all_dd6_lib2.bat”, one at a time, until each one is completed.
    • Doing either “a” or “b” will rebuild the Standard DD Library with your specific customizations.
    • You will notice some errors building some of the Standard DDs.  These can be ignored for older device projects.  The errors occur because the batch scripts being used include the newer  standard blocks currently found in Foundation Fieldbus specifications that did not exist at the time the library in use was customized.  Those blocks will not have Standard DD files built because the DDL files to build them cannot be found.  Any standard block profiles found in your older project should still tokenize and build normally.  The batch files are attempting to build standard SCP blocks, HSE ROM Blocks, and ISA100 blocks that were included in the FDI Package IDE release, but will not be found in the older library folder that was customized for a previous project.

  • Note that project files from the FF DD-IDE are not compatible with the FDI Package IDE.  Refer to the old DDP project files in a text editor to get settings information from an older project.  A new project file will have to be created for the FDI Package IDE using the project wizard prior to using the FDI Package IDE for the first time.  Please refer to the user guide of the FDI Package IDE for further information on creating a new EDD project or FDI Package project.