Skip to content

Add manual servo offset calibration for tendon setup variations - #49

Open
actinbrandnew wants to merge 2 commits into
TetherIA:mainfrom
actinbrandnew:feature/manual-mid-calibration
Open

Add manual servo offset calibration for tendon setup variations#49
actinbrandnew wants to merge 2 commits into
TetherIA:mainfrom
actinbrandnew:feature/manual-mid-calibration

Conversation

@actinbrandnew

@actinbrandnew actinbrandnew commented Jul 24, 2026

Copy link
Copy Markdown

Summary

  • add a CALIBRATE_MID command for manually recalibrating an actuator offset
  • add a Calibrate Mid button to the setup GUI
  • report raw actuator positions after midpoint calibration and Trim
  • document a flexible calibration workflow for different tendon lengths, pretension, and spool winding directions

Why

Tendon length, pretension, and spool winding can vary between hand assemblies.

The existing Homing routine detects a mechanical stop and then applies a fixed half-turn offset of 2048 counts. This works with the expected assembly and winding configuration, but it may not place the full finger extension-to-flexion travel inside the actuator's single-turn position window when:

  • tendon lengths differ from the reference assembly
  • the initial spool wrap or pretension differs
  • users choose a different spool winding direction
  • accumulated assembly tolerances shift the useful actuator range

In these cases, Homing can complete successfully while the slider range still cannot cover the full finger motion.

This PR gives users direct control over the actuator offset. They can move an actuator to a suitable physical reference position in the GUI, calibrate that position to the actuator midpoint, and then use Trim to align the extension endpoint.

0a2cc401e71e27ee98b646ead19dd1ea

The following assembly is an example where tendon routing and spool winding may differ from the default Homing assumption:
7a0f9585c0de7a7d6f8e16777e006f5f

Calibration workflow

  1. Set a low speed and torque limit for the selected actuator.
  2. Use the GUI slider to move the spool to a suitable physical reference position.
  3. Press Calibrate Mid and select the actuator channel.
  4. Verify that the returned raw position is near the actuator midpoint, approximately 2048.
  5. Use Trim Servo to align the extension endpoint.
  6. Test the slider range and verify that it covers the required finger extension and flexion.

This does not replace the existing Homing routine. It provides an additional manual calibration option when the fixed Homing offset does not match the assembled tendon and spool configuration.

Safety

  • midpoint calibration is accepted only in position mode
  • the firmware checks that the calibrated position is near the actuator midpoint
  • the GUI warns that the actuator may move when position streaming resumes with the unchanged slider target
  • users should use low speed and torque during calibration
  • running Homing later recalibrates the actuator offset and can replace the manual midpoint calibration

Protocol and compatibility

  • add opcode 0x04 for CALIBRATE_MID
  • include status and protocol version fields in calibration and Trim responses
  • retain the existing Extend Count SDK return field for compatibility
  • serialize SDK communication to prevent calibration responses from conflicting with position streaming

Testing

  • tested on a right Aero Hand Open with HLS3606M actuators
  • tested with tendon lengths and spool winding that did not match the default Homing assumption
  • verified midpoint calibration returns a raw position near 2048
  • verified Calibrate Mid combined with Trim can reposition the useful finger travel inside the single-turn actuator range
  • verified Trim reports the saved extension endpoint and current raw position
  • verified the SDK and GUI with py_compile
  • successfully built the ESP32-S3 firmware with PlatformIO

@actinbrandnew
actinbrandnew requested a review from a team July 24, 2026 05:26
@actinbrandnew actinbrandnew changed the title Add manual actuator midpoint calibration Add manual servo offset calibration for tendon setup variations Jul 24, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant