UniteLabs
Reference

Brooks PreciseFlex 400

Get a Brooks PreciseFlex 400 robot arm connected through GroundControl, with the connector installing its own controller software, and confirm the connection from Python.

This page gets you from a mounted PF400 to a first state and position reading from Python, without moving the arm. The Brooks manuals cover mounting, wiring, and safety. To teach positions and move plates, see the PF400 guides.

This page applies to connector version 0.5.0 or later. If you use an older version, update the connector before you continue.

What you need

ItemDetail
InstrumentA PF400 with its Guidance Controller, bolted down and powered on, with the emergency stop within reach
ControllerIP address and basic settings set in the Brooks web interface. See the Guidance Controller documentation
NetworkEthernet from the GroundControl machine to the controller. The factory address is 192.168.0.1
ConnectorBrooks PreciseFlex 400 from the UniteLabs registry
Vendor softwareNone. The connector installs its own program on the controller
MachineWindows, Linux, or macOS running GroundControl
AccessA tenant and the SDK installed. See Setup

The GroundControl machine needs access to these ports on the controller:

PortUsed for
10100Commands to the arm
10000Status reads, and stopping the arm while another command runs
21FTP, to install the connector's program on the first start, after a connector update, or when another program answers
80The web console, to start the program, and to write the startup settings when commissioning
Drive the arm from one client at a time. Stop the connector in GroundControl before you move the arm from the Brooks web console, and close the console before you start the connector again.

The controller program

The Guidance Controller is the control unit that drives the arm's motors. It runs programs written in Guidance Programming Language (GPL), Brooks' programming language. The connector installs its own GPL program on the controller, in /flash/projects/unitelabs_tcp_server/, and sends the arm's commands through it.

If the controller runs another program, for example from Brooks or an integrator, the connector stops and unloads it, then starts its own. Other projects stay on the controller.

Commissioning

By default, the connector installs and starts its program but leaves the controller's startup settings as they are. After a power cycle, restart the connector to start the program again.

Commissioning sets the controller to start the connector's program at every power-up. Motor power stays off at power-up, so switch it on and home the arm before the first move.

Before you commission, note the current startup settings and the name of the startup project in the web console. You need them to roll back.

To commission, set commission to true before the connector's first start on the controller. On that start, the connector:

  1. Copies the controller's parameter files to /flash/unitelabs_backup_<timestamp>/. If the copy fails, the connector stops and changes nothing.
  2. Writes the startup settings: GPL mode, autostart of the connector's program, homing at power-up, and motor power off at power-up.
  3. Saves the controller's whole parameter database to flash, its permanent storage, including calibration and joint limits.
  4. Starts the program, switches motor power on, and homes the arm. The arm moves.

After commissioning, set commission back to false. If you leave it on, deleting the program's folder later commissions the controller again.

Commissioning only runs if the program isn't on the controller yet. To commission a controller the connector already started with commission set to false:

  1. Over FTP, delete /flash/projects/unitelabs_tcp_server/ on the controller.
  2. Power-cycle the controller, so the program stops running.
  3. Set commission to true and restart the connector.

To roll back, copy the files from the backup folder to /flash/config/ and reboot the controller without saving. You can also disable motor power, set the old project and values again, and save them to flash.

Install and configure the connector

  1. In GroundControl, add a connector and pick Brooks PreciseFlex 400 (how to add a connector).
  2. Fill in the device block of the configuration. The fields that matter:
    FieldValue
    hostThe controller's IP address, 192.168.0.1 unless it was changed
    portThe command port, 10100. Change it only if the controller serves commands on another port
    status_portThe status port, 10000 by default. Set to 0 to disable it. Without it, the connector uses the command port only, and blended paths run one leg at a time
    simulationfalse for the real arm. It's true by default, which runs the connector's built-in simulator, so a fresh install never moves the arm
    extended_reachtrue for an extended-reach (XR) arm, false for standard reach. The default is true
    rail_axisy, or x if the rail carriage is turned a quarter. Ignored without a rail
    ftp_userLeave empty unless someone added FTP credentials on the controller. Same for ftp_password
    boot_timeoutSeconds to wait for the controller after installing the program, 120 by default
    profilesMotion profiles to write into slots 1 to 20 at startup. Leave empty to keep the controller's values
    commissionfalse by default. Set to true for the first start on a controller. See Commissioning

    The connector reads from the controller whether a rail is installed, so there's no setting for it.
  3. Start the connector. On the first start with simulation set to false, it installs its program on the controller, checks that the program answering is the one it installed, and switches motor power on. This takes up to two minutes. With commission: true, it also writes the startup settings and homes the arm, so the arm moves. Later starts use the installed program, and reinstall it after a connector update.
  4. GroundControl then shows the modules MovementController, JointMovementController, PathController, GripperController, SafetyController, InformationProvider, LightingController, and SimulationController. If the controller has Brooks' plate-handling option, GroundControl also shows TransportController, which the pick-up and put-down commands need.

