.. include:: alias.rst .. _usage: Ride cli commands ================= .. code-block:: bash 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 ```` to have the current command completed and press ```` twice to get a list of available options and commands. Pressing ```` twice is necessary if the available completion can not be disambiguated. For example, if you start typing ``ride ex`` bash and zsh will autocomplete this to ``ride execution ``. If you start typing ``ride log``, ride will not autocomplete, because both ``login``, ``logout`` and ``log`` would match. Only when pressing ```` 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 |cli| functionality you need to login, as |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: .. code-block:: bash $ ride login SERVER ``robot.franka.de`` is an example for a ``SERVER`` address. |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. .. code-block:: shell 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: .. code-block:: bash 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 .. code-block:: bash $ ride execution trace A sample trace could look like: .. code-block:: bash 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 .. code-block:: bash $ 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: .. code-block:: shell 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 `` 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. .. code-block:: shell $ ride bundle new BUNDLE_PATH Given a path like ``bundles/test`` this will create a structure similar to .. code-block:: shell . └── bundles └── test ├── manifest.json ├── sources │ └── test.lf └── resources Listing bundles ^^^^^^^^^^^^^^^ All currently uploaded bundles can be seen with .. code-block:: bash $ 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 |cli|. Will be deleted once the app development feature is removed from the robot. Compiling bundles ^^^^^^^^^^^^^^^^^ The compile command has the following form: .. code-block:: bash 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 `_in) a JSON format: .. code-block:: json { "name": "my_bundle", "version": "1.0", "dependencies": [], "globalComponents": [] } The ``sources`` folder contains state machines in the |lf| 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: .. code-block:: none $ 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. .. code-block:: json { "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. .. _deps: 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: .. code-block:: none . ├── 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: .. code-block:: shell $ 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: .. code-block:: bash $ 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: .. code-block:: bash 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 |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 ------------- .. code-block:: shell 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 .. code-block:: bash $ 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. .. code-block:: bash 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 .. code-block:: bash $ ride node list -t fe_lib_robot__move_contact results only in .. code-block:: bash 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 ---------------- |cli| allows you to get insight into the services that are currently connected to the |core|. .. code-block:: shell 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: .. code-block:: shell $ ride service list When the name of a service is appended, only information about that specific service is shown e.g.: .. code-block:: shell $ 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 ^^^^^^^^^^^^^^^^^^^^ |cli| also provides a tool to continuously print event values. Call .. code-block:: shell $ ride service echo SERVICE_NAME EVENT_NAME to print values for the given event. For example, you can use .. code-block:: shell $ ride service echo robot robot_state to publish the robot state values from the robot service. Log commands ------------ |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 .. code-block:: shell $ 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