Darp.Fairino 0.9.0

Darp.Fairino

Darp.Fairino is a modern async .NET SDK for Fairino robot controllers. It provides typed command helpers, realtime-state feedback, dependency injection registration, and a Result<..., FairinoError> failure model for controller and transport errors.

The minimum supported Fairino robot software is v4.0.1, which added the filter time and joint gains of servo motion.

Install

dotnet add package Darp.Fairino

The package currently targets net10.0.

Quick Start

using Darp.Fairino;
using Darp.Fairino.DependencyInjection;
using Darp.Results;
using Microsoft.Extensions.DependencyInjection;

var services = new ServiceCollection();
services.AddFairinoRobot();

await using ServiceProvider provider = services.BuildServiceProvider();
await using FairinoRobot robot = provider.GetRequiredService<FairinoRobot>();

// The realtime states are fixed for the life of the connection; pass null for a command-only connection.
var realtimeStates = new FairinoRobotStateConfiguration(
    [FairinoRobotStates.JointCurPos, FairinoRobotStates.MotionDone],
    TimeSpan.FromMilliseconds(8));

Result<Success, FairinoError> connectResult = await robot.ConnectAsync("192.168.58.2", realtimeStates);
if (connectResult.TryGetError(out FairinoError? connectError))
{
    Console.WriteLine($"Connection failed: {connectError.Message}");
    return;
}

Result<SoftwareVersion, FairinoError> versionResult = await robot.GetSoftwareVersionAsync();
if (versionResult.TryGetValue(out SoftwareVersion version, out FairinoError? versionError))
{
    Console.WriteLine($"Robot model: {version.RobotModel}");
    Console.WriteLine($"Web version: {version.WebVersion}");
    Console.WriteLine($"Controller version: {version.ControllerVersion}");
}
else
{
    Console.WriteLine($"Version query failed: {versionError.Message}");
}

await robot.DisconnectAsync();

Only connect to a reachable controller on a trusted local network.

Geometry and units

Motion and kinematics methods use JointPos and Aardvark transforms:

The SDK follows Fairino's controller coordinate definitions. It converts to the controller's millimetres and degrees when sending commands and converts responses back. GetActualJointPosAsync replaces GetActualJointPosDegreeAsync. Optional pose offsets accept null for identity.

using Aardvark.Base;

var result = await robot.GetActualTcpPoseAsync();
if (result.TryGetValue(out Euclidean3d pose, out var error))
    Console.WriteLine($"TCP in metres: {pose.Trans}");

External-axis coordinates, force/torque records, scalar motion options and raw telemetry arrays retain their documented controller units.

Local kinematics

The package embeds a URDF for each supported robot model, for use with Darp.Kinematics. GetDhCompensationAsync reads the calibration of the connected robot, which converts to the DH offset table that Darp.Kinematics expects:

using Darp.Kinematics;

DhCompensation compensation = (await robot.GetDhCompensationAsync()).Unwrap();
IKinematics kinematics = SerialKinematics.ParseEmbeddedUrdf(
    typeof(FairinoRobot).Assembly,
    "Darp.Fairino.Models.fr5_v6.urdf",
    "base_link",
    "flange",
    compensation
);

The local model calculates the pose of the flange. The controller calculates the pose of the active TCP, so multiply with GetTcpOffsetAsync to compare the two.

Configuration

FairinoRobotOptions holds the command timeout and the controller ports. Transport internals such as the reconnect policy are managed by the SDK.

services.AddFairinoRobot(options =>
{
    options.CommandTimeout = TimeSpan.FromSeconds(30);
    options.StatePort = 20005;
});

API Shape

The Fairino C# SDK manual can be used as a reference for available controller operations. In Darp.Fairino, methods are async and use an Async suffix.

A command the SDK has no method for can be sent raw. Its arguments and response values are RpcValues: numbers, booleans, text, JointPos, Euclidean3d, ExaxisPos and ForceTorque convert implicitly, and geometry is sent in the controller's units. The last argument reads the result from the response values; FairinoParsers has readers for common results.

Result<Euclidean3d, FairinoError> offset = await robot.SendCommandAsync(
    "GetTCPOffset",
    [0],
    FairinoParsers.CreatePose,
    cancellationToken);

Without a reader, SendCommandAsync returns the response values. A command that takes all its values as one array takes a single RpcValue.Flat(...) argument.

Failure Model

SDK operations return operational failures as Result<..., FairinoError>. This includes robot error codes, network failures, protocol errors, timeouts, and not-connected states.

Caller cancellation throws OperationCanceledException, and invalid arguments throw the usual .NET argument exceptions.

Connection State

FairinoRobot.ConnectionState describes the realtime-state connection, which is the only persistent connection to the controller. A lost connection is recovered automatically until DisconnectAsync is called, and the realtime states passed to ConnectAsync are re-applied before the state returns to Connected. Changing the realtime states means disconnecting and connecting again.

using IDisposable subscription = robot
    .WhenConnectionStateChanged()
    .Subscribe(state => Console.WriteLine($"Robot connection: {state}"));

While the connection is being recovered, state reads fail with FairinoErrorMessages.NotConnected, and a state read that was already waiting fails with FairinoErrorMessages.ConnectionLost.

XML-RPC commands and UDP commands do not use this connection. They are neither rejected nor cancelled during a recovery, and a UDP command such as ServoJAsync still reports success. The SDK cannot tell a network interruption from a controller restart, so re-check the robot after a recovery and restart a servo session if one was active.

Testing

Darp.Fairino.Testing provides FakeFairinoController, an in-memory controller that a real FairinoRobot connects to. It records what the robot sends and answers every command with success, also a command of your own; a test says what a command returns and which realtime states arrive. Tests need neither a robot nor a simulator:

var controller = new FakeFairinoController();
await using FairinoRobot robot = await controller.ConnectRobotAsync();

await robot.SetDOAsync(id: 3, status: 1, smooth: 0, block: 0);
// controller.Commands is [new FakeCommand("SetDO", [3, 1, 0, 0])]

controller.AnswerNext("GetSysVarValue", FakeResponse.Values(12.5));
// (await robot.GetSysVarValueAsync(1)) is 12.5

Build

dotnet restore Darp.Fairino.slnx
dotnet build Darp.Fairino.slnx --no-restore
dotnet pack src/Darp.Fairino/Darp.Fairino.csproj --no-build

License

This project is licensed under the Apache License 2.0. See LICENSE.