7. Configuration¶
RAFCON can be configured using two config files, one for
the core and one for the GUI. The config files are automatically
generated (if not existing) on the first run of RAFCON. It is stored in
your home folder: ~/.config/rafcon/
with name config.yaml
and
gui_config.yaml
, respectively. The path can be changed when running
the start.py
script with argument “-c”. The syntax used is
YAML.
7.1. Core Configuration¶
Example:
A typical config file looks like this:
TYPE: SM_CONFIG
LIBRARY_PATHS: {
"generic": "${RAFCON_LIB_PATH}/generic",
"tutorials": "${RAFCON_LIB_PATH}/../examples/tutorials",
"ros": "${RAFCON_LIB_PATH}/../examples/libraries/ros_libraries",
"turtle_libraries": "${RAFCON_LIB_PATH}/../examples/libraries/turtle_libraries",
"intermediate_level": "${RAFCON_LIB_PATH}/../examples/functionality_examples"
}
LIBRARY_RECOVERY_MODE: False
LOAD_SM_WITH_CHECKS: True
STORAGE_PATH_WITH_STATE_NAME: True
MAX_LENGTH_FOR_STATE_NAME_IN_STORAGE_PATH: None
NO_PROGRAMMATIC_CHANGE_OF_LIBRARY_STATES_PERFORMED: False
IN_MEMORY_EXECUTION_HISTORY_ENABLE: True
FILE_SYSTEM_EXECUTION_HISTORY_ENABLE: True
EXECUTION_LOG_PATH: "%RAFCON_TEMP_PATH_BASE/execution_logs"
EXECUTION_LOG_SET_READ_AND_WRITABLE_FOR_ALL: False
SCRIPT_RECOMPILATION_ON_STATE_EXECUTION: True
Documentation:
In the following, all possible parameters are described, together with their default value:
- TYPE
- Type: String-constantDefault:
SM_CONFIG
Specifying the type of configuration. Must be SM_CONFIG for the core config file. - LIBRARY_PATHS
- Type: Dictionary with type(key) = String and type(value) = StringDefault:
{"generic": "${RAFCON_LIB_PATH}/generic"}
A dictionary holding all libraries accessible in RAFCON. The key of the dictionary is a unique library identifier. This unique identifier will be used as library name, shown as root of the library hierarchy in the library tree. The value of the dictionary is a relative or absolute path on the file system that is searched for libraries. Relative paths are assumed to be relative to the config file. Environment variables are also allowed. - LIBRARY_RECOVERY_MODE
- Type: booleanDefault:
False
If this flag is activated, state machine with consistency errors concerning their data ports can be loaded. Instead of raising exceptions only errors are printed. Invalid transitions and data-flows will just be removed. This mode can be used to fix erroneous state machines. Intermediate and expert users can also keep this setting enabled all the time. - LOAD_SM_WITH_CHECKS
- Type: booleanDefault:
True
If this flag is activated, every state is checked for consistency before loaded. If set to false all consistency checks will be skipped. This leads to much faster loading times. However, if there are consistency errors RAFCON tries to open the state machines and will fail. - STORAGE_PATH_WITH_STATE_NAME
- Type: booleanDefault:
True
If set to True the paths to save states will contain the state names. If False only the state IDs will be used to create the storage path. - MAX_LENGTH_FOR_STATE_NAME_IN_STORAGE_PATH
- Default:
None
Unit: numberSpecifies the maximum length of a state name in the storage path. If the state name is longer than the specified value, the state name is truncated. If the value is set to None the whole state name is used inside the path. - NO_PROGRAMMATIC_CHANGE_OF_LIBRARY_STATES_PERFORMED
- Type: booleanDefault:
False
Set this to True if you can make sure that the interface of library states is not programmatically changed anywhere inside your state machines. This will speed up loading of libraries. If you use template state machines that insert states during runtime, this must be disabled. - IN_MEMORY_EXECUTION_HISTORY_ENABLE
- Type: booleanDefault:
True
Enables execution history. The execution history is required for backward execution and execution logging to the file system. - FILE_SYSTEM_EXECUTION_HISTORY_ENABLE
- Type: booleanDefault:
True
Enables the logging of rafcon execution histories to the file system. Every time a statemachine is executed, a python shelve is created in the execution log directory, e.g./tmp/rafcon_execution_logs/rafcon_execution_log_99-Bottles-of-Beer_2017-08-31-16-07-17.shelve
. Some helpful utility functions for working with log files through python are in:import rafcon.utils.execution_log
. A tiny tiny code snippet which shows how to use the pandas.DataFrame representation to query the outcomes of a state named ‘CheckFinished’ is here:https://rmc-github.robotic.dlr.de/common/rafcon/pull/324#issuecomment-2520
- EXECUTION_LOG_PATH:
- Type: StringDefault:
"/tmp/"
Sets the target path of the execution logs - EXECUTION_LOG_SET_READ_AND_WRITABLE_FOR_ALL:
- Type: booleanDefault:
False
If True, the file permissions of the log file are set such that all users have read access to this file. - SCRIPT_RECOMPILATION_ON_STATE_EXECUTION:
- Type: booleanDefault:
True
If True, the script of anExecutionState
will be recompiled each time the state is executed, effectively resetting all global variables. For reasons of backwards compatibility, the default value isTrue
. It is recommended to set the value toFalse
, causing a recompilation only when the execution of a state machine is newly started, which is a bit faster and allows to share data between consecutive state executions.
7.2. GUI Configuration¶
A typical config file looks like this:
TYPE: GUI_CONFIG
SOURCE_EDITOR_STYLE: rafcon
GAPHAS_EDITOR_AUTO_FOCUS_OF_ROOT_STATE: True
ENABLE_CACHING: True
THEME_DARK_VARIANT: True
DRAG_N_DROP_WITH_FOCUS: False
WAYPOINT_SNAP_ANGLE: 45
WAYPOINT_SNAP_MAX_DIFF_ANGLE: 10
WAYPOINT_SNAP_MAX_DIFF_PIXEL: 50
PORT_SNAP_DISTANCE: 5
LOGGING_SHOW_VERBOSE: False
LOGGING_SHOW_DEBUG: False
LOGGING_SHOW_INFO: True
LOGGING_SHOW_WARNING: True
LOGGING_SHOW_ERROR: True
CONSOLE_FOLLOW_LOGGING: True
LIBRARY_TREE_PATH_HUMAN_READABLE: False
SUBSTITUTE_STATE_KEEPS_STATE_NAME: True
MINIMUM_SIZE_FOR_CONTENT: 30
MAX_VISIBLE_LIBRARY_HIERARCHY: 2
NO_FULLY_RECURSIVE_LIBRARY_MODEL: True
USE_ICONS_AS_TAB_LABELS: True
SHOW_NAMES_ON_DATA_FLOWS: True
SHOW_CONTENT_LIBRARY_NAME_TRANSPARENCY: 0.5
ROTATE_NAMES_ON_CONNECTIONS: False
HISTORY_ENABLED: True
KEEP_ONLY_STICKY_STATES_OPEN: True
AUTO_BACKUP_ENABLED: True
AUTO_BACKUP_ONLY_FIX_FORCED_INTERVAL: False
AUTO_BACKUP_FORCED_STORAGE_INTERVAL: 120
AUTO_BACKUP_DYNAMIC_STORAGE_INTERVAL: 20
AUTO_RECOVERY_CHECK: False
AUTO_RECOVERY_LOCK_ENABLED: False
SESSION_RESTORE_ENABLED: True
NUMBER_OF_RECENT_OPENED_STATE_MACHINES_STORED: 20
AUTO_APPLY_SOURCE_CODE_CHANGES: True
CHECK_PYTHON_FILES_WITH_PYLINT: False
DEFAULT_EXTERNAL_EDITOR:
PREFER_EXTERNAL_EDITOR: False
RESTORE_UNDOCKED_SIDEBARS: True
FULLSCREEN_SHOW_TOOLBAR: True
NOTIFICATIONS_MINIMUM_LOG_LEVEL: 30
NOTIFICATIONS_DURATION: 3
STATE_SELECTION_INSIDE_LIBRARY_STATE_ENABLED: True
LIBRARY_TREE_TOOLTIP_INCLUDES_ROOT_STATE_DESCRIPTION: True
ZOOM_WITH_CTRL: False
SEMANTIC_DATA_MODE: False
SHOW_PATH_NAMES_IN_EXECUTION_HISTORY: False
EXECUTION_TICKER_ENABLED: True
EXECUTION_TICKER_PATH_DEPTH: 3
# 300 is equal to glib.PRIORITY_LOW which is is lower than the default gtk priority
LOGGING_CONSOLE_GTK_PRIORITY: 300
SHORTCUTS:
abort: Escape
add: <Control>A
add_execution_state: <Alt>E
add_hierarchy_state:
- <Alt>H
- <Control><Shift>A
add_preemptive_state: <Alt>C
add_barrier_state: <Alt>B
add_output: <Alt>U
add_input: <Alt>N
add_outcome: <Alt>T
add_scoped_variable: <Alt>V
apply: <Control><Shift>E
backward_step: F9
close: <Control>W
copy: <Control>C
cut: <Control>X
data_flow_mode: <Control><Shift>D
delete: Delete
down:
- <Control>Down
- <Control><Shift>Down
fit: <Control>space
group: <Control>G
info: <Control>I
is_start_state:
- <Control>E
- <Control><Shift>X
transition_from_closest_sibling_state: <Control><Shift>C
transition_to_closest_sibling_state: <Control><Shift>V
transition_to_parent_state: <Control><Shift>B
left:
- <Control>Left
- <Control><Shift>Left
new: <Control>N
open: <Control>O
open_external_editor: <Control><Shift>Q
open_library_state_separately: <Control><Shift>space
paste: <Control>V
pause: F7
quit: <Control>Q
redo:
- <Control>Y
- <Control><Shift>Z
reload: <Shift>F5
rename: F2
right:
- <Control>Right
- <Control><Shift>Right
run_to_selected: <Control><Shift>R
save: <Control>S
save_as: <Control><Shift>S
save_as_copy: <Control><Shift><Alt>S
save_state_as: <Control><Alt>S
substitute_state: <Control><Shift><Alt>S
show_aborted_preempted: <Control>P
show_data_flows: <Control>D
show_data_values: <Control>L
start: F5
start_from_selected: <Control>R
step: F4
step_mode: F6
stop: F8
undo: <Control>Z
ungroup:
- <Control><Shift>G
- <Control>U
up:
- <Control>Up
- <Control><Shift>Up
fullscreen: F11
Documentation:
- TYPE
- Type: String-constantDefault:
GUI_CONFIG
Specifying the type of configuration. Must be GUI_CONFIG for the GUI config file. - SOURCE_EDITOR_STYLE
- Type: stringDefault:
rafcon
The gtk source view style used in the script editor. Note: You can download different styles here. The scripts have to be downloaded to <rafcon package directory>/share/gtksourceview-2.0/styles. “rafcon” is a style created to fit to the design of RAFCON. - GAPHAS_EDITOR_AUTO_FOCUS_OF_ROOT_STATE
- Type: booleanDefault:
True
If RAFCON is started with the Gaphas editor enabled this flag enables an initial auto focus of the root state after opening the state machine. If you do not like this feature simply disable it (False). - ENABLE_CACHING:
- Default:
True
Enables a accelerating caching feature. - THEME_DARK_VARIANT:
- Default:
True
IfTrue
, a dark theme will be used, else a light theme - PORT_SNAP_DISTANCE
- Default:
5
Unit: PixelMaximum distance to a port, at which the moved end of a connection is snapped to a port (outcome, input, output, scoped variable). - LOGGING_SHOW_VERBOSE
- Type: booleanDefault:
False
The flag decides to activate the VERBOSE log level in the logging console view. - LOGGING_SHOW_DEBUG
- Type: booleanDefault:
False
The flag decides to activate the DEBUG log level in the logging console view. - LOGGING_SHOW_INFO
- Type: booleanDefault:
True
The flag decides to activate the INFO log level in the logging console view. - LOGGING_SHOW_WARNING
- Type: booleanDefault:
True
The flag decides to activate the WARNING log level in the logging console view. - LOGGING_SHOW_ERROR
- Type: booleanDefault:
True
The flag decides to activate the ERROR log level in the logging console view. - CONSOLE_FOLLOW_LOGGING
- Type: booleanDefault:
True
The flag decides to activate the follow mode in the logging console view and to stay on the last printed logger message. - LIBRARY_TREE_PATH_HUMAN_READABLE
- Type: booleanDefault:
False
The flag is substituting underscores with spaces in the library tree. Thereby it is thought for people who do not like spaces in file system paths but don’t wanna have underscores in the library tree. - SUBSTITUTE_STATE_KEEPS_STATE_NAME
- Type: booleanDefault:
True
The flag describes the default behavior of the substitute state action concerning the previous state name and the state name after the substitution. In the dialogs this can be adapted for each single operation via a check box. If the flag is True the name is taken from the original state. If the flag is False the name is taken from the state machine that substitutes the original state. - MINIMUM_SIZE_FOR_CONTENT
- Default:
30
Unit: PixelMinimum side length (width and height) for container states to have their content (child states, transitions, etc.) shown. Currently only used in the old editor (OpenGL). - MAX_VISIBLE_LIBRARY_HIERARCHY
- Default:
2
Number of hierarchy levels to be shown within a library state. High values cause the GUI to lag. - NO_FULLY_RECURSIVE_LIBRARY_MODEL
- Type: booleanDefault:
True
If True, GUI models are only loaded up to the MAX_VISIBLE_LIBRARY_HIERARCHY. Setting this to False will drastically increase the time for loading a state machine. - USE_ICONS_AS_TAB_LABELS
- Type: booleanDefault:
True
If True, only icons will be shown in the tabs of the notebooks of the left and right pane. Otherwise the text of the notebook tab is shown as text. - SHOW_NAMES_ON_DATA_FLOWS
- Type: booleanDefault:
True
If False, data flow labels will not be shown (helpful if there are many data flows) - SHOW_CONTENT_LIBRARY_NAME_TRANSPARENCY
- Type: floatDefault:
0.5
Set to a value between 0 and 1. Defines the transparency of the name of a LibraryState in the graphical editor, of which the content is shown. - ROTATE_NAMES_ON_CONNECTIONS
- Type: booleanDefault:
False
If True, connection labels will be parallel to the connection. Otherwise, they are horizontally aligned. - HISTORY_ENABLED
- Type: booleanDefault:
True
If True, an edit history will be created, allowing for undo and redo operations. - KEEP_ONLY_STICKY_STATES_OPEN
- Type: booleanDefault:
True
If True, only the currently selected state and sticky states are open in the “states editor” on the right side. Thus, a newly selected state closes the old one. If False, all states remain open, if they are not actively closed. - AUTO_BACKUP_ENABLED
- Type: booleanDefault:
True
If True, the auto backup is enabled. I False, the auto-backup is disabled. - AUTO_BACKUP_ONLY_FIX_FORCED_INTERVAL
- Type: booleanDefault:
False
If True, the auto backup is performed according to a fixed time interval which is defined byAUTO_BACKUP_FORCED_STORAGE_INTERVAL
. If False, the auto-backup is performed dynamically according toAUTO_BACKUP_DYNAMIC_STORAGE_INTERVAL
. This means that RAFCON tries to avoid user disturbances by waiting for the case that the user does not perform any changes to the state machine forAUTO_BACKUP_DYNAMIC_STORAGE_INTERVAL
seconds. If this happens RAFCON will perform a backup. StillAUTO_BACKUP_FORCED_STORAGE_INTERVAL
is used as a hard storage interval. More information about this can be found on Auto Backup - AUTO_BACKUP_FORCED_STORAGE_INTERVAL
- Default: 120Unit: SecondsTime horizon for a forced auto-backup if
AUTO_BACKUP_ONLY_FIX_FORCED_INTERVAL
is True. - AUTO_BACKUP_DYNAMIC_STORAGE_INTERVAL
- Default: 20Unit: SecondsTime horizon after which the auto-backup is triggered if there was no modification to the state-machine for an time interval of this size. (only if
AUTO_BACKUP_ONLY_FIX_FORCED_INTERVAL
is False) - AUTO_RECOVERY_CHECK
- Default:
False
If True, the auto back module will check for backups of crashed RAFCON instances. This comfortable feature only can be used if the crashed instances or state machines were already created withAUTO_RECOVERY_LOCK_ENABLED
andAUTO_BACKUP_ENABLED
set to True. - AUTO_RECOVERY_LOCK_ENABLED:
- Default:
False
If True, the auto backup will put lock-files into the respective backup folder to label not correctly/cleanly closed state machines and instances. The auto recovery check is searching for these lock-files. - SESSION_RESTORE_ENABLED:
- Default:
True
If True the current session is stored into the runtime configuration and restored after restarting RAFCON. - NUMBER_OF_RECENT_OPENED_STATE_MACHINES_STORED:
- default: 20Maximum number of state machines that can be restored in a session.
- AUTO_APPLY_SOURCE_CODE_CHANGES
- Default:
True
If True, RAFCON will apply source code changes on saving a state machine. - CHECK_PYTHON_FILES_WITH_PYLINT
- Default:
False
If True, RAFCON checks the script file with pylint before saving it. In case of an error a message dialog will pop up to warn the user about the error. - DEFAULT_EXTERNAL_EDITOR
- Default: EmptyHolds the command for the editor to open the script.py file with, if the user clicks the ‘Open externally’ button in the source editor window. The command can be anything and results in a shell command with the following pattern: ‘<DEFAULT_EXTERNAL_EDITOR> script.py>’.
- PREFER_EXTERNAL_EDITOR
- Default:
False
If True, RAFCON will assume that the user always wants to work with a different editor than the internal one. If the ‘Open externally’ button is clicked, the source text is locked the whole time and a ‘Reload’ button reloads the saved file into RAFCON. If False, it is recommended to close the externally opened script.py everytime you are done editing. - RESTORE_UNDOCKED_SIDEBARS
- Default:
True
If True, RAFCON will restore undocked windows from the last RAFCON-instance run. - FULLSCREEN_SHOW_TOOLBAR
- Default:
True
If True, the toolbar with execution and state buttons is shown in fullscreen mode. - NOTIFICATIONS_MINIMUM_LOG_LEVEL
- Default:
30
Minimum log level of messages that shell show up in the notification bar.40
corresponds toERROR
,30
toWARNING
,20
toINFO
,10
toDEBUG
and5
toVERBOSE
. If this is set to a level higher than40
, no notifications are shown. - NOTIFICATIONS_DURATION: 3
- Default:
3
Number of seconds a notification is shown. If set to0
, the notification must be closed manually. - STATE_SELECTION_INSIDE_LIBRARY_STATE_ENABLED:
- Default:
True
If set to True, states inside library states can be selected. - LIBRARY_TREE_TOOLTIP_INCLUDES_ROOT_STATE_DESCRIPTION:
- Default:
True
If set to True, tooltip include the root state description text if the hovered library tree element (leaf element) is a real state machine. - ZOOM_WITH_CTRL:
- Default:
False
If set to True the user has to press the CTRL button to zoom into a state machine. - SEMANTIC_DATA_MODE
- Default:
False
If True, RAFCON gives the semantic data editor of each state more vertical space. The vertical space is taken from the port/connection widget. This is especially useful, when working a lot with semantic data. - SHOW_PATH_NAMES_IN_EXECUTION_HISTORY
- Default:
False
If True, RAFCON shows the state paths next to the state names in each execution history entry. - EXECUTION_TICKER_ENABLED
- Default:
True
If True, the execution ticker will prompt activity into respective widget. - EXECUTION_TICKER_PATH_DEPTH
- Default:
3
Number of state names shown in active path (by names) starting from the lowest leaf state as the last and cutting away the first and following if to much. - LOGGING_CONSOLE_GTK_PRIORITY:
- Default: 300Unit: PrioritySets the priority of logging anything to the console widget. The lower the number, the higher the priority. If the priority is too high, than the GUI will lag during execution, as the console widget will than slow down the rendering of gaphas / OpenGL
- SHORTCUTS
- Type: dictDefault: see example
gui_config.yaml
aboveDefines the shortcuts of the GUI. The key describes the action triggered by the shortcut, the value defines the shortcut(s). There can be more than one shortcut registered for one action. See GTK Documentation about more information about the shortcut parser. Not all actions are implemented, yet. Some actions are global within the GUI (such as ‘save’), some are widget dependent (such as ‘add’).
7.3. Environment variables¶
Next to the configuration files, a number of environment variables exist that allow for further configuration.
RAFCON_LOGGING_CONF
¶
RAFCON_LIBRARY_PATH
¶
An alternative option to specify your RAFCON libraries, which can e.g. be handy in combination with RMPM. See Option 2.
RAFCON_PLUGIN_PATH
¶
Use this variable to specify the RAFCON plugins that are to be loaded. See Plugin Interface.
RAFCON_START_MINIMIZED
¶
If the env variable RAFCON_START_MINIMIZED
is set (i.e., has a value which is not an empty string), RAFCON is
started minimized/iconified. This comes in handy, when the tests are run. You can then continue working, without
RAFCON windows repeatedly being opened and closed in the foreground.
7.4. Logging configuration¶
RAFCON uses the default Python logging
package for logging. Starting with version 0.9.7, logging handlers,
filters, formatting and more can be configured using a JSON file. The default configuration can be found in
source/rafcon/logging.conf
. The configuration can be overwritten with a custom JSON file. To do so, specify the
path to your configuration in the env variable RAFCON_LOGGING_CONF
. For information about the logging
package, please check the official documentation.
Example:
To not destroy the behavior of RAFCON, the default configuration should be used as basis for your extensions. The following example shows how to add another logging handler, writing all messages to a file:
{
"loggers": {
"rafcon": {
"handlers": ["stdout", "stderr", "loggingView", "file"]
}
},
"handlers": {
"file": {
"class": "logging.handlers.RotatingFileHandler",
"formatter": "default",
"filename": "/tmp/rafcon.log",
"maxBytes": 1024,
"backupCount": 3
}
},
}
7.5. Monitoring plugin configuration¶
The config file of the monitoring plugin contains all parameters and
settings for communication. It is additionally needed next to the
config.yaml
and the gui_config.yaml
to run the plugin. If it
does not exist, it will be automatically generated by the first start of
the start.py
and stored at ~/.config/rafcon
as
network_config.yaml
. The path of the used config file can be changed
by launching the start.py
script with argument “-nc”.
Example:
The default network_config.file
looks like:
TYPE: NETWORK_CONFIG
ENABLED: true
HASH_LENGTH: 8
HISTORY_LENGTH: 1000
MAX_TIME_WAITING_BETWEEN_CONNECTION_TRY_OUTS: 3.0
MAX_TIME_WAITING_FOR_ACKNOWLEDGEMENTS: 1.0
SALT_LENGTH: 6
SERVER: true
SERVER_IP: 127.0.0.1
SERVER_UDP_PORT: 9999
TIME_BETWEEN_BURSTS: 0.01
BURST_NUMBER: 1
CLIENT_UDP_PORT: 7777
Documentation:
- TYPE
- Type: stringDefault:
NETWORK_CONFIG
Specifying the type of configuration. Must be NETWORK_CONFIG for the network config file. - ENABLED
- Type: booleanDefault:
True
The monitoring plugin is only used if this value is set to True. - HASH_LENGTH
- Type: intDefault:
8
If you have many different message contents, increase this number. - HISTORY_LENGTH
- Type: intDefault:
1000
- MAX_TIME_WAITING_BETWEEN_CONNECTION_TRY_OUTS
- Type: floatDefault:
3.0
- MAX_TIME_WAITING_FOR_ACKNOWLEDGEMENTS
- Type: floatDefault:
1.0
Maximum waiting time for an acknowledgement after sending a message which expects one. - SALT_LENGHT
- Type: intDefault:
6
- SERVER
- Type: booleanDefault:
True
Defines if the RAFCON instance should start as server or client. IfFalse
process will start as client. - SERVER_IP
- Type: stringDefault:
127.0.0.1
If RAFCON is started as client, SERVER_IP contains the IP to connect to. - SERVER_UDP_PORT
- Type: intDefault:
9999
Contains the UDP port of the server which shall be connected to. - TIME_BETWEEN_BURSTS
- Type: floatDefault:
0.01
Time between burst messages (refer to BURST_NUMBER). - BURST_NUMBER
- Type: intDefault:
1
Amount of messages with the same content which shall be send to ensure the communication. - CLIENT_UDP_PORT
- Type: intDefault:
7777
Contains the UDP port of the client