Running BeTFSM

Executing a state machine is done using a Runner. This Runner iteratively executes the state machine at a fixed frequency and returns when the state machine gives an outcome not equal to TICKING.

Most of the parameters are defined by RunnerBase. The actual runners inherit from this base class and implement the environment related aspects such as timing, scheduling etc. There are currently two runners Runner only depends on a pure Python environment, and ROSRunner depends on a ROS2 environment and allow to use BeTFSM to implement a proper ROS2 node.

Besides their constructor arguments, all the runners will interpret command line arguments that allow all users to further configure the execution. Using the --help command line argument you can get a full list:

usage: example_runner.py [-h] [--frequency FREQUENCY]
                         [--publish_frequency PUBLISH_FREQUENCY]
                         [--debug | --no-debug]
                         [--display_active | --no-display_active]
                         [--betfsm_log BETFSM_LOG] [--name-filter NAME_FILTER]
                         [--generate_dot GENERATE_DOT]
                         [--generate_json GENERATE_JSON]
                         [--serve | --no-serve] [--host HOST] [--port PORT]
                         [--workers WORKERS]
                         [--log-level {critical,error,warning,info,debug,trace}]

BeTFSMRunnerGUI command line options

options:
  -h, --help            show this help message and exit

BeTFSMRunnerGUI Options:
  --frequency FREQUENCY
                        frequency at which BeTFSM runs [default:100.0]
  --publish_frequency PUBLISH_FREQUENCY
                        publishing frequency for GUI [default:5 ]
  --debug, --no-debug   Log statistics of the timing of each tick at
                        publish_frequency [default: False] (default: False)
  --display_active, --no-display_active
                        Log the active nodes at rate equal to
                        publish_frequency, only logs changes to
                        activity[default: False] (default: False)
  --betfsm_log BETFSM_LOG
                        BeTFSM Log specification string, i.e. a list of
                        categories separated with ':'. Known categories are
                        {'state', 'default', 'service', 'unknown'} but there
                        can be user-defined categories [default: 'None']
  --name-filter NAME_FILTER
                        specifies a comma-separated list of naes (can be
                        regular expressions) to filter out.[default: ''
  --generate_dot GENERATE_DOT
                        generate a graphviz .dot file from the state machine
                        and store in the specified file (and quit the program
                        without running)
  --generate_json GENERATE_JSON
                        generate a json file from the state machine and store
                        in the specified file (and quit the program without
                        running)
  --serve, --no-serve   Start-up server with graphical user interface
                        [default:True] (default: True)

Uvicorn Web Server Options:
  --host HOST           Bind socket to this host [default: 0.0.0.0]
  --port PORT           Bind socket to this port [default: 8000]
  --workers WORKERS     Number of worker processes[default: 1]
  --log-level {critical,error,warning,info,debug,trace}
                        log-level of the web-server [default: info ]

You can still pass ROS2 arguments according to ROS2 conventions: e.g. adding :
"--ros-args --log-level debug" to your arguments

You can also use the command-line arguments not to execute, but to generate a .dot file, in GraphViz format, or to generate a .json file that can be used for further analysis of the BeTFSM-tree. Currently the .json format does not contain enough information to reconstruct the BeTFSM tree.

RunnerBase

`betfsm.RunnerBase`

`init(statemachine, blackboard, frequency=100.0, publish_frequency=10, debug=False, display_active=False, betfsm_log=None, select_name='', type_filter='', allow_generate_dot=True, allow_generate_sm_dot=True, allow_generate_json=True, serve=True, host='0.0.0.0', port=8000, workers=1, log_level='info')`

Initializes the BeTFSMRunner. This BeTFSMRunner has no other dependencies and runs in the main thread. The parameters frequency, publish_frequency, debug, display_active, and serve can be overridden by command-line parameters. Use "--help" to show all command-line parameters.

Parameters:

statemachine (TickingState) –

the TickingStateMachine to be run
blackboard (Blackboard) –

the blackboard to be used
frequency (float, default: 100.0 ) –

frequency at which the statemachine is ticked, in Hz [default=100Hz]
publish_frequency (float, default: 10 ) –

frequency at which to publish to the webbrowser [default= 10Hz]
debug (bool, default: False ) –

If true outputs debug info on console each tick. [default=False]
display_active (bool, default: False ) –

displays all active nodes on log at publish_frequency. Only if activity changed!
betfsm_log (str, default: None ) –

A list of categories, separated by ':' that will be logged, known categories are default, state, service,... But users and libraries can add their own.
select_name (str, default: '' ) –

specifies the name to start with while using generate-dot or generate-sm-dot. Ignored for generate-json or the graphical visualization.
type_filter (str, default: '' ) –

comma-separated list of typrs of nodes that are not descended into in the graphical user interface or generate-dot
allow_generate_dot (bool, default: True ) –

adds the generate_dot command-line parameter. [default: True]
allow_generate_sm_dot (bool, default: True ) –

adds the generate_sm_dot command-line parameter. [default: True]
allow_generate_json (bool, default: True ) –

adds the generate_json command-line parameter. [default: True]
serve (bool, default: True ) –

A : {active} starts webserver if True [default: True]
host (str, default: '0.0.0.0' ) –

the host IP of the network interface to bind to. Default=0.0.0.0. Typical values are: - 127.0.0.1 for only local acces and high security, for local development or production behind reverse proxy. - localhost usually 127.0.0.1 - 0.0.0.0 for anyone who knows your IP, lower security, for Docker, VM's or public access - 192.168.x.x for only your local network
port (int, default: 8000 ) –

bind socket of server to this port, default=8000
workers (int, default: 1 ) –

number of worker processes, default=1
log_level (str, default: 'info' ) –

log-level of the web-server (not BeTFSM), default = "info" choices are "critical", "error", "warning", "info", "debug", "trace"

`parse_arguments(parser, group_app, group_uvr)`

Parses the arguments from the command-line. This function could further add parameters to the parser if necessary.

Runner

`betfsm.Runner`

Bases: RunnerBase

Runner for a BeTFSM ticking state machine. Initializes the BeTFSMRunner. This BeTFSMRunner has no other dependencies and runs in the main thread. You typically call this class in the main body of your program.

This is multi-threaded, only access member variables using the methods designed for this. (i.e. set_outcome, get_outcome)

`run()`

Runs the statemachine until it returns an outcome different from TICKING

Refers to absolute time to avoid drifting. Uses monotonic clock to avoid problems with system time changes.

Returns:	`int` – the final outcome of the statemachine

ROSRunner

`betfsm_ros.ROSRunner`