Ride cli Commands

Usage: ride [-c|--connection SERVER] [-i|--insecure] COMMAND

Available options:
  -v,--version             Show version
  -h,--help                Show this help text
  -c,--connection SERVER   Base URL for the API.
  -i,--insecure            Ignore all TLS errors and treat them as warnings.
  --spoc-token             Acquire control token without asking the user.
  --spoc-force             Force control token acquisision.
  --spoc-timeout TIMEOUT   Maximum seconds to wait for execution token.

Available commands:
  login                    Log in
  logout                   Log out
  bundle                   Bundle commands (default: list)
  node                     Node Commands (default: list)
  cli                      App programming tool for Franka Emika robots.
  execution                Execution commands
  service                  Service commands

Login commands

Before using other ride-cli functionality you need to login, as ride-cli requires proper credentials to communicate with the core. The user account is the same as the one created for use with Desk.

To log in, execute the following:

ride login SERVER

robot.franka.de is the default SERVER address. ride-cli can also connect both through the shop-floor network and the port at Panda's base.

You will be prompted for your username and password. If the credentials are correct, a session will be created. Once you no longer need robot access, you can execute the ride logout command.

Execution commands

The execution group of commands manages statemachine execution by starting and stopping statemachines and by tracing the execution state.

Usage: ride execution COMMAND
  Execution commands

Available options:
  -h,--help                Show this help text

Available commands:
  start                    Start execution of a state machine, optionally with
                          tracing.
  stop                     Stop the current execution.
  trace                    Trace execution of a state machine.

Starting a statemachine

After writing and uploading a statemachine, or creating a task, it can be started by calling

ride execution start [state machine or task name]

In order to trace the specified execution, start can directly be called with a trace flag:

ride execution start [state machine or task name] --trace

If a Work Execution Wait Time is specified, a countdown will start and be displayed. The execution can be aborted during the countdown by pressing CTRL+C.

If the --trace option is enabled, stopping a running task or state machine is also possible by pressing CTRL+C.

Tracing the execution progress

If an execution is already running, the execution trace can be inspected by calling

ride execution trace

A sample trace could look like:

Execution state:
idle_statemachine: [active]
idle_statemachine.error: [inactive]
idle_statemachine.monitor_gripper: [inactive]
idle_statemachine.set_thresholds: [inactive]
idle_statemachine.set_pilot_colors: [inactive]
idle_statemachine.parallel: [inactive]
idle_statemachine.wait_until_no_emergency: [active]
idle_statemachine.monitor_zerog: [inactive]
idle_statemachine.loop_pilot_colors: [inactive]

This is a trace from the idle-statemachine, it shows the activation of each state along the path of active states and is updated every time the activation changes.

Stopping the execution

In order to stop any execution currently running, one can simply call

ride execution stop

An idle state machine will start as soon as a state machine is stopped. In that case, ride cli stop has to be called a second time to stop the idle state machine.

Bundle commands

Commands for working with bundles, that is collections of state machines, are group together under the bundle subcommand.

ride bundle --help command lists all available bundle commands:

Usage: ride bundle [COMMAND]
  Bundle commands (default: list)

Available options:
  -h,--help                Show this help text

Available commands:
  list                     List bundles
  install                  Install bundles on a robot
  compile                  Compile a single bundle
  publish                  Compile and sign a single bundle
  remove                   Remove a bundle
  new                      Create a new bundle
  info                     Introspect a bundle archive

All commands shown here assume that successfully logged in onto the robot. If you are using a different network configuration, append the -c <ADDRESS> parameter to your commands.

Create a new bundle

This will create the directory structure for a new, empty bundle.

ride bundle new PATH

Given a path like bundles/test this will create a structure similar to

.
└── bundles
  └── test
      ├── manifest.json
      ├── sources
      │  └── test.lf
      └── resources

Listing bundles

All currently uploaded bundles can be seen with

ride bundle list

or by simply executing ride bundle.

Installing bundles

If you created, or were provided with a bundle as a .bundle file, you can upload it to the robot using:

ride bundle install BUNDLE

Compiling bundles

