Brooks PreciseFlex 400
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
| Item | Detail |
|---|---|
| Instrument | A PF400 with its Guidance Controller, bolted down and powered on, with the emergency stop within reach |
| Controller | IP address and basic settings set in the Brooks web interface. See the Guidance Controller documentation |
| Network | Ethernet from the GroundControl machine to the controller. The factory address is 192.168.0.1 |
| Connector | Brooks PreciseFlex 400 from the UniteLabs registry |
| Vendor software | None. The connector installs its own program on the controller |
| Machine | Windows, Linux, or macOS running GroundControl |
| Access | A tenant and the SDK installed. See Setup |
The GroundControl machine needs access to these ports on the controller:
| Port | Used for |
|---|---|
10100 | Commands to the arm |
10000 | Status reads, and stopping the arm while another command runs |
21 | FTP, to install the connector's program on the first start, after a connector update, or when another program answers |
80 | The web console, to start the program, and to write the startup settings when commissioning |
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:
- Copies the controller's parameter files to
/flash/unitelabs_backup_<timestamp>/. If the copy fails, the connector stops and changes nothing. - Writes the startup settings: GPL mode, autostart of the connector's program, homing at power-up, and motor power off at power-up.
- Saves the controller's whole parameter database to flash, its permanent storage, including calibration and joint limits.
- 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:
- Over FTP, delete
/flash/projects/unitelabs_tcp_server/on the controller. - Power-cycle the controller, so the program stops running.
- Set
commissiontotrueand 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
- In GroundControl, add a connector and pick Brooks PreciseFlex 400 (how to add a connector).
- Fill in the
deviceblock of the configuration. The fields that matter:Field Value hostThe controller's IP address, 192.168.0.1unless it was changedportThe command port, 10100. Change it only if the controller serves commands on another portstatus_portThe status port, 10000by default. Set to0to disable it. Without it, the connector uses the command port only, and blended paths run one leg at a timesimulationfalsefor the real arm. It'strueby default, which runs the connector's built-in simulator, so a fresh install never moves the armextended_reachtruefor an extended-reach (XR) arm,falsefor standard reach. The default istruerail_axisy, orxif the rail carriage is turned a quarter. Ignored without a railftp_userLeave empty unless someone added FTP credentials on the controller. Same for ftp_passwordboot_timeoutSeconds to wait for the controller after installing the program, 120by defaultprofilesMotion profiles to write into slots 1to20at startup. Leave empty to keep the controller's valuescommissionfalseby default. Set totruefor 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. - Start the connector. On the first start with
simulationset tofalse, 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. Withcommission: 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. - GroundControl then shows the modules
MovementController,JointMovementController,PathController,GripperController,SafetyController,InformationProvider,LightingController, andSimulationController. If the controller has Brooks' plate-handling option, GroundControl also showsTransportController, 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.
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 see | It means | Do this |
|---|---|---|
-1021 Robot not homed on every move | The controller was power-cycled, the program restarted, or the arm was stopped | Clear the gripper. Switch power on if it's off (update_power(active=True)), then await arm.movement_controller.home() |
-1009 latched fault | A collision or an emergency stop left a fault on the controller | Check 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 false | No arm answered at host | Check 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 digests | Another program answers on port 10100 | Read 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 connector | Someone is driving it from the Brooks web console | Close 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
- Robot arms: how UniteLabs represents an arm and its teachpoints.
- Teach positions: capture stations in the Teach view.
- Move a plate and Recover from a stop.
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