Ride cli commands¶
Usage: ride [-c|--connection SERVER] [-i|--insecure] [--spoc-token]
[--spoc-force] [--spoc-timeout TIMEOUT] 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 acquisition.
--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)
execution Execution commands
service Service commands
log Logging commands
You can get a list of currently available commands, by using bash or zsh
tab-completion. Start typing a command and press <tab> to have the current
command completed and press <tab> twice to get a list of available options
and commands. Pressing <tab> twice is necessary if the available
completion can not be disambiguated.
For example, if you start typing ride ex<tab> bash and zsh will
autocomplete this to ride execution ``. If you start typing
``ride log<tab>, ride will not autocomplete, because both
login, logout and log would match. Only when pressing <tab> again
login, logout and log will be printed as the list of available
commands. Most commands, options and parameters of the ride cli support
tab-completion, but some of them might require you to login first.
Login commands¶
Before using other ride-cli functionality you need to login, as ride-cli requires proper credentials to communicate with the robot. 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 an example for a SERVER address. ride-cli can
connect through the shop-floor network and the port at the robot'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 access to the
robot, you can execute the ride logout command.
Execution commands¶
The execution group of commands manages state machine execution by starting and stopping state machines 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 state machine¶
After writing and uploading a state machine, or creating a task, it can be started using the execution start command:
Usage: ride execution start [-t|--trace] PATH [ARGUMENT]
Start execution of a state machine, optionally with tracing.
Available options:
-h,--help Show this help text
-t,--trace After starting also trace its execution
PATH State machine path to start
ARGUMENT State machine arguments, e.g. '{ foo: 123; }'
Tasks are state machines as well and can therefore be started the same way. You
can detect tasks in the output of ride node list through the 0_ prefix.
Specify ARGUMENT if your state machine requires certain parameter.
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 [STOPPED]
Execution (10) of 0_wait [RUNNING]
0_wait.timeline_body.wait.skill.wait_execution.wait_library [ACTIVE]
Execution (10) of 0_wait [FINISHED]
Execution [STOPPED]
This is a trace of running a "wait" app, 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.
Bundle commands¶
Commands for working with bundles are grouped together under the bundle subcommand. A bundle is a collection of state machines and resources.
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 you're successfully logged in to the robot.
If you are using a different network configuration, append the -c <SERVER>
parameter to your commands. This is useful if you for example temporarily use
the shop floor to connect to the robot instead of the robot network. It will
use the stored credentials to connect to the set SERVER.
Create a new bundle¶
This will create the directory structure for a new, empty bundle.
$ ride bundle new BUNDLE_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. There are two types of bundles:
CloudBundle: Downloaded and installed from the Franka World.
LocalBundle: Installed through ride-cli. Will be deleted once the app development feature is removed from the robot.
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]
with DIR as the path to the bundle directory, containing the manifest.json.
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, dependencies and global context menu components (see `Parameter
Modification <context_menu.html#global-components>`_in) a JSON format:
{
"name": "my_bundle",
"version": "1.0",
"dependencies": [],
"globalComponents": []
}
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.
To create the structure you could use the above described
ride bundle new BUNDLE_PATH command.
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!
Handling dependencies¶
Oftentimes, you want to utilize state machines from other bundles, either ones you wrote yourself or from bundles written by other developers. How exactly you can use state machines from other bundles in your state machine is described later in more detail in the chapter LF file format. ride tries to assist you as much as possible with finding and fixing missing dependencies.
When you are using a state machine from another bundle you have to declare the
bundle dependency in your manifest. Let's assume that our test bundle uses some
functionality from the pick bundle. Oftentimes, it is enough to just use a
dependency and let ride fix the manifest for you:
$ ride bundle compile bundles/test
~/statemachines/bundles/test/manifest.json: ERROR
Missing or undeclared dependencies: pick
Try these "dependencies": ["pick"] or use --fix-manifest.
ExitFailure 1
$ ride compile bundles/test --fix-manifest
The fixed manifest will then contain the bundle our test bundle depends on.
Now ride happily compiles our test bundle again. However, this works only when
the state machine you reference to is in the same folder as the bundle you
compile.
{
"name": "test",
"version": "1.0",
"dependencies": ["pick"]
}
Warning
Your code should not depend on system bundles. You can recognize those by their common prefix
fe_system. These are only intended for internal use.
There is one edge case which has to be considered by developers and is not covered by RIDE.
If a bundle uses a resource from another bundle (e.g. pick) and an SVG file is specified in the
clientData.icon markup that bundle needs to be added manually to the dependencies section
in the manifest. RIDE will not check if this dependency exists. Using this bundle on a robot
where the dependency is missing will result in an HTML/JS error when using the Bundle in Desk.
Dependency resolution¶
Sometimes you get an error about missing dependencies, where RIDE does not offer
the --fix-manifest option. This is because RIDE is unable to find the dependent
bundle. By default RIDE will look through the parent folder of your bundle to
resolve the bundles you depend on. Let's assume our workspace layout looks like this:
.
├── bundles
│ └── test
│ ├── manifest.json
│ ├── sources
│ │ └── Test.lf
│ └── resources
└── dependencies
├── pick
└── ...
When we now try to compile the test bundle again, we will get an error message
saying, that the pick dependency could not be resolved. This is because we
explicitly have to tell where RIDE can find this dependency with
the -B option:
$ ride bundle compile bundles/test -B dependencies/pick
Note
You can use multiple -B options to specify multiple paths for different dependencies.
However you can also specify the workspace directory (e.g. -B dependencies/) to search
recursively through all bundles.
Now our test bundle should compile nicely and can be installed on the robot.
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 FILE
You will get warnings associated to the installed bundle. If you want to get
all warnings of all bundles, use the -a|--all-warnings option.
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 to the Franka 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 ride bundle list
command. You can remove bundles installed through the Franka World
(CloudBundle) as well as bundles installed through ride-cli (LocalBundle).
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 state machines¶
All currently uploaded root nodes can be gathered through
$ ride node list
This list shows all state machines available on the robot, including both your
own state machines as well as internal system state machines. Tasks on the
robot are also listed and can be detected by the prefix 0_.
Using -t or --tree will show all nodes with their child nodes, without
following linked states.
Nodes at path []:
├── 0_my_test_task
│ └── timeline_body
│ └── test_move
│ └── skill
...
├── fe_lib_robot__move
│ ├── check_empty_motion
│ ├── fe_lib_robot__convert_timeline_parameters
│ ├── move_cart
│ ├── move_joint
│ └── process_poses
├── fe_lib_robot__move_contact
│ ├── check_error
│ ├── motion
│ ├── move
│ └── stop_at_contact_change
...
By adding a path, only the subtree after the path will be shown, i.e calling
$ ride node list -t fe_lib_robot__move_contact
results only in
Nodes at path ["fe_lib_robot__move_contact"]:
├── check_error
├── motion
├── move
└── stop_at_contact_change
Note
This command is especially useful to find the correct name of a state machine
to use for the ride execution start and ride execution 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 e.g.:
$ ride service list opcua
Service opcua
...
Operation readIntMap
Request: { }
Result: []{ string key; int value; }
Error: string
Operation readIntMapKeys
Request: { }
Result: []string
Error: string
Operation readPose
Request: { string key; float timeout; }
Result: [16]float
Error: string
Operation readPoseMap
Request: { }
Result: []{ string key; [16]float value; }
Error: string
...
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.
Log commands¶
ride-cli is able to relay log messages from the core. This is useful to display print messages of your apps. In order to display the log messages from the core, simply call
$ ride log
[ INFO] 09:55:24.351 UTC: Idle stopped
[ INFO] 09:55:28.444 UTC: Example print from app
[ INFO] 09:55:31.518 UTC: Timeline: { error_cause: nil }
...
Note
By default this command will omit dates (but not times) from the output. If
you need also the dates simply use the --with-date switch