Getting Started
There are three different ways to use Transitive:
- Using the hosted solution at transitiverobotics.com,
- self-hosting, or
- from source.
The first is by far the easiest and fastest to get started and it's the one we are describing here.
Start by . Once registered, you can start using Transitive Robotics by:
- Installing the agent,
- Installing a capability, and
- Embedding the capability in your own web application using the provided HTML snippet.
These steps are now explained in more detail.
Installing the agent
Once you have an account and are logged in, head to the . The fleet page shows you all your connected devices. Most of these will be robots but may also include other devices such as on-premise servers. To add devices to your account, find the curl command on that page and execute it on your device. We currently support devices running Ubuntu >=18.04 on amd64 or arm64.
Using the curl command installs the agent natively on a system running systemd. If you are using docker, please see Using Docker instead. There you will also learn how to pre-install the agent and desired capabilities in a docker image. Alternatively you can use the docker command provided after signing up to try it out in a ready-to-go image we provide.
The URL in the command contains your user id and your secret token. This token grants permission to connect to your account. While it is unlikely anyone would want to grant access to their robots to you by stealing your token and executing this command on their robots, you may still want to keep that token a secret.
The curl command fetches the install script from our servers and runs it. It installs the Transitive Robotics agent in ~/.transitive and adds a systemd user service to start it on boot. The agent is responsible for providing very basic status information about your device and for installing and starting capabilities. If you ever want to remove the agent, its services, and all capabilities it has installed, you can run the ~/.transitive/bin/uninstall.sh script.
Once the agent is installed you will see your device on your Fleet page.
The install script sets an ID for the device. This ID is generated from the sha256 sum of the id in /etc/machine-id, which is a unique id generated by systemd. If that file is empty, a random ID will be generated instead. If you prefer to set an ID of your own, you can do so by setting the TR_INSTALL_HASH environment variable before executing the curl command, or adding it to the bash environment, e.g., curl ... | TR_INSTALL_HASH=abc123 bash.
Installing a capability
Once the agent is installed on your device and you see it on the Fleet page you can install a first capability. For that head to your and select the device you want to add a capability on. Click on "Add Capabilities" and choose the capability you want to add. The agent running on the robot will then install that capability. Each capability runs in its own sandbox environment on the robot. Capabilities are started by the robot-agent but can keep running uninterrupted even if the robot-agent restarts.
Some users may wonder how Transitive Robotics handles dependencies given that the robot-agent is running as an ordinary user without sudo privileges. The answer is that the agent installs required Ubuntu packages that are not already found on the system locally in ~/.transitive, where they are shared between capabilities. Inside a capability's sandbox these local directories are overlayed on top of their corresponding system-paths to avoid making copies of already installed packages, using the same overlayfs mounts that docker uses.
Once the chosen capability is running, it will show up as "running" on the device page. If the capability provides a front-end component it will be shown on the device page as well. The display of the front-end component (also referred to as widget), is primarily for demonstration purposes. Their intended purpose is for embedding in your own robotic web applications, for which there are embedding instructions provided by each such widget.
Some of the capabilities available from Transitive Robotics rely on ROS and require you to configure a ROS version to use (e.g., noetic) and a ROS master to be running.
Embedding a capability's widget in your own web application
All front-end components shown on the device page come with embedding instructions. These instructions describe how the shown component can be embedded in other web application either using HTML:
<script src="URL-to-components-js-file"></script>
<name-of-the-capability id="YOUR-USER-ID" jwt="JWT" />
or React:
import { TransitiveCapability } from '@transitive-sdk/utils-web';
...
<TransitiveCapability jwt={JWT} />
Here JWT is a JSON Web Token signed with your JWT secret carrying a specific payload described in the embedding instructions of the capability. You can find your JWT secret on your . To get you started quickly the instructions also include snippets like the above with a pre-signed JWT token valid for a limited time. You can use that snippet for testing without having to worry about signing JWTs just yet. However, in production you will need to automatically generate these tokens. They are required to let Transitive Robotics know that a user of yours who is logged into the page where you embedded these snippets has your permission to use the respective capabilities.
Front-end components are packaged as Web Components, a technology that is supported by all modern browsers. Internally, many use React and will update when attributes change. Some also expose an imperative API. Please see the capabilities' descriptions for details.