CIF PLC code generator (experimental)

This application is in the experimental stage.

It may or may not perform as expected. In addition, functionality may change or disappear without prior notice and without providing a backwards-compatible alternative.

For now, use the stable CIF PLC code generator instead.

The CIF PLC code generator takes a CIF specification and creates real-time Programmable Logic Controller (PLC) code that can read values from external inputs, evaluate the state and perform event transitions, and finally write values to external outputs. The resulting code is written in the Structured Text programming language, one of the programming languages that is part of the IEC 61131-3 standard.

The generated code is not intended to be modified directly. Instead, the original CIF models should be modified, and from them new PLC code should be generated.

To successfully deploy the generated code at a real system, the CIF model should satisfy certain conditions and the used PLC should have a sufficiently short cycle-time to catch all input changes.

Starting the generator

The CIF PLC generator can be started in the following ways:

  • In Eclipse, right click a .cif file in the Project Explorer tab or Package Explorer tab and choose CIF implementation tools  Generate PLC code for CIF specification…​ (experimental).

  • In Eclipse, right click an open text editor for a .cif file and choose CIF implementation tools  Generate PLC code for CIF specification…​ (experimental).

  • Use the cifplcgen tool in a ToolDef script. See the scripting documentation and tools overview page for details.

  • Use the cifplcgen command line tool.

Options

Besides the general application options, this application has the following options:

Basic settings of the CIF PLC code generator

As different PLC systems have different expectations and limitations in what they accept as input, behavior of the PLC code generator heavily depends on the chosen PLC target. This is configured with the PLC target type option:

  • PLC target type: The PLC code target type specifies the form of the desired output for the PLC model that eventually will run the generated code. Default value is PLCopen XML.

Other important settings are the Input file path for the CIF specification, the I/O table file path to the file that contains the connections to the external inputs and outputs, and the Output file for writing the generated PLC code:

  • Input file: The absolute or relative local file system path to the input CIF specification.

  • I/O table path: The absolute or relative file system path to the I/O table path file that contains the I/O connections. For more information, consult the I/O table section. Default path is derived from the CIF Input file option value. The .cif file extension is removed if it exists. Then, a .csv file extension is appended.

    If the file path does not exist, code generation will continue with a warning that the generated code will not perform I/O with its environment.

  • Output file: The absolute or relative local file system path to the output file or directory. If not specified, the output path will depend on the Input file option value. The result also depends on the chosen target type.

Tailoring the output of the code generator

Additional options exist to tailor the output of the code generator:

  • Simplify values: Enable this option to simplify values in the generated PLC code. The resulting code expresses more directly what values it actually uses as the cost of less abstractions in the generated code. This may make reviewing more difficult. This option is by default enabled.

  • Rename warnings: Names in the CIF specification are re-used to improve linking generated PLC code back to the CIF file. However, as PLC code has different requirements for names, the names from the CIF specification are not always used as-is. This option is by default disabled. By enabling this option, the generator prints a warning whenever a CIF name is not used as-is in the PLC code. This allows to obtain the original CIF name for the adapted name that is used in the generated PLC code. For more information, see the section about names.

Overriding target type choices

Selecting the target type is usually enough to get PLC code for that PLC model. If that is not sufficient, the PLC code generator also allows overriding choices to tailor the generated PLC code.

