Getting Started

Installation

First, install the required dependencies:

sudo apt install libsodium18

Then you can install the debian package you were provided with:

sudo dpkg -i ride-cli_*.deb

This will place the ride executable in /usr/bin. Execute:

ride --help

to see the available commands.

Compiling a Simple Bundle

Your workspace should be structured similar to this:

.
└── bundles
  ├── test
  │   ├── manifest.json
  │   ├── sources
  │   │  └── Test.lf
  │   └── resources
  └── pick

The bundle test can simply be created by using:

ride bundle new bundles/test

Here, test and pick constitute bundles. They each contain a manifest.json file, which indicates the name, the version and the dependencies (on other bundles) of the bundle. Next to this, sources and resources folders are created. The sources folder holds your source files (i.e. all .lf files), the resources folder holds app resources like icons.

Let's compile the test bundle:

ride bundle compile bundles/test

This will create a test.bundle file next to the test bundle directory.

Note

You can specify the path of the resulting bundle file with the -o argument

Installing a Bundle

To get a bundle onto the robot, you should first login:

ride login SERVER

Then you can upload the bundle to the robot by installing it:

ride bundle install test.bundle

Handling Dependencies

Oftentimes, you want to utilize state machines from the common bundles or other developers (including yourself). 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. The ride CLI 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 compile our test bundle again.

{
  "name": "test",
  "version": "1.0",
  "dependencies": ["pick"]
}

Note

You don't need to specify the following builtin dependencies:

  • base

  • cartesian_motion

  • common

  • common-robot

  • haptic_common

  • joint_motion

  • no-gripper

  • gripper

  • cobot-pump

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.

Compiling with Make

Another way to compile and install your bundle(s) is to use make. You can download a Makefile here. Put it next to bundles and then, from outside of the bundles directory, simply use make to compile and install your bundles on the robot. There are several

make
make install

There exist several different make targets depending on your need:

  • make bundles will compile all bundles within the bundles folder (default)

  • make bundle-X will compile only the bundle named X and put the result into build/X.bundle

  • make install will upload all build/*.bundle s to the robot

  • make install-X will compile and upload the bundle named X

If you get warnings about missing dependencies during make, add the bundle directory containing the missing dependency, similarly as described above.

make DEPS="-B ee-gripper"

Warning

If you omit the DEPS=... to make, RIDE will build your bundles with --ignore-dependencies by default. However you should always specify the folder to missing dependencies such as the gripper if you can!