Early adopters of FDI technology have reported problems with the installation and configuration of the FF Standard DD Library. This application guide addresses the reasons for some of those problems, and offers details on how best to avoid them.
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 VM.
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.
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 overwrittenduring 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 afterthey 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.
- 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 includethe 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.
- 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.
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 bitsfor 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_OPTSparameter, 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_OPTSparameter, 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.
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 beforerelease 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 in section 4.2.3 to rebuild the library as necessary for your specific 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.
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”. When the FDI Tokenizer was developed, these same file names were assigned 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.
Developers wishing to change the FF Standard Library used by the FDI Package IDE need to follow the steps outlined in section 5 to avoid these problems.
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 exceptthe 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.
- 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.
- Make a copy of the folder that contains the library you are currently using, “C:\FF\DDL” to “C:\FF\DDL_SAVED”.
- 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 notcompatible 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.
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 registered recently with a new device.
When attempting to build their first FDI Package, the FDI Tokenizer reported:
“Error 518 - The type of item DEVICE_TAG was redefined”.
A variable DEVICE_TAG had been previously defined in their DDL code. The problem was that the same variable name DEVICE_TAG now exists as a standard parameter in one of the newer standard block profiles included in the standard library that was installed with the FDI Package IDE.
The original symbols.txt file for the device included:
member DEVICE_TAG record 0xC0014901
In this case, DEVICE_TAG is the name of a standard parameter in an ISA100 block.
One solution is to change this name slightly in 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. 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 at that time. 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 includes a standard definition for this parameter, so the tokenizer reported:
“Error 518 - The type of item COMPATIBILITY_REV was redefined”.
One solution is to find the standard text file in the FF Standard Library that included 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!