.. 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 ``<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 |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
    format                   Format lingua franka

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.

.. 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
        ├── migrations
        ├── resources
        └── sources
          └── Test.lf

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
  * migrations 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:

.. 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 <lf_file_format.html>`_. The ``resources`` folder
contains any additional files, such as icons and images. The ``migrations``
folder contains scripts which perform migrations of state machines, more
information can be found in chapter `state machine migrations <migrations.html>`_.

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
<lf_file_format.html#states>`_. `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
  |     ├── migrations
  │     └── 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.

When installing bundles, all tasks will potentially be migrated. To see the logs
of the migration scripts, use the ``-m|--migrations-logs`` option.

Publishing bundles
^^^^^^^^^^^^^^^^^^

To publish your bundle to `Franka World <https://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.

Formatting LF files
^^^^^^^^^^^^^^^^^^^

You can format one or multiple LF files by executing ``ride bundle format PATH...``,
where ``PATH`` is a path to a single LF file or a folder containing
LF files. If no paths are specified stdin will be read.

.. note::

   The formatter might not correctly deal with all variants for commenting LF
   source code. It is recommended to always add comments above the
   corresponding line.

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
