.LF file format

Introduction

The .lf file format is a human-readable format for representing core model's semantics for state machines and all their properties. Its intended use case is the creation and manipulation of state machines using light-weight tools such as a text editor and a command line interface to read, validate and upload state machines to the core.

.lf files

A .lf file holds a single root state, all its hierarchical child states, as well as all ports, barriers, actions, parameters, variables and results. The name of the file directly acts as the name of that state, e.g. a file called Wiggle.lf is interpreted as a state machine called 'Wiggle'.

State machines can also contain script code, e.g. for actions. Scripts are stored within .lf files as well, but they are enclosed in special tags (@{ as the opening tag and }@ as the closing tag).

An example of a state machine representing a simple timer module is given below:

Timer {
  port done service("timer").operation("wait").status == "success"

  parameterType {
    float duration;
  }

  entry @{
    service("timer").operation("wait").call(parameter.duration)
  }@

  clientData {
    type : "app";
  }
}

Note that the script language for actions (including entry and exit actions) is Lua.

In the following sections, we will go over the grammar of the individual elements.

Elements of a state machine

A state machine consists of several elements. The following figure shows an overview of them. For a simple state only the name of the state machine and the ports are mandatory, all the other elements can be used if necessary. If you want to build a Desk app, a few more elements are necessary which are explained later in the tutorial.

The next code block displays these elements in Lingua Franka. The order of the elements inside the state does not matter. The structure of the child states is similar to the parent state. All the elements can be used, except of the clientData block.

App {
  port Success child("child_state_2").port("success")
  port Error child("child_state_1").port("error") or
             child("child_state_2").port("error")

  clientData { ... }

  parameterType { ... }

  resultType { ... }

  variableType { ... }

  entry @{ ... }@

  action ..condition.. @{ ... }@

  action ..condition.. @{ ... }@

  exit @{ ... }@

  --> child_state_1 {
    port success ..condition.. -> child_state_2
    port error ..condition..

    parameterType { ... }
    resultType { ... }
    variableType { ... }
    entry @{ ... }@
    action ..condition.. @{ ... }@
    action ..condition.. @{ ... }@
    exit @{ ... }@

  } where { ... }

  child_state_2 {
    port success ..condition..
    port error ..condition..

    parameterType { ... }
    resultType { ... }
    variableType { ... }
    entry @{ ... }@
    action ..condition.. @{ ... }@
    action ..condition.. @{ ... }@
    exit @{ ... }@

  } where { ... }

} where { ... }

Root states

A single .lf file contains a single root state. Its name must match the filename without the .lf suffix.

The grammar for a root state (i.e. for a complete .lf file) is given as follows:

<root-state> ::= <state-name> <state-block>

The rules for <state-name> and <state-block> will be defined in the next section.

States

A state is a named entity in a hierarchical state machine that can contain other states or barriers. It can be connected to sibling states via ports, and contain actions that are executed upon certain triggers.

In core model, the state holds a reference to a single child state or barrier which it treats as its "first" child, i.e. upon executing the state, this "first" child element gets activated. In .lf files, this attribute is not expressed at the parent state, but the "first" child element is marked by a --> arrow, marking it as the entry state.

A state can be a link state and reference a library, i.e. another state machine, which it links to. Such a link state cannot contain states, barriers, nor actions as these elements are inherited from the linked library. The only elements the link state can contain are ports without a condition that must also be present within the library.

<state> ::= <entry-symbol> <state-name> <state-block>
<link> ::= <entry-symbol> <state-name> "<-" <library-name> <link-block>
<dynamic-link> ::= <entry-symbol> <state-name> "<-" <value> <link-block>
<entry-symbol> ::= epsilon | "-->"
<parameter-value> ::= epsilon | "where" <value>

<state-block> ::= "{" <state-contents> "}" <parameter-value>
<state-contents> ::= <state-elem> *
<state-elem> ::=  <state> | <link> | <barrier> | <action> | <port> | <client-data> |
                  <parameter> | <variable> | <result>

<link-block> ::= "{" <link-contents> "}" <parameter-value>
<link-contents> ::= <link-elem> *
<link-elem> ::=  <link-port> | <client-data>

<state-name> ::= <identifier>
<library-name> ::= <identifier>
<identifier> ::= <alpha> <identifier-component>
<identifier-component> ::= <alpha-num> *
<alpha> ::= A-Za-z
<alpha-num> ::= <alpha> | 0-9 | "_"

Valid state or library identifiers start with a letter and are followed by any number of letters, numbers or underscore. Identifiers are case-sensitive.