Note that these options do not take limitations of the PLC model into account. An incorrect choice in these options may thus make the generated PLC code unusable for the specified target type. When using these options, always make sure the intended PLC model supports the configured values.

  • Convert enumerations: Enumerations may have been used in the CIF specification. In addition, the PLC code generator introduces enumerations in its conversion of automata. This option controls how all enumerations are converted to PLC code:

    • Use Automatically decide how to handle enumerations (--convert-enums=auto) to let the code generator decide based on the configured target PLC model. This is the default value of the option. It will either preserve enumerations if the PLC model supports them, or it will convert the enumerations by one of the alternatives described below.

    • Use Preserve enumerations (--convert-enums=keep) if the target PLC supports enumerations. It is generally the preferred value because using enumeration names improves readability of the generated PLC code.

    • Use Convert enumerations to constants (--convert-enums=consts) if the target PLC does not support enumerations but does support constants. This option value also causes generation of names in the PLC code, but information about which names belong together is lost.

    • Use Convert enumerations to integers (--convert-enums=ints) if the target PLC neither supports enumerations nor supports constants. This option value causes numeric values to be generated for values of the enumerations. That may cause difficulties in reviewing the generated PLC code.

  • PLC maximum iterations: The controller checker should be used to ensure that the PLC code generated by the PLC code generator will always finish its PLC cycle by checking that the maximum number of events that can be done in a single cycle is finite. However, even if the number of events is known to be finite, it can in some cases still take a long time to finish the PLC cycle. This option sets or disables the upper limit on the number of performed transitions in a single PLC cycle.

    It is not recommended, but by setting an upper limit, long cycle times can be avoided at the cost of not always performing all enabled events. Default value of this option is to disable the upper limit.

  • PLC task name: The name of the generated PLC task that runs the converted CIF specification. If not specified, defaults to PlcTask.

  • PLC project name: The name of the generated PLC project. If not specified, defaults to Untitled1.

  • PLC configuration name: The name of the generated PLC configuration. If not specified, defaults to Untitled1.

  • PLC resource name: The name of the generated PLC resource. If not specified, defaults to Untitled1.

  • PLC task cycle time: If periodic task scheduling is desired, set the scheduling interval in milliseconds for the task in the generated PLC code. To disable periodic task scheduling, disable the option. This option takes positive integer values and defaults to periodic task scheduling with a cycle time of 10 milliseconds.

  • PLC task priority: The scheduling priority of the task to generate. The priority must be in the range [0 .. 65535], where priority 0 is the highest priority, and priority 65535 is the lowest priority. The priority can be used for preemptive or non-preemptive scheduling. If not specified, the priority defaults to 20.

  • PLC integer type size: The number of bits of an integer value in the PLC. The default value of this option lets the target type decide. In general that is 32 bit, which is also the size of an int in CIF. If the PLC supports only smaller integer values, the largest available size is chosen.

  • PLC real type size: The number of bits of a floating point value in the PLC. The default value of this option lets the target type decide. In general that is 64 bit, which is also the size of a real in CIF. If the PLC supports only smaller floating point values, the largest available size is chosen.

Supported specifications

The CIF PLC code generator assumes that the given CIF file has the following properties:

  • It does not suffer from runtime evaluation errors. For instance, it should not be prone to division by zero, accessing out of bound array indices, assignments of out of range values to variables, and so on. To ensure such problems do not occur, apply synthesis to the model.

  • It has finite response. This property can be checked using the controller checker tool.

  • It is confluent. This property can be checked using the controller checker tool.

  • It is non-blocking under control.

Pre-processing

To enlarge the accepted set of CIF files, the following transformations are first performed:

Specification checks

After pre-processing, a check is performed whether the CIF file meets all the requirements of the CIF PLC code generator:

  • For components, the following conditions must be met:

    • No initialization predicates outside locations that restrict initialization.

    • No equations outside locations.

  • For automata and invariants, the following conditions must be met:

    • At least one automaton.

    • All automata must have a single initial location that can be statically decided.

    • Discrete variables must have a single initial value.

    • No state invariants that restrict behavior.

    • No tau events. This includes edges without an event.

    • No urgent locations and edges.

    • No equations.

  • For user-defined functions, the following conditions must be met:

    • No internal user-defined functions.

    • No external user-defined functions.

  • For continuous variables the following conditions must be met:

  • For expressions and data types, the following conditions must be met:

    • No sets, dictionaries, strings, and stochastic distributions.

    • Only arrays, so no non-array lists.

    • No arrays for the S7 targets.

    • For arrays: no +, -, =, !=, empty, delete, in, pop, size, and slicing.

    • For tuples: no = and !=.

    • Standard library functions: no acosh, asinh, atanh, ceil, cosh, floor, round, scale, sign, sinh, and tanh.

    • No functions used as data values or stored in variables. Functions must thus only be used to call the function.

    • No use of variable time.

    Depending on the PLC target type, additional restrictions may apply. Please consult the next section for details.

  • Furthermore:

    • I/O declarations are ignored. A warning is printed if a CIF/SVG input declaration is encountered.

    • Annotations are ignored.

Target types

The PLC code generator output contains a single program called MAIN. This program is instantiated in a task, which is part of a resource, which in turn is part of a configuration. The configuration is put in a project, but that is outside the range of the IEC 61131-3 standard. Most implementations however, work with projects.

The effect of the project, configuration, resource, and task is dependent on the configured target. Unless overridden with options, the target also affects the shape of lower level details such as the form of the function calls, selected size of integers, and other configuration that tends to be different for different PLC systems. Last but not least, the target affects how the generated output gets written to files.

