PreciseFlex Arm Driver

[miikee]

Untested Driver

This adds:

• ArmBackend base class
• PreciseFlexBackend
• TCP(IOBase) class
• Arm front end class

Docs haven't been updated yet.
There's a warning included in the PreciseFlexBackend docstring that it's untested.

[rickwierenga]

when gripping a plate using pick_plate, I get this:

  An axis has been commanded to accelerate too quickly or move too fast and does not have the power to perform the operation.  If necessary, this can be confirmed by datalogging the "Compensator output torque" (DataID 12304) and the "Position tracking error" (DataID 12320) for the axis in question.  If this is the source of the envelope error, the position error will increase significantly when the motor torque saturates at its maximum value for several tens of milliseconds.
  The axis has gone unstable due to a hardware failure or some other error.  This can be confirmed by listening for an audible noise or by datalogging the "Velocity tracking error" (DataID 12321) for the axis in question and looking for high frequency oscillations.
  An axis may have crashed into an obstacle and is unable to move to the specified position.
  The "Software envelope error limit" (DataID 10302) may be set to too small of a value. - 

the reason is probably that it tries to close too far, as the gripper closes all the way when I run it without a plate. strangely, _set_grip_close_pos does not make a difference (it does change the position for the closer_gripper command)

two questions:

• how to make it pick up a plate using pick_plate?
• how to recover from this error? hp 1 and attach 1 don't work.

[rickwierenga]

re my second question:

I get the following error when attempting any command after the crash:

PreciseFlexError -1009: No robot attached. A function or method was executed that required that a robot be ATTACHED.  ...

when I attach, I get this:

PreciseFlexError: PreciseFlexError -1007: Robot not ready to be attached. An Auto Execution task or a GPL project has attempted to gain control of a robot by executing a Robot.Attach method or similar function, but the specified robot is not in a state where it can be attached. If this was generated by a GPL project, it might indicate: That the system is configured to execute DIOMotion blocks instead of a GPL motion program (DataID 200) or "Auto start auto execute mode" (DataID 202) is not set to TRUE. If so, please check the Setup>Startup Configuration web page to verify the current setup. - 

I have to power cycle by physically powering off and on the robot.

[rickwierenga]

how to make it pick up a plate using pick_plate?

turns out, it pulls information not from the _set_grip_close_pos but from grasp_data (set_grasp_data and get_grasp_data). pushing a nice api in a bit.

[miikee]

I havent run into this error with the pick plate before. But it maybe that the speed in your profile is too fast. So that may need to be lowered in the speed profile because some joints may not be able to keep up.

The other part is I add in a setting to keep the wrist between +/- 180° to prevent some wild spinning of the wrist. It's a bitwise setting called GPL_Single flag (0x1000) in commit a332ab5

I think this including this would be useful because the wrist can get a little wild sometimes... but it may be the cause of this problem. I'd check the profile setting first though. I think the pick always just runs on profile 1.

[rickwierenga]

I think the reason is our end effector has prongs, which makes the default width different than yours. It is my first time using pick_plate.

[miikee]

If setup(), which has the hp 1 and attach 1 isn't working, it may have gotten hung up with the GPL code running on the system.

Go to the web application, I think its 192.168.0.1. Then select admin button and then click the top option in the side panel... I think it maybe be pendant or operator or similar. And in there I think you need to stop the GPL program that's loaded then need to load it again. I think there's a stop button and then you need to load it again. (You can also do this from Brooks' GDS app, if you have that)

I dont have my laptop or the bot right now... so this is from memory. And a bad memory too.

[rickwierenga]

we are mostly ready I think!

I just wrote a small tutorial showing how to do the basic things

one thing still to discuss:

• there are many duplicitous methods, such as pick_plate and its lower level function grasp_plate, and place_plate and release_plate. I think we should consider removing the lower level methods because I am not sure who would use those, and it makes the api ambiguous. do I use place_plate or release_plate? if there's a reason to keep them, maybe make them private? they are not used by PLR, and probably won't be by users.

I will do the resource modeling (ie picking up resources instead of "pick up from coordinate") in a future PR.

[miikee]

The only reason I can think of for keeping those functions is to have all endpoints of the TCS API exposed in python in case there is a difference and a user is specifically looking for one of them. But I think its probably just better to remove them in favor of a non-ambiguous API.

Brooks' TCS GPL code is open source if a user wants to explore things more. There's a few things not exposed through the TCS interface. An example is the Kinematic Solve function for cartesian <-> joint conversions. It exists on the robot, but isn't exposed through the TCS program that ships with the robot.

This is where Brooks' has a lot of their software - Guidance Development Studio (GDS), TCP Command Server (TCS), etc:
https://www.brooks.com/support/brooks-preciseflex-support/ - But they require you to reach out to get a password for access: support_preciseflex@brooks.com

[Copilot]

Pull request overview

This PR adds a comprehensive driver implementation for the PreciseFlex robotic arm (PF400 and PF3400 models). The implementation follows a backend/frontend architecture pattern with extensive test coverage for the backend logic.

Key changes:

• Introduces SCARABackend base class and ExperimentalSCARA frontend for robotic arm control
• Implements PreciseFlexBackend with full TCP/IP socket communication to Brooks TCS controller
• Adds support for Cartesian and joint-space movement, gripper control, and pick/place operations

Reviewed changes

Copilot reviewed 20 out of 21 changed files in this pull request and generated 10 comments.

Show a summary per file

File	Description
pylabrobot/arms/backend.py	Defines SCARABackend abstract base class and access pattern classes (VerticalAccess, HorizontalAccess)
pylabrobot/arms/scara.py	Frontend ExperimentalSCARA class that wraps backend methods
pylabrobot/arms/precise_flex/precise_flex_backend.py	Main backend implementation with 2400+ lines of TCS command wrappers
pylabrobot/arms/precise_flex/coords.py	PreciseFlex-specific Cartesian coordinates with elbow orientation
pylabrobot/arms/precise_flex/joints.py	Joint coordinate dataclass for 6-axis robot
pylabrobot/arms/precise_flex/pf_400.py	Specific backend for PF400 model
pylabrobot/arms/precise_flex/pf_3400.py	Specific backend for PF3400 model
pylabrobot/arms/scara_tests.py	Unit tests for SCARA frontend
pylabrobot/arms/precise_flex/precise_flex_backend_tests.py	Comprehensive unit tests (1551 lines) for backend
pylabrobot/resources/rotation.py	Adds roll, pitch, yaw properties for clearer rotation access
pylabrobot/io/socket.py	Changes logging from .hex() to raw bytes for better readability
pytest.ini	Adds hardware test marker to skip hardware-dependent tests by default
docs/user_guide/01_material-handling/arms/c_scara/precise-flex-pf400/hello-world.ipynb	Jupyter notebook tutorial for PreciseFlex usage

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[rickwierenga]

thank you so much for this massive effort!