UniteLabs

Move a plate with the PF400

A script that reads the PF400's teachpoints from the Platform and moves a plate from one station to another.

This script picks up a plate at station A1 and puts it down at B1, using the teachpoints you captured in the Teach view. Each move is one call: the arm goes in through the station's safe point and approach, grips or releases at the nest, and backs out the same way.

You need unitelabs-sdk 0.18.0 or later (installation), the PF400 connector running, and both stations taught (Teach positions). The script runs the same against the connector in simulation mode.

This script moves the arm. If the arm isn't homed, the script homes it first, which is a large move to the home sensors. The arm then follows exactly the route you taught. Between stations it keeps moving through each safe point and cuts the corners slightly, more at higher speed. Check that the arm's path is clear, and run a new route on the Validation tab or in simulation first.
move_a_plate.py
import asyncio

from unitelabs.sdk import AsyncApiClient

ARM = "Brooks PreciseFlex 400"  # the arm's name on the Devices page
SOURCE, DESTINATION = "A1", "B1"  # stations taught in the Teach view

SETTLE = 0  # 10% of rated speed, stops on each point
BLEND = -4  # 25% of rated speed, carries its speed through each point

PLATE = dict(width=127.76, grip_speed=20.0)  # SBS plate, landscape; % of the gripper's top speed
GRIP_FORCE = 5.0  # N


async def main():
    client = AsyncApiClient()
    device_id, arm = await find_arm(client, ARM)
    points, stations, safe_points = await load_teachpoints(client, device_id)

    # Plan both moves first, so a wrong station name fails before the arm moves
    pick = plan(points, stations, safe_points, SOURCE)
    place = plan(points, stations, safe_points, DESTINATION, coming_from=SOURCE)

    if not (await read_state(arm))["Homed"]:
        await arm.movement_controller.home()

    rail = await arm.information_provider.get_rail_installed()
    suffix = "_with_rail" if rail else ""
    pick_up = getattr(arm.transport_controller, "pick_up_joints" + suffix)
    put_down = getattr(arm.transport_controller, "put_down_joints" + suffix)

    await pick_up(**pick, **PLATE, force=GRIP_FORCE)
    await put_down(**place, **PLATE)
    print(f"Plate moved from {SOURCE} to {DESTINATION}")


def plan(points, stations, safe_points, station, coming_from=None):
    """The arguments for one pick-up or put-down at a station."""
    nest, approach, *way_out = stations[station]  # way_out: transitions, then safe point
    way_in = way_out[::-1]
    if coming_from:
        start = stations[coming_from][-1]
        way_in = between(safe_points, start, way_out[-1]) + way_in
    return dict(
        approach_path=[points[name] for name in way_in],
        approach_path_profile=BLEND,
        approach=points[approach],
        approach_profile=SETTLE,
        target=points[nest],
        target_profile=SETTLE,
        retract=points[approach],
        retract_profile=SETTLE,
        retract_path=[points[name] for name in way_out],
        retract_path_profile=BLEND,
    )


def between(safe_points, start, end):
    """The shared safe points the arm passes from one station's safe point to another's."""
    i, j = safe_points.index(start), safe_points.index(end)
    return safe_points[i + 1 : j] if i < j else safe_points[j + 1 : i][::-1]


async def load_teachpoints(client, device_id):
    """Joint values by point name, each station's points in order, and the shared safe points."""
    found = (await client.list_teach_points(device_id, auto=True)).items
    names = {point.id: point.name for point in found}
    # The connector expects capitalized axis names: "Column", not "column"
    points = {
        point.name: {axis.capitalize(): float(v) for axis, v in point.joints.items()}
        for point in found
    }

    stations, safe_points = {}, []
    for group in (await client.list_teach_groups(device_id, auto=True)).items:
        members = sorted(group.members, key=lambda member: member.position)
        path = [names[member.teach_point_id] for member in members]
        if group.kind == "NEST":  # nest, approach, transitions, safe point
            stations[group.name.removeprefix("NEST_")] = path
        elif group.kind == "SAFE":
            safe_points = path

    # On a rail, the arm passes the safe points in their order along the rail
    if safe_points and all("Rail" in points[name] for name in safe_points):
        safe_points.sort(key=lambda name: points[name]["Rail"])
    return points, stations, safe_points


async def find_arm(client, name):
    """The arm's device ID, for its teachpoints, and its connector, to move it."""
    devices = (await client.list_devices(name=name)).items
    if not devices:
        raise RuntimeError(f"No device named {name!r}")
    services = await client.get(f"/devices/{devices[0].id}/services")
    if not services:
        raise RuntimeError(f"{name!r} has no connector")
    return devices[0].id, await client.get_service(services[0]["id"])


async def read_state(arm):
    """Powered, homed, and idle? The stream opens with an empty event."""
    states = await arm.information_provider.subscribe_state()
    async with states:
        async for state in states:
            if "Homed" in state:
                return state
    raise RuntimeError("The state stream closed without a state")


asyncio.run(main())

Run it with uv run move_a_plate.py. Set ARM to the arm's name as the Devices page shows it, and SOURCE and DESTINATION to your station names.

What the script does

It reads the teachpoints from the UniteLabs Platform on every run, so a re-taught point is used the next time the script runs.

To get from one station to the next, the arm travels along the safe spine, through the safe points between them. On an arm with a rail, they're ordered along the rail. Without a rail, they follow the order you captured them in.

The script uses two built-in speed settings, called motion profiles. SETTLE (10% of full speed) stops exactly on each point. It's used going into and out of a nest, so the gripper closes and opens with the arm still. BLEND (25%) keeps the arm moving through each point. It's used between safe points and transitions.

To pin a workflow to one set of points, export them and change load_teachpoints() to read the file instead of the Platform. Its teachPoints and teachGroups lists hold the same fields as the API.

Next steps

Last updated