The epsilon represents an empty symbol.

The rules for <barrier>, <action>, <port>, <link-port>, <parameter>, <variable>, <value>, <result> and <client-data> are given in the following sections.

Barriers

Barriers are child elements of states and represent either:

• a synchronization point where incoming port connections from multiple states can be merged onto a single destination state. Execution waits for all incoming ports to activate and transitions to the destination state. This is akin to a join operation in multi-threaded programs.

• a branching point where a single incoming port is mapped onto a number of destination states. In this case, execution starts the execution of the destination states in parallel. This is similar to a fork operation in multi-threaded programs. Barriers can also be entry nodes of the containing state, i.e. they are the first element to activate when the parent activates.

The grammar for barriers is defined as follows:

<barrier> ::= <entry-symbol> "barrier" <barrier-name> <barrier-block>
<barrier-name> ::= <identifier>

<barrier-block> ::= "{" <barrier-connections> "}"
<barrier-connections> ::= <barrier-connection> *
<barrier-connection> ::= "->" <state-name>

Actions

Actions are functions written in Lua that are executed based on trigger conditions during the execution of the state machines. Special cases are the entry and exit actions, which are executed upon entering and leaving a state, respectively. More general actions have an additional condition expression which must evaluate to true to be executed.

The grammar for actions is defined as follows:

<action> ::= <entry-action> | <exit-action> | <condition-action>
<entry-action> ::= 'entry' <script>
<exit-action> ::= 'exit' <script>
<condition-action> ::= 'action' <value> <script>
<script> ::= '@{' String '}@' | '"' EscapedString '"'

