TrialONE
Request Pilot Access

Get started

Quickstart

From an approved account to your first issue.

You need an approved TrialONE account, Python 3.10 or newer and a recording to analyse. File analysis runs on Linux, Windows or macOS without a ROS installation. Watching a live ROS 2 graph also needs a working ROS 2 environment, rclpy and the message packages used by your robot.

1. Request Pilot Access

TrialONE is available to approved pilot teams. Request Pilot Access with the email you will sign in with. You can sign in with Google or GitHub before the approval arrives; the app opens as soon as it does.

2. Install the command line tool

TrialONE is not on public PyPI. It comes from our own package index, and your CLI key is the password. Create one under Settings, CLI keys and put it into the command; the same key signs this machine in afterwards.

Terminal
$ pip install --index-url https://trialone:<your-cli-key>@trialone.dev/api/pypi/simple --extra-index-url https://pypi.org/simple trialone

For a microcontroller on a serial port (Arduino, ESP32), add the serial extra: "trialone[serial]" instead of trialone. If pip asks for a username and password, any username works and the CLI key is the password.

3. Sign in on this machine

Terminal
$ trialone login

It shows a one-time code and opens trialone.dev/cli-login when you press Enter. Enter the code there while you are signed in to the app and approve it. On a robot over SSH, open that page on your laptop instead.

The terminal receives its own key, checked before it is saved, and trialone whoami shows which account it is connected to. Each machine gets its own key: revoking one under Settings, CLI keys leaves the others working. Scripts can pass a key from there directly: trialone login <key>.

4. Diagnose a recording

Terminal
$ trialone diagnose ./recording.mcap --machine amr-01 --symptom "The robot stops when it enters the loading area"

The terminal shows a summary and writes the full report and diagnosis JSON to output/. When signed in, it also sends the run to your workspace and prints its link. The report shows the finding, supporting measurements, proposed action and what still needs checking. Exit code 0 means analysis completed; it does not mean the robot is healthy.

Give the investigation useful context:

  • --symptom <text>: describe what you saw, rather than a guess about the cause. This helps the investigation focus on your incident instead of an unrelated warning.
  • --machine <name>: use the same name for every recording from this robot, especially when analysing several robots on one laptop.
  • --healthy <recording>: another recording of the same robot that you know ran well. Without one, TrialONE can only compare a recording with itself, and a fault that lasts the whole recording then looks normal.
  • --project <folder>: the relevant source checkout, including parameter, launch and URDF files. It gives the investigation code and configuration context; a precise file or line is included when the available evidence supports one.
Terminal
$ trialone diagnose ./today.mcap --machine amr-01 --symptom "Stops in the loading area" --healthy ./last-good.mcap --project ./robot_ws/src --json ./diagnosis.json

5. Check the repair

After applying the change, repeat the scenario and make a fresh recording. Use the same healthy reference so both recordings are measured on the same basis:

Terminal
$ trialone verify ./diagnosis.json ./after-repair.mcap --healthy ./last-good.mcap --json ./verification.json

The result is pass, fail or inconclusive, with the findings that disappeared, remained or appeared. It checks the supplied scenario; it is not a general guarantee that the robot cannot fail.

Choose where data is processed

Detection runs on the machine where you start the CLI. Model interpretation is enabled when a model is configured, subject to your plan or provider. --no-explain skips model interpretation. --no-push skips the workspace upload, but does not disable model calls. See Data and model processing before using sensitive recordings.

Next steps

Something missing or wrong here? Tell us.