The PLC code generator supports the following targets:

  • ABB:

    Output for the ABB target generates multiple files in a directory. By default, if no output directory is specified, it defaults to the input file path, where the .cif file extension is removed (if present), and a _abb directory extension is added. The MAIN program gets a .plcprog file extension, functions get a .plcfunc file extension, type declarations get a .plctype file extension, and the configuration gets a .plccfg file extension.

    The PLC project name and PLC resource name options have no effect for this target type.

  • IEC 61131-3:

    Output for the IEC 61131-3 target generates multiple files in a directory. By default, if no output directory is specified, it defaults to the input file path, where the .cif file extension is removed (if present), and a _plc directory extension is added. The MAIN program gets a .plcprog file extension, functions get a .plcfunc file extension, type declarations get a .plctype file extension, and the configuration gets a .plccfg file extension.

    The PLC project name and PLC resource name options have no effect for this target type.

  • PLCopen XML:

    PLCopen XML is an XML-based file format standardized by the PLCopen organization, intended for the exchange of complete projects of PLC code, even across different tools and vendors. The generated PLCopen XML file is compliant with version 2.01 of the PLCopen XML standard.

    Output for the PLCopen target generates a single file. By default, if no output file is specified, it defaults to the input file path, where the .cif file extension is removed (if present), and a .plcopen.xml file extension is added.

  • SIMATIC S7-300, S7-400, S7-1200, or S7-1500:

    Totally Integrated Automation Portal (TIA Portal) is an IDE for the development and testing of SIMATIC controllers. Using the S7 target, the generated PLC code can be imported in TIA Portal.

    Output for the SIMATIC target generates multiple files in a directory. By default, if no output directory is specified, it defaults to the input file path, where the .cif file extension is removed (if present), and a _s7_<ver> (<ver> being either 1500, 1200, 400 or 300) directory extension is added. The MAIN programs and functions get a .scl file extension, type declarations get a .udt file extension, the persistent variables databases get a .db file extension, and the global variable lists get a .xml file extension.

    The PLC task name, PLC task cycle time, PLC task priority, PLC project name, PLC configuration name, and PLC resource name options have no effect for this target type. Currently, the PLC code generator cannot generate code for arrays for these systems. Therefore, all forms of CIF lists are forbidden for these target types.

    See the S7 PLC output section for details on how to transfer generated code to the PLC system.

  • TwinCAT:

    TwinCAT is a complete IDE for the development and testing of PLC controllers. Using the TwinCAT PLC target type, the generated PLC code is written to the native file formats of the TwinCAT IDE.

    Output for the TwinCAT target generates multiple files in a directory tree. By default, if no output directory is specified, it defaults to the input file path, where the .cif file extension is removed (if present), and a _twincat directory extension is added.

    See the TwinCAT PLC output section for details on how to transfer generated code to the PLC system.

I/O table file

The PLC code generator generates PLC code that reads input values from external inputs and writes output values to external outputs. Inside the PLC these values are transferred using variables with an I/O address. To make such connections in CIF, some of the input variables should be connected to input addresses, and some of the discrete variables should be connected to output addresses. This is done by writing an I/O table file (details follow below), and giving it to the PLC code generator.

The generated PLC code will automatically read all inputs at the start of a PLC cycle and store them in the connected input variables. The values of the variables can for instance be used in a guard or a computation, or get copied to other variables. At the end of a cycle, outputs are written in a similar way by using the values of the connected discrete variables.

The I/O table file is a Comma Seperated Values (CSV) file. The CIF PLC code generator assumes the RFC-4180 format for this file, which is compatible with many spreadsheet programs. Each line has three columns and describes one connection with a variable:

  • The first column contains the PLC input or output address.

    An example address is %IX35.2.15. It always starts with a %. The other parts are:

    • The I is the kind of connection. The I means it reads from an external input, a Q at that position means writing to an external output, and an M means reading or writing memory inside the PLC.

    • The X describes the amount of data being transferred. The X or not specifying a letter means 1 bit is transferred (in CIF, a bool type). A B at that position means transfer of a byte (8 bits), a W means transfer of a word (16 bits), a D means transfer of a double word (32 bits), and an L means transfer of a long word (64 bits).

    • The last part of an address is a sequence of numbers separated by dots. In the example it is 35.2.15. The length and meaning of the sequence can vary between different PLC systems. Consult the manual of the target PLC system for details. In general the sequence indicates which of several available I/O ports is being used.

  • The second column optionally contains the PLC type of the input or output. If left empty, the type of the CIF variable is used instead.

  • The third column contains the non-escaped absolute name of the CIF variable connected to the I/O address. For example, the variable of the automaton below is named G.A.v:

    group G:
  automaton A:
    disc int v;
    ...
  end
end

Depending on the PLC target type, additional restrictions may apply on addresses. Consult the manual of the target PLC system for details.

The kind of connection, the direction of the connection, and the allowed kind of variable are related in the following way:

Connection kind Direction Variable Kind

I

from input

input variable

Q

to output

discrete variable

M

from memory

input variable

M

to memory

discrete variable