The compile command has the following form:

ride bundle compile DIR [-o|--output FILE] [-B|--bundle-dir DIRECTORY]
                        [--ignore-dependencies] [--fix-manifest] [--verbose]

A basic bundle is a folder containing:

• manifest file

• sources directory

• resources directory

The manifest.json file encodes the bundle's meta information such as its name, version and dependencies in a JSON format:

{
  "name": "my_bundle",
  "version": "1.0",
  "dependencies": []
}

The sources folder contains state machines in the Lingua Franka format, as described by chapter LF File Format. The resources folder contains any additional files, such as icons and images.

Note

If your state machines depend on states outside of the currently compiled bundle, you can append the path to the bundle containing those states using the --bundle-dir parameter. Make sure to also add these bundles to your manifest!

Publishing bundles

To publish your bundle to Franka World you need to sign it using your private key and your app developer certificate. This works similarly to how you compiled your bundle, but you add the paths to KEY and CERT. The following command will create a signed bundle, which you can upload in the World:

ride bundle publish DIR [-o|--output FILE] [-B|--bundle-dir DIRECTORY]
                    KEY CERT [--verbose]

Removing bundles

You can remove a bundle by executing ride bundle remove BUNDLE_NAME. If you are not sure about the name of your bundle, use the list command.

Showing bundle information

The ride bundle info command lists the following information about a compiled bundle in a .bundle file:

• The bundle's name

• Version of the bundle

• The list of contained apps and their icons

• The list of other bundles on which this bundle depends

The information is presented in JSON format.

Node commands

Usage: ride node [COMMAND | [-t|--tree] [PATH]]
  Node commands (default: list)

Available options:
  -h,--help                Show this help text
  -t,--tree                List nodes at path and their children recursively as
                          tree.
  PATH                     Path of the (sub) nodes to list, separated by periods
                          (e.g. 0_timeline.timeline_body).

Available commands:
  list                     List root nodes

Listing statemachines

All currently uploaded nodes can be seen with

ride node list

Using -t or --tree will show all nodes with their child nodes, without following linked states.

|── error_handling_statemachine
|   |── error
|   |── finish
|   |── interaction
|   |   |── decrease_gripper_width
|   |   |── decrease_gripper_width_haptic
|   |   |── ignore
|   |   |── increase_gripper_width
|   |   |── increase_gripper_width_haptic
|   |   |── menus
|   |   |   |── haptic_interaction_menu
|   |   |   |── menus
|   |   |   |── pilot_interaction_menu
|   |   |── safety
|   |── user_input
|   |── wait_until_no_emergency
|   |── zeroG
|── idle_statemachine
|   |── error
|   |── loop_pilot_colors
|   |── monitor_gripper
|   |── monitor_zerog
|   |── parallel
|   |── set_pilot_colors
|   |── set_thresholds
|   |── wait_until_no_emergency
|── wait
|   |── play_tic_sounds

By adding a path, only the subtree after the path will be shown, i.e calling

ride node list -t idle_statemachine

results only in

|── error
|── loop_pilot_colors
|── monitor_gripper
|── monitor_zerog
|── parallel
|── set_pilot_colors
|── set_thresholds
|── wait_until_no_emergency

Note

This command is especially useful to find the correct name of a statemachine to use for the start and stop calls.

Service commands

ride-cli allows you to get insight into the services that are currently connected to the core.

Usage: ride service COMMAND
  Service commands

Available options:
  -h,--help                Show this help text

Available commands:
  list                     List connected services
  echo                     Echo events of a service

Listing connected services

To list all connected services call:

ride service list

When the name of a service is appended, only information about that specific service is shown.

With -o and -e you can optionally choose to only list operations or events respectively.

Echoing event values

ride-cli also provides a tool to continuously print event values. Call

ride service echo SERVICE_NAME EVENT_NAME

to print values for the given event. For example, you can use

ride service echo robot robot_state

to publish the robot state values from the robot service.

cli commands

The cli group of commands allows for interacting with the core. It can be used to print service events from the core.

Logging core output

In order to display the log messages from the core, one can simply call

ride cli log