After every connector start, the arm reports Homed as false. Home it before the first move.

To install the program by hand, for example on a site that blocks FTP, set auto_deploy to false and ask UniteLabs support for the project files.

Try it without an arm

With simulation left at true, the connector answers like a PF400: moves take time and finish, the gripper grasps, and it reports plate handling. Set simulate_rail to true to add a rail.

The simulator checks targets against the arm extended_reach describes, so set it as you would for the real arm. Every script on this page and in the PF400 guides runs against the simulator.

To switch between the simulator and the real arm, change simulation and restart the connector. A restart also installs the program when needed. The SimulationController module switches without installing it, and its switch to the real arm fails while another program runs on the controller.

First connection test

The script reads what the controller reports about itself, then the arm's state and joint positions. Run it with the SDK authenticated (Connect to Platform), using the connector's name from GroundControl.

first_connection.py
import asyncio

from unitelabs.sdk import AsyncApiClient

ARM = "Brooks PreciseFlex 400"  # the connector's name in GroundControl


async def first(subscription, key):
    """The first value that carries `key`. Streams open with an empty event."""
    async with subscription:
        async for value in subscription:
            if key in value:
                return value
    raise RuntimeError("The stream closed without a value")


async def main():
    client = AsyncApiClient()
    arm = await client.get_service_by_name(name=ARM)
    info = arm.information_provider

    print("Model:", await info.get_model())
    print("Firmware:", await info.get_firmware_version())
    rail = await info.get_rail_installed()
    print("Rail:", rail)
    print("Plate handling:", await info.get_plate_handling_supported())

    print("State:", await first(await info.subscribe_state(), "Homed"))
    suffix = "_with_rail" if rail else ""
    stream = getattr(
        arm.joint_movement_controller, "subscribe_joint_positions" + suffix
    )
    print("Joints:", await first(await stream(), "Column"))


asyncio.run(main())

Run it with uv run first_connection.py. On a real arm it prints something like:

Model: PreciseFlex 400
Firmware: TCP Command Server 3.0D2 06-28-2024, ..., PARobot Module 3.0C2 07-11-2023, ...
Rail: False
Plate handling: True
State: {'Status': 'IDLE', 'Enabled': True, 'Homed': True}
Joints: {'Column': 502.27, 'Shoulder': 26.389, 'Elbow': 181.844, 'Wrist': -207.677, 'Gripper': 126.12}

With a rail, Joints also carries Rail. The pick-up and put-down commands need Plate handling to be True. If it's False, contact UniteLabs support.

Known quirks and errors

You seeIt meansDo this
-1021 Robot not homed on every moveThe controller was power-cycled, the program restarted, or the arm was stoppedClear the gripper. Switch power on if it's off (update_power(active=True)), then await arm.movement_controller.home()
-1009 latched faultA collision or an emergency stop left a fault on the controllerCheck the cell and the gripper, then recover (Recover from a stop). Recovery re-homes the arm, so it moves
The connector doesn't start with simulation set to falseNo arm answered at hostCheck the cable, the address, and the ports above. With simulation set to false, the connector only starts once the arm answers
-2805 Unknown command, or an error naming two digestsAnother program answers on port 10100Read The controller program, then restart the connector. A fresh start stops the other program and starts its own
The arm doesn't respond to the connectorSomeone is driving it from the Brooks web consoleClose the console. Drive the arm from one client at a time

After a move, a stop, or a recovery, Homed can take a few seconds to update.

Next steps

Vendor documentation

Mounting, power, the controller's own settings, and safety are covered by the Brooks PreciseFlex 400 manual and the Guidance Controller documentation shipped with the arm.

Last updated