.. include:: alias.rst

Getting started
===============

Installation
------------

On Windows using WSL (Windows Subsystem for Linux)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

At present, we do not offer a |cli| executable that directly runs on Windows. Alternatively, you
can leverage the built-in WSL (Windows Subsystem for Linux) feature. You can activate and install
Ubuntu on Windows 10 or 11 by following the official `Ubuntu tutorial
<https://ubuntu.com/tutorials/install-ubuntu-on-wsl2-on-windows-11-with-gui-support>`_. We
recommend that you install Ubuntu 22.04 for this purpose. Once you have done this, you will have
a setup like the one shown below:

.. image:: _static/ride-on-wsl.png

Now that you have installed Ubuntu on your Windows system through WSL, the next step is to install
|cli|. To do this, please follow the instructions provided in the next section. We recommend using
the :ref:`debian-package-instructions` installation instructions.

On Ubuntu systems
^^^^^^^^^^^^^^^^^

The latest version of |cli| can be downloaded from the `Franka World Resources page
<https://franka.world/resources>`_. There are two different methods to configure |cli| on your
system.

.. _debian-package-instructions:

|cli| Debian package
++++++++++++++++++++

The recommended method to use |cli| is to use the Debian packages created for different Ubuntu
versions. Before continuing make sure that you have installed the required dependencies:

.. code-block:: bash

    sudo apt install libsodium-dev libssl-dev libgmp-dev zlib1g

To check which Ubuntu version you are running on, execute ``lsb_release -a``. Then select
the correct |cli| Debian package and install it e.g. for Ubuntu 22.04 like the following:

.. parsed-literal::

    sudo dpkg -i ride-cli\_\ |version|\ -1_jammy_amd64.deb

|cli| is now ready to be used. To check if the installation worked, you can enter:

.. parsed-literal::

    ride --version
    |version|

To see the available commands enter:

.. code-block:: bash

    ride --help

|cli| AppImage
++++++++++++++

The |cli| `AppImage <https://appimage.org/>`_ already includes all required libraries and can be
used on any Linux based system out-of-the-box. This method does not require sudo rights on the
system! The AppImage can be used as follows:

.. parsed-literal::

    ./ride-\ |version|\ -x86_64-jammy.AppImage login robot.franka.de

More information on possibilities to store the AppImage on your system can be found
`here <https://docs.appimage.org/user-guide/faq.html#question-where-do-i-store-my-appimages>`_.

.. _creating_simple_bundle:

Creating a simple bundle
------------------------

Now we will create our first bundle, containing a state machine that simply
prints "Hello World!".

All state machines are installed as part of bundles. The bundle in this chapter
will be called ``tutorial``:

.. code-block:: shell

  $ ride bundle new bundles/tutorial

This will create the following folder structure and two text files:

.. code-block:: none

  .
  └── bundles
    └── tutorial
        ├── manifest.json
        ├── migrations
        ├── resources
        └── sources
            └── Tutorial.lf

The ``manifest.json`` file indicates the name, the version and the dependencies
of a bundle. When installing a bundle on a robot which already has a bundle
with the same name, it will only be updated if the version is the same or newer.

The ``Tutorial.lf`` file will contain the code we create in this tutorial. Let
us start by creating a single state which will print a message to the log.

.. code-block:: lf

  Tutorial {
    port Success true
    entry @{
      printf("Hello World!")
    }@
  }

This creates a root state ``Tutorial``. The root must always have the same name
as the file it is contained in. Our state has one exit port called ``Success``.
After the port's name we put a condition, which defines when the execution
should exit through that port. In this case, the condition is simply ``true``,
so it will immediately exit successfully.

Finally, we attach a Lua script block (between ``@{...}@``) onto the ``entry``
action. Whenever the ``Tutorial`` state is entered, a "Hello World!" message
will be printed to the |core| log.

Compiling our bundle
^^^^^^^^^^^^^^^^^^^^

Next we have to compile our bundle.

.. code-block:: shell

  $ ride bundle compile bundles/tutorial

This will produce our Tutorial bundle `tutorial.bundle` in the `bundles`
folder which we can install on the robot.

Installing the bundle
^^^^^^^^^^^^^^^^^^^^^

To install our tutorial bundle, you must first log-in using:

.. code-block:: shell

  $ ride login SERVER

``SERVER`` is the same address you would use to connect to Desk, like
``robot.franka.de``.

.. note::

   When connecting through the shop floor or with the ip address of the robot
   make sure to ignore all TLS errors and treat them as warnings using the `-i`
   option, e.g.: `ride -i login SERVER`

.. code-block:: shell

  $ ride bundle install bundles/tutorial.bundle

You should be able now to see the ``tutorial`` bundle listed when using:

.. code-block:: shell

  $ ride bundle list

This will list you all installed bundle as well as the way how it got installed.
``CloudBundle`` indicates that is was received trough the Franka World.
``LocalBundle`` indicates that it got installed through |cli|.

Running our state machine
^^^^^^^^^^^^^^^^^^^^^^^^^

Now we can start our new state machine.

The message "Hello World!" will be printed in the |core| log. To see it we
can run ``ride log`` in a separate terminal

.. code-block:: shell

  $ ride log -l -d

Then we start our newly installed state machine with:

.. code-block:: shell

  $ ride execution start -t Tutorial

Where ``-t`` stands for tracing. You should obtain an output similar to this
one:

.. code-block:: shell

  $ ride execution start -t Tutorial
  Waiting for 5 seconds to initiate motion, press CTRL-C to abort
  Waiting for 4 seconds to initiate motion, press CTRL-C to abort
  Waiting for 3 seconds to initiate motion, press CTRL-C to abort
  Waiting for 2 seconds to initiate motion, press CTRL-C to abort
  Waiting for 1 seconds to initiate motion, press CTRL-C to abort
  Execution (25) of Tutorial [FINISHED]
  Tutorial [RESULT]:
  { error_cause: nil; }

You should see "Hello World!" printed in the log:

.. code-block:: shell

  $ ride log -l -d
  [ INFO] 2022-08-30 12:02:49.451 UTC core.evaluation.script: Hello World!