In this grammar and the following ones in this document, String represents any string, and EscapedString represents any string where quotes are escaped (\"). The <value> in the <condition-action> must evaluate to a <bool-value>.

Note

Actions are executed synchronously and should therefore not contain any long running computations, since this might block the execution of parallel branches. Any long running computation should be extracted to a separate service and integrated using an operation call.

Ports

Ports are named entities that allow the transition from the port's parent (the source state) to the port's destination (the destination state). A port also has a condition attached that must evaluate to true for the port (and thus the transition) to be activated. Ports are not necessarily connected to a destination state.

The grammar for ports is defined as follows:

<port> ::= "port" <port-name> <value> <connection>
<port-name> ::= <identifier>
<connection> ::= epsilon | "->" <destination-name>
<destination-name> ::= <state-name>

The <value> in the <condition-action> must evaluate to a <bool-value>.

Link ports

Libraries also can have ports, and instantiations of libraries ("link" states) inherit the library's ports such that they can be connected. As such, link ports are less complex since they do not contain the condition expression. The condition is already defined within the library.

The grammar for link ports is thus defined as follows, using the same rules as the regular port grammar:

<link-port> ::= "port" <port-name> <connection>

It is therefore possible to define a link port without connecting it to a destination state or barrier. In this case, the statement merely acts as an explicit statement that the linked library must provide the corresponding port <port-name>, however this is currently not checked when compiling the bundle.

Parameter, result and variable

States can have parameters, results and variables, which are simple or composite data structures representing a configuration, outcome or private data of a state, respectively. Parameters, results and variables are strongly typed. Parameters and results can be augmented with metadata for specifying default values, value ranges, units but also information about which widgets to use for allowing the user to specify them. Variables can be used to store state private data which is persistent even if a (child) state is deactivated.

The definition of parameters, results and variables is split into two aspects: types and values.

Parameter, result and variable types

A parameter/result/variable type can consist of the following entities:

• basic types

  • float: The float data type is a double precision 64-bit floating point.

  • int: The int data type is a 32-bit signed integer.

  • bool: The bool data type has two possible values: true and false.

  • string: The string data type represents character strings.

• array type: An array is a container holding a fixed or unbounded number of values of a single type.

• struct type: A struct is a container holding a set of named fields with potentially different types.

• state interface type: A state interface describes the public interface of a state, namely its ports, parameter type and result type. A state fulfills a state interface if both contain the same ports, and if all parameter fields and result fields are contained in the parameter fields and result fields of the interface, respectively.

• comments: everything from the '--' sign until the end of the line is considered a comment and will not be parsed.

The following grammar defines the structure of parameter/result/variable types:

<parameter> ::= "parameterType" <type>
<variable> ::= "variableType" <type>
<result> ::= "resultType" <type>
<type> ::= <base-type> | <array> | <struct> | <state-interface>
<base-type> ::= 'int' | 'float' | 'bool' | 'string'
<array> ::= '[]' <type> | '[' Integer ']' <type>
<field> ::= <type> <identifier> ';'
<fields> ::= <field> *
<struct> ::= '{' <fields> '}'
<state-interface> ::= '{' <state-interface-elem> <state-interface-contents> '}'
<state-interface-contents> ::= <state-interface-elem> *
<state-interface-elem> ::= <state-interface-port> | <parameter> | <result> |
                           "parameterType" "any" | "resultType" "any"
<state-interface-port> ::= 'port' <port-name>

The following example shows a simple parameter type that contains a pose matrix and linear and angular velocities:

{
  [4][4]float goal_pose;
  -- this is a comment
  {
    [3]float linear;
    [3]float angular;
  } velocities;
}

Here is another example containing two state interfaces:

{
  compute_goal_pose: {
    port done
    resultType {
      [4][4]float goal_pose;
    }
  };
  move_to_goal_pose: {
    port success
    port error
    parameterType {
      [4][4]float goal_pose;
    }
  };
}

Since both structs and state interfaces are enclosed with curly braces, state interfaces must contain at least one element to distinguish between an empty struct and an empty state interface. Specifying parameter and result type in a state interface is optional. Both default to the special any type, meaning all types will match. It is possible to explicitly write this as follows:

{
  port done
  parameterType any
  resultType any
}

This is equivalent to:

{
  port done
}

Parameter, result, variable values

In the preceding section, the grammar for parameter, result and variable types was given. The grammar for assigning values to these parameters is a separate aspect and defined as follows:

<value> ::= <int-value> | <float-value> | <string-value> | <bool-value> |
            <nil-value> | <array-value> | <struct-value> |
            <anonymous-state> | <exp> | "(" <value> ")"
<int-value> ::= Integer
<float-value> ::= Float
<string-value> ::= "'" String "'"
<bool-value> ::= "true" | "false"
<nil-value> ::= "nil"
<array-value> ::= "[" <elements> "]"
<struct-value> ::= "{" <field-values> "}"
<elements> ::= <value> | <value> "," <elements>
<field-values> ::= <field-value> *
<field-value> ::= <identifier> ":" <value> ";"
<anonymous-state> ::= <state-block>
<exp> ::= <fun-app> | <access-path> | <exp> "[" Integer "]"
<fun-app> ::= <access-path> "(" <elements> ")" | <access-path> "(" ")" |
              <unary-operator> <value> | <value> <binary-operator> <value> |
              "if" <value> "then" <value> "else" <value>
<unary-operator> ::= "not" | "#" | "-"
<binary-operator> ::= "and" | "or" | "*" | "/" | "%" | "+" | "-" |
                      "==" | "~=" | "<=" | ">=" | "<" | ">"
<access-path> ::= <identifier> "." <access-path> | <identifier>

See Built-in operators and functions for a list of available operators and functions and and their meaning.

An instantiation of the above parameter type follows as:

{
  goal_pose : [[1.0, 0.0, 0.0, 0.0],
               [0.0, 1.0, 0.0, 0.0],
               [0.0, 0.0, 1.0, 0.0],
               [0.0, 0.0, 0.0, 1.0]];
  velocities : { linear : [ 1.0, 0.0, 0.0 ]; angular : [ 0.0, 0.0, 0.0 ]; };
}

Note that omission of the "where" clause results in an empty parameter struct value.

The value for a state interface can be specified via a struct with exactly two fields { string state; any parameter; }, where state and parameter mean the same as <library-name> and <parameter-value> in links. E.g.

{
  state: "some_root_state";
  parameter: {
    a: "Hello";
    b: 42;
  };
}

references the root state "some_root_state" and sets a default value for its parameter value. A state reference must specify values for all parameter fields that are not contained in the parameter type of the state interface.

Client data

States can hold arbitrary client data in a key-value store. This allows for clients to store e.g. human-readable state names or the app's context menus. While client data is stored in the core, no semantics are attached to them, i.e. their interpretation resides fully client-side. It is possible to provide some extra data that you might want to use later using ElementAPI. Every key in clientData that is prefixed with X_ will be available in extraClientData property of model object with X_ prefix omitted. For example the following clientData block

clientData {
  X_myCustomProperty: "hello"
}

will look like this when accessed via ElementAPI

model: {
  extraClientData: {
    myCustomProperty: "hello"
  }
}

The grammar for client-data is defined as follows:

<client-data> ::= "clientData" "{" <client-data-block> "}"
<client-data-block> ::= <key-value> *
<key-value> ::= <key> ":" <value> ";"
<key> ::= <identifier>
<value> ::= '@{' String '}@' | '"' EscapedString '"'