The number of transferred bits must match with the CIF type of the variable as follows:

Transfer size PLC type CIF type

1

BOOL

bool

16

INT

int (for PLC systems that do not support 32 bit integers)

32

DINT

int (for PLC systems that support 32 bit integers)

32

REAL

real (for PLC systems that do not support 64 floating point)

64

LINT

int (for PLC systems that support 64 bit integers)

64

LREAL

real (for PLC systems that support 64 floating point)

Continuous behavior

Within PLC systems, a major use for continuous behavior is timers to detect (sufficient) passage of time. For instance, a reaction could be expected to happen within some period of time, but if it does not happen something else must be done. Another use case is to wait for a certain amount of time before a next action may be started. The PLC code generator assumes that continuous variables are always used for such purposes.

To reduce possible confusion with timer values, the common case of checking for timeout should be done against 0. In that way, the check is always the same no matter what the initial timer value is. It is simpler to reason about positive values, so initial timer values should be positive. Finally, time is measured in seconds, since that is an SI unit, and a common amount of time for PLC controlled systems. This leads to a derivative of -1 for the continuous variables. Unlike continuous variables in CIF, timers in the PLC stop measuring when they reach timeout. To preserve CIF behavior when generating PLC code, values used in comparisons against timers are restricted to non-negative values.

The following conditions therefore apply to continuous variables in the input CIF specification:

  • The derivative of a continuous variable must always be -1 or -1.0, and this value must be statically decidable.

  • Continuous variables must only be compared to an inclusive upper-bound that is zero or larger. The upper-bound value must be statically decidable.

    For example, for a continuous variable c, the comparisons c ⇐ 0 or 5 >= c could be used. The former example checks for timeout (zero seconds left), the latter example checks whether there are five seconds or less remaining.

  • Each assignment of a new value to a continuous variable should be separate. That is, use do c := 1.0, d := 2.0 on edges. Other forms like do (c, d) := (1.0, 2.0) are not allowed.

  • Values used to initialize a continuous variable, or to assign to a continuous variable must be larger or equal to zero, and this must be statically decidable.

As a more elaborate example, the following automaton will enable the timeout event 10 seconds after the last reset event:

automaton Timer:
  cont t der -1;

  location timed_out:
    initial;
    edge reset do t := 10; goto running;

  location running:
    edge reset do t := 10;
    edge timeout when t <= 0 goto timed_out;
end

Resulting PLC code

In general, the PLC code generator attempts to preserve as much (of the structure) of the original CIF specification as possible. For example, names of elements in CIF are also used for their converted equivalents in the generated PLC program.

However, some parts of CIF specifications are not supported by any PLC system. For example, multiple automata and synchronizing on events or channels is unknown in a PLC system. For these cases the generator produces significantly different code, compared to the CIF specification. For example, for taking an event transition, all edges are grouped by event instead of grouping by automaton.

Other parts are supported only by some of the supported PLC systems. For these cases, the generator tries to generate the form that fits best within the abilities of the targeted PLC system and the configured options. For example, enumerations and constants are not always supported. The PLC code generator may change enumerations to constants or plain numbers in such a case.

From a bird’s-eye view, the PLC code generator generates one main program that performs the entire PLC cycle. It consists of the following steps:

  • Read values from the external inputs.

  • For the first cycle, initialize the CIF variables and automata locations. For every next cycle, update the continuous variables for the passed time.

  • Repeatedly check whether any of the events is enabled:

    • Each event is tried in turn.

    • If an event is found to be enabled, perform the event transition, and update the state of the controller.

    • After checking all events, if at least one transition was thus performed, all events are tried again. The performed transition(s) may have changed the state, enabling other events. Such events must be performed as well in the same cycle, since in CIF time cannot progress if an event is enabled.

  • If no enabled events exist any more, write values to the external outputs.

Names

Generated PLC code contains names for PLC elements like functions, variables, enumeration literals, and so on. If such an element represents a CIF element in the PLC code, the absolute name of the CIF element is used as name in the PLC code. In this way it is easier to link parts of a CIF specification with parts of the generated PLC code.

However, name requirements in CIF are different from name requirements in a PLC system. As as result, names of CIF elements cannot always be used as-is in the PLC code, and must be changed before they can be used in the PLC code.

In general, names are preserved as much as possible. However, in case of confusion where a PLC name originates from, the PLC code generator has a Rename warnings option in its options. By enabling the option, the code generator will print warnings whenever a CIF name is not used as-is.

Note that the PLC code generator also generates output that is closely related to CIF elements, but not directly representing the CIF element itself. In such cases the variable may get a slightly different name to keep the name of the CIF element available for other uses, but at the same time still show the connection with the CIF element.