Update FESA device instance files in the device-instance part, data taken from a text file.

Utility is located: /common/usr/cscofe/bin/fesa-instance


usage: fesa-instance [options] <cmd-file>
expects instance files in <base directory>/src/test/<front-end node>/
looks for instance files: DeviceData*.instance
-d <base directory> e.g. ~/workspace/PowerSupply_DU/
-n <front-end node> e.g. scuxl0037
multiple nodes: use wildcards, BUT to overcome shell-expansion ALWAYS QUOTE (or ESCAPE) WILDCARDS!!
quoted wildcards: like -n '*' or -n 'scuxl0??3'
default value: all nodes ('*')
-b <bitmap-definitions>: specifies XML-file with bitmap definitions, e.g. for detailed status labels
-r read values from instance file(s), with options -v <variable location> and -e <event-mapping>
-p <deploy-unit>: for option -r, read files from fec nfs-filesystem
-i input-format output, for option -r / -p, output can be used as input-command file
-t test-only, displays modifications, no update of instance files
-u update nomenclatures in command file, output to <cmd-file>-new
-h displays short help

<cmd-file> input-data
structured text file,
details see section 'Structure of Text File'

The utility fesa-instance will update entries in the device-instance section of the device-instance files for the given front-ends, with values which are defined in the command file.

The device instance files in the corresponding subdirectory will be replaced by the updated new versions!. Up to three older versions of the device instance files are kept, with suffix ~, ~~ and ~~~.

To display modifications but not change the instance files, use option -t.

Special Modes (options -u, -r, -p, -t)

The utility fesa-instance may be used to
  • update device names (option -u) in command file:
    generate a new file (<cmd-file>-add), containing all nomenclatures from the instance files which are not contained in the command file (neither in device entries nor in group entries), in the form device GTK1MU1
  • read entries from instance files (option -r):
    read and display an entry (given by option -v <entry location>) or an event-mapping (given by option -e <event-mapping) for all devices in the instance file
    • read from fec boot-filesystem (option -p <deploy-unit>), from files used by the front-end computer (read from /common/export/fesa/local/<fe-name>/<deploy-unit directory>)
  • only display modifications of the instance files (option -t) but not change the instance files

test modifications instance files will not be changed: fesa-instance cmd.txt -d ~workspace/PowerSupplyHebt_DU -t
look for nomenclatures which are not contained in cmd.txt : fesa-instance cmd.txt -d ~workspace/PowerSupplyHebt_DU -u
read entries from development directory: fesa-instance -d ~workspace/PowerSupplyHebt_DU -v configuration.timingDomain -e VoltageSetEvent
read entries from production directory: fesa-instance -d PowerSupplyHebt_DU -v configuration.timingDomain -e VoltageSetEvent

Structure of Text File

Each line in the file is a separate command.

Each command (each line) starts with a command-key. Command-keys may be abbreviated as far they still are unique, which is down to single letters.

Supported Commands

Commands to Combine Single Commands

ACCUMULATION <accumulation name>
defines a set of commands (bitmap, copyvalue, event or variable) which can be executed as a whole
an ACCUMULATION command should be followed by event- and variable-commands which define the commands to be executed in the accumulation command

GROUP <group name>
defines a set of device names which can be accessed by the group name
a group command should be followed by nomen-commands which define the contents of the group

nomen <device-name>
used in GROUP command only: defines the name of a device to be added to the present group of devices

Commands to Identify Devices for which Commands Will Be Executed

device <device-name>
defines the device for which following accumulation-, bitmap-, copyvalue-, event- and variable-commands are to be executed

group <group name>
defines the group of devices, for which following accumulation-, bitmap-, copyvalue-, event- and variable-commands are to be executed

Commands which are Executed for Devices/Groups of Devices

accumulation <accumulation-name>, execute all commands in the accumulation
execute all commands in the accumulation for the previously given device or the devices of the previously given group

bitmap <bitmap name>
sets bitmap data, contained in special XML bitmap-file, for a device (usage for detailed status or module status information)

copyvalue <destination location> <source location>
copies the value from source location to destination location

event <event-mapping> <value>
defines values for entries in the events-mapping section in the device-instance part of the FESA device instance file
event-mapping: the event-mapping, as defined in the instance file (e.g. <ValueSetEvent>) to be modified
value: the value for the event mapping

variable <data-location> <data-value> [<dimension>]
defines a value for an entry in the device-instance section of the FESA device instance file
location: gives the sub-node in the instance file, in the form <sub-node>.<sub-sub-node>
an entry configuration.timingDomain means the sub-sub-node <configuration><timingDomain>...<timingDomain/><configuration/>
data-value: the value for the entry. If the value should contain blanks, it has to be enclosed in quotation marks
dimension: the dim or dim1 value for the dimension of Arrays, if needed

Bitmap Data (Detailed Status Bits, Module Status Bits, Others)

Some of the device configuration data are in the form of lists. In some cases, like the device detailed status bits, items in different lists have to correspond. Ensuring the right position of the items can be difficult, especially for long lists.

To simplify handling of such lists, the can be specified item by item in a specific XML-format in a separate file. From this file, entries for the FESA device-instance file will be generated.

Such bitmap definition files have to be specified by option -b. The format of the definition file is explained in the page FESA-Instance BitMap Definition.


Entries in the device-instance section of the instance-file are given as <area>.<value>, which means

configuration.accelerator will expand to <configuration> <accelerator> </accelerator> </configuration>

Data will be updated when given as value-attribute or as value subnode in the XML instance file.


When executing the fesa-instance utility, FESA device-instance files will be updated. The three last versions of the instance files will be available, indicated by <file>~, <file>~~ and <file>~~~

To avoid updating, but still display changes, use option -t (test-only).


For better reading, lines may be indented. Lines starting with hash (#) are interpreted as comments.

Example 1: Modifying entries, using groups of devices and accumulation of commands

Example 2: Update bitmaps, like detailed status entries
Topic revision: r18 - 19 Mar 2019, UdoKrause
This site is powered by FoswikiCopyright © by the contributing authors. All material on this collaboration platform is the property of the contributing authors.
Ideas, requests, problems regarding Foswiki? Send feedback