.. include:: alias.rst .. _usage: Ride cli Commands ================= .. code-block:: bash 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 |cli| functionality you need to login, as |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: .. code-block:: bash ride login SERVER ``robot.franka.de`` is the default ``SERVER`` address. |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. .. 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 statemachine ^^^^^^^^^^^^^^^^^^^^^^^ After writing and uploading a statemachine, or creating a task, it can be started by calling .. code-block:: bash ride execution start [state machine or task name] In order to trace the specified execution, start can directly be called with a ``trace flag``: .. code-block:: bash 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 .. code-block:: bash ride execution trace A sample trace could look like: .. code-block:: bash 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 .. code-block:: bash 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: .. 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 successfully logged in onto the robot. If you are using a different network configuration, append the ``-c
`` parameter to your commands. Create a new bundle ^^^^^^^^^^^^^^^^^^^ This will create the directory structure for a new, empty bundle. .. code-block:: shell ride bundle new 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``. 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 BUNDLE 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] 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: .. code-block:: json { "name": "my_bundle", "version": "1.0", "dependencies": [] } 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. .. 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: .. 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 ``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 ------------- .. 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 statemachines ^^^^^^^^^^^^^^^^^^^^^ All currently uploaded nodes can be seen with .. code-block:: bash ride node list Using ``-t`` or ``--tree`` will show all nodes with their child nodes, without following linked states. .. code-block:: bash |── 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 .. code-block:: bash ride node list -t idle_statemachine results only in .. code-block:: bash |── 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 ---------------- |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. 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. 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 .. code-block:: bash ride cli log