orca_core 0.4.0__tar.gz → 0.4.2__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (192) hide show
  1. {orca_core-0.4.0 → orca_core-0.4.2}/.github/workflows/test.yml +15 -2
  2. {orca_core-0.4.0 → orca_core-0.4.2}/CLAUDE.md +65 -2
  3. {orca_core-0.4.0 → orca_core-0.4.2}/PKG-INFO +15 -4
  4. {orca_core-0.4.0 → orca_core-0.4.2}/README.md +13 -2
  5. {orca_core-0.4.0 → orca_core-0.4.2}/docs/pages/getting-started-docs/setting-up-config.md +11 -10
  6. orca_core-0.4.2/docs/pages/getting-started-docs/windows.md +96 -0
  7. {orca_core-0.4.0 → orca_core-0.4.2}/docs/pages/orca-core-docs/motor-client-api.md +8 -6
  8. {orca_core-0.4.0 → orca_core-0.4.2}/docs/pages/orca-core-docs/orca-core-scripts.md +1 -1
  9. {orca_core-0.4.0 → orca_core-0.4.2}/examples/main_demo.py +2 -2
  10. {orca_core-0.4.0 → orca_core-0.4.2}/examples/main_demo_abduction.py +2 -2
  11. {orca_core-0.4.0 → orca_core-0.4.2}/examples/record_angles.py +25 -3
  12. orca_core-0.4.2/examples/record_continuous.py +133 -0
  13. {orca_core-0.4.0 → orca_core-0.4.2}/examples/replay_angles.py +10 -2
  14. {orca_core-0.4.0 → orca_core-0.4.2}/examples/replay_continuous.py +2 -2
  15. {orca_core-0.4.0 → orca_core-0.4.2}/examples/taxel_frames.py +18 -9
  16. {orca_core-0.4.0 → orca_core-0.4.2}/mkdocs.yml +1 -0
  17. {orca_core-0.4.0 → orca_core-0.4.2}/orca_core/api/api.py +97 -34
  18. {orca_core-0.4.0 → orca_core-0.4.2}/orca_core/constants.py +6 -2
  19. {orca_core-0.4.0 → orca_core-0.4.2}/orca_core/hand_config.py +102 -12
  20. {orca_core-0.4.0 → orca_core-0.4.2}/orca_core/hand_factory.py +127 -9
  21. {orca_core-0.4.0 → orca_core-0.4.2}/orca_core/hardware/dynamixel_client.py +34 -3
  22. {orca_core-0.4.0 → orca_core-0.4.2}/orca_core/hardware/feetech/sms_sts.py +8 -8
  23. orca_core-0.4.2/orca_core/hardware/feetech_client.py +1329 -0
  24. orca_core-0.4.2/orca_core/hardware/feetech_registers.py +33 -0
  25. {orca_core-0.4.0 → orca_core-0.4.2}/orca_core/hardware/mock_dynamixel_client.py +17 -4
  26. orca_core-0.4.2/orca_core/hardware/mock_feetech_client.py +290 -0
  27. {orca_core-0.4.0 → orca_core-0.4.2}/orca_core/hardware/motor_client.py +127 -3
  28. {orca_core-0.4.0 → orca_core-0.4.2}/orca_core/hardware/motor_factory.py +32 -0
  29. orca_core-0.4.2/orca_core/hardware/motor_resolution.py +114 -0
  30. {orca_core-0.4.0 → orca_core-0.4.2}/orca_core/hardware/sensing/health.py +2 -1
  31. {orca_core-0.4.0 → orca_core-0.4.2}/orca_core/hardware/sensing/serial_discovery.py +31 -0
  32. {orca_core-0.4.0 → orca_core-0.4.2}/orca_core/hardware_hand.py +146 -47
  33. {orca_core-0.4.0 → orca_core-0.4.2}/orca_core/maintenance/calibration_routine.py +29 -29
  34. {orca_core-0.4.0 → orca_core-0.4.2}/orca_core/maintenance/motor_chain.py +54 -16
  35. orca_core-0.4.2/orca_core/maintenance/motor_reads.py +43 -0
  36. {orca_core-0.4.0 → orca_core-0.4.2}/orca_core/maintenance/tensioning.py +20 -2
  37. {orca_core-0.4.0 → orca_core-0.4.2}/orca_core/models/v1/orcahand-left/config.yaml +1 -2
  38. {orca_core-0.4.0 → orca_core-0.4.2}/orca_core/models/v1/orcahand-right/config.yaml +1 -2
  39. {orca_core-0.4.0 → orca_core-0.4.2}/orca_core/models/v2/orcahand-full-left/config.yaml +5 -6
  40. {orca_core-0.4.0 → orca_core-0.4.2}/orca_core/models/v2/orcahand-full-right/config.yaml +9 -10
  41. {orca_core-0.4.0 → orca_core-0.4.2}/orca_core/models/v2/orcahand-joint-left/config.yaml +5 -6
  42. {orca_core-0.4.0 → orca_core-0.4.2}/orca_core/models/v2/orcahand-joint-right/config.yaml +9 -10
  43. {orca_core-0.4.0 → orca_core-0.4.2}/orca_core/models/v2/orcahand-left/config.yaml +5 -6
  44. {orca_core-0.4.0 → orca_core-0.4.2}/orca_core/models/v2/orcahand-right/config.yaml +9 -10
  45. {orca_core-0.4.0 → orca_core-0.4.2}/orca_core/models/v2/orcahand-touch-left/config.yaml +5 -6
  46. {orca_core-0.4.0 → orca_core-0.4.2}/orca_core/models/v2/orcahand-touch-right/config.yaml +9 -10
  47. {orca_core-0.4.0 → orca_core-0.4.2}/orca_core/utils/__init__.py +4 -0
  48. orca_core-0.4.2/orca_core/utils/cli.py +166 -0
  49. {orca_core-0.4.0 → orca_core-0.4.2}/orca_core/utils/utils.py +66 -6
  50. {orca_core-0.4.0 → orca_core-0.4.2}/pyproject.toml +9 -1
  51. {orca_core-0.4.0 → orca_core-0.4.2}/scripts/calibrate.py +15 -68
  52. orca_core-0.4.2/scripts/check_motor.py +110 -0
  53. {orca_core-0.4.0 → orca_core-0.4.2}/scripts/check_sensors.py +4 -2
  54. {orca_core-0.4.0 → orca_core-0.4.2}/scripts/configure_motor_chain.py +56 -14
  55. orca_core-0.4.2/scripts/detect.py +56 -0
  56. {orca_core-0.4.0 → orca_core-0.4.2}/scripts/manual_control.py +74 -18
  57. {orca_core-0.4.0 → orca_core-0.4.2}/scripts/monitor_sensors.py +2 -3
  58. {orca_core-0.4.0 → orca_core-0.4.2}/scripts/neutral.py +2 -2
  59. {orca_core-0.4.0 → orca_core-0.4.2}/scripts/setup.py +16 -55
  60. {orca_core-0.4.0 → orca_core-0.4.2}/scripts/stress_test.py +43 -59
  61. {orca_core-0.4.0 → orca_core-0.4.2}/scripts/tension.py +2 -2
  62. {orca_core-0.4.0 → orca_core-0.4.2}/scripts/zero.py +2 -2
  63. {orca_core-0.4.0 → orca_core-0.4.2}/tests/conftest.py +62 -6
  64. {orca_core-0.4.0 → orca_core-0.4.2}/tests/test_api.py +78 -22
  65. {orca_core-0.4.0 → orca_core-0.4.2}/tests/test_calibration_routine.py +87 -5
  66. {orca_core-0.4.0 → orca_core-0.4.2}/tests/test_connect_resolution.py +145 -96
  67. {orca_core-0.4.0 → orca_core-0.4.2}/tests/test_core.py +0 -22
  68. {orca_core-0.4.0 → orca_core-0.4.2}/tests/test_dynamixel_client_locking.py +4 -0
  69. orca_core-0.4.2/tests/test_dynamixel_current_limits.py +154 -0
  70. {orca_core-0.4.0 → orca_core-0.4.2}/tests/test_feetech_client.py +63 -17
  71. orca_core-0.4.2/tests/test_feetech_registers.py +25 -0
  72. {orca_core-0.4.0 → orca_core-0.4.2}/tests/test_hand_class_layout.py +14 -1
  73. orca_core-0.4.2/tests/test_hand_config_loading.py +167 -0
  74. orca_core-0.4.2/tests/test_hand_detection.py +450 -0
  75. {orca_core-0.4.0 → orca_core-0.4.2}/tests/test_hand_factory.py +58 -0
  76. {orca_core-0.4.0 → orca_core-0.4.2}/tests/test_hardware_hand.py +39 -7
  77. {orca_core-0.4.0 → orca_core-0.4.2}/tests/test_jitter.py +50 -29
  78. {orca_core-0.4.0 → orca_core-0.4.2}/tests/test_kinematics_extractor.py +24 -1
  79. {orca_core-0.4.0 → orca_core-0.4.2}/tests/test_motor_client_contract.py +130 -39
  80. {orca_core-0.4.0 → orca_core-0.4.2}/tests/test_motor_client_registry.py +94 -4
  81. orca_core-0.4.2/tests/test_motor_clients_feetech_parity.py +538 -0
  82. orca_core-0.4.2/tests/test_package_core_feetech.py +292 -0
  83. {orca_core-0.4.0 → orca_core-0.4.2}/tests/test_public_api_surface.py +1 -0
  84. orca_core-0.4.2/tests/test_scripts_cli.py +497 -0
  85. {orca_core-0.4.0 → orca_core-0.4.2}/tests/test_tension.py +90 -15
  86. {orca_core-0.4.0 → orca_core-0.4.2}/tests/test_touch_connect.py +13 -0
  87. orca_core-0.4.2/tests/test_virtual_clock.py +104 -0
  88. orca_core-0.4.2/tests/test_windows_compat.py +113 -0
  89. {orca_core-0.4.0 → orca_core-0.4.2}/tools/extract_urdf_kinematics.py +27 -7
  90. {orca_core-0.4.0 → orca_core-0.4.2}/uv.lock +25 -1
  91. orca_core-0.4.0/examples/record_continuous.py +0 -83
  92. orca_core-0.4.0/orca_core/hardware/feetech_client.py +0 -925
  93. orca_core-0.4.0/orca_core/hardware/motor_resolution.py +0 -140
  94. orca_core-0.4.0/orca_core/utils/cli.py +0 -72
  95. orca_core-0.4.0/scripts/check_motor.py +0 -58
  96. orca_core-0.4.0/tests/test_hand_config_loading.py +0 -62
  97. orca_core-0.4.0/tests/test_hand_detection.py +0 -159
  98. {orca_core-0.4.0 → orca_core-0.4.2}/.github/workflows/downstream.yml +0 -0
  99. {orca_core-0.4.0 → orca_core-0.4.2}/.github/workflows/release.yml +0 -0
  100. {orca_core-0.4.0 → orca_core-0.4.2}/.gitignore +0 -0
  101. {orca_core-0.4.0 → orca_core-0.4.2}/LICENSE +0 -0
  102. {orca_core-0.4.0 → orca_core-0.4.2}/docs/auto_docs_instructions.md +0 -0
  103. {orca_core-0.4.0 → orca_core-0.4.2}/docs/css/overrides.css +0 -0
  104. {orca_core-0.4.0 → orca_core-0.4.2}/docs/img/logo-light-256.png +0 -0
  105. {orca_core-0.4.0 → orca_core-0.4.2}/docs/index.md +0 -0
  106. {orca_core-0.4.0 → orca_core-0.4.2}/docs/pages/getting-started-docs/initial-tensioning-and-calibration.md +0 -0
  107. {orca_core-0.4.0 → orca_core-0.4.2}/docs/pages/getting-started-docs/quickstart-with-core-package.md +0 -0
  108. {orca_core-0.4.0 → orca_core-0.4.2}/docs/pages/getting-started-docs/setting-up-dynamixels.md +0 -0
  109. {orca_core-0.4.0 → orca_core-0.4.2}/docs/pages/orca-core-docs/latency-optimization.md +0 -0
  110. {orca_core-0.4.0 → orca_core-0.4.2}/docs/pages/orca-core-docs/orca-core-structure.md +0 -0
  111. {orca_core-0.4.0 → orca_core-0.4.2}/docs/pages/orca-core-docs/orcahand-api.md +0 -0
  112. {orca_core-0.4.0 → orca_core-0.4.2}/docs/pages/orca-core-docs/tactile-frames.md +0 -0
  113. {orca_core-0.4.0 → orca_core-0.4.2}/docs/requirements.txt +0 -0
  114. {orca_core-0.4.0 → orca_core-0.4.2}/examples/demo_runner.py +0 -0
  115. {orca_core-0.4.0 → orca_core-0.4.2}/examples/sequences/kapandji_opposition.yaml +0 -0
  116. {orca_core-0.4.0 → orca_core-0.4.2}/orca_core/__init__.py +0 -0
  117. {orca_core-0.4.0 → orca_core-0.4.2}/orca_core/api/__init__.py +0 -0
  118. {orca_core-0.4.0 → orca_core-0.4.2}/orca_core/base_hand.py +0 -0
  119. {orca_core-0.4.0 → orca_core-0.4.2}/orca_core/calibration.py +0 -0
  120. {orca_core-0.4.0 → orca_core-0.4.2}/orca_core/control/__init__.py +0 -0
  121. {orca_core-0.4.0 → orca_core-0.4.2}/orca_core/control/constants.py +0 -0
  122. {orca_core-0.4.0 → orca_core-0.4.2}/orca_core/control/joint_controller.py +0 -0
  123. {orca_core-0.4.0 → orca_core-0.4.2}/orca_core/control/joint_loop.py +0 -0
  124. {orca_core-0.4.0 → orca_core-0.4.2}/orca_core/data/demo_poses.yaml +0 -0
  125. {orca_core-0.4.0 → orca_core-0.4.2}/orca_core/demo_poses.py +0 -0
  126. {orca_core-0.4.0 → orca_core-0.4.2}/orca_core/hardware/__init__.py +0 -0
  127. {orca_core-0.4.0 → orca_core-0.4.2}/orca_core/hardware/feetech/__init__.py +0 -0
  128. {orca_core-0.4.0 → orca_core-0.4.2}/orca_core/hardware/feetech/group_sync_read.py +0 -0
  129. {orca_core-0.4.0 → orca_core-0.4.2}/orca_core/hardware/feetech/group_sync_write.py +0 -0
  130. {orca_core-0.4.0 → orca_core-0.4.2}/orca_core/hardware/feetech/hls.py +0 -0
  131. {orca_core-0.4.0 → orca_core-0.4.2}/orca_core/hardware/feetech/port_handler.py +0 -0
  132. {orca_core-0.4.0 → orca_core-0.4.2}/orca_core/hardware/feetech/protocol_packet_handler.py +0 -0
  133. {orca_core-0.4.0 → orca_core-0.4.2}/orca_core/hardware/feetech/scscl.py +0 -0
  134. {orca_core-0.4.0 → orca_core-0.4.2}/orca_core/hardware/feetech/scservo_def.py +0 -0
  135. {orca_core-0.4.0 → orca_core-0.4.2}/orca_core/hardware/hand_serial_link.py +0 -0
  136. {orca_core-0.4.0 → orca_core-0.4.2}/orca_core/hardware/joint_encoder_client.py +0 -0
  137. {orca_core-0.4.0 → orca_core-0.4.2}/orca_core/hardware/mock_hand_serial_link.py +0 -0
  138. {orca_core-0.4.0 → orca_core-0.4.2}/orca_core/hardware/sensing/__init__.py +0 -0
  139. {orca_core-0.4.0 → orca_core-0.4.2}/orca_core/hardware/sensing/constants.py +0 -0
  140. {orca_core-0.4.0 → orca_core-0.4.2}/orca_core/hardware/sensing/encoder_protocol.py +0 -0
  141. {orca_core-0.4.0 → orca_core-0.4.2}/orca_core/hardware/sensing/framing.py +0 -0
  142. {orca_core-0.4.0 → orca_core-0.4.2}/orca_core/hardware/sensing/models/touch-sensor-finger/config.yaml +0 -0
  143. {orca_core-0.4.0 → orca_core-0.4.2}/orca_core/hardware/sensing/models/touch-sensor-pinky/config.yaml +0 -0
  144. {orca_core-0.4.0 → orca_core-0.4.2}/orca_core/hardware/sensing/models/touch-sensor-thumb/config.yaml +0 -0
  145. {orca_core-0.4.0 → orca_core-0.4.2}/orca_core/hardware/sensing/tactile_mock.py +0 -0
  146. {orca_core-0.4.0 → orca_core-0.4.2}/orca_core/hardware/sensing/tactile_protocol.py +0 -0
  147. {orca_core-0.4.0 → orca_core-0.4.2}/orca_core/hardware/sensing/taxel_geometry.py +0 -0
  148. {orca_core-0.4.0 → orca_core-0.4.2}/orca_core/hardware/sensing/types.py +0 -0
  149. {orca_core-0.4.0 → orca_core-0.4.2}/orca_core/hardware/tactile_client.py +0 -0
  150. {orca_core-0.4.0 → orca_core-0.4.2}/orca_core/hardware_hand_sensing.py +0 -0
  151. {orca_core-0.4.0 → orca_core-0.4.2}/orca_core/joint_position.py +0 -0
  152. {orca_core-0.4.0 → orca_core-0.4.2}/orca_core/kinematics/__init__.py +0 -0
  153. {orca_core-0.4.0 → orca_core-0.4.2}/orca_core/kinematics/data/v2_kinematics.yaml +0 -0
  154. {orca_core-0.4.0 → orca_core-0.4.2}/orca_core/kinematics/frames.py +0 -0
  155. {orca_core-0.4.0 → orca_core-0.4.2}/orca_core/kinematics/hand_kinematics.py +0 -0
  156. {orca_core-0.4.0 → orca_core-0.4.2}/orca_core/kinematics/transforms.py +0 -0
  157. {orca_core-0.4.0 → orca_core-0.4.2}/orca_core/maintenance/__init__.py +0 -0
  158. {orca_core-0.4.0 → orca_core-0.4.2}/orca_core/version.py +0 -0
  159. {orca_core-0.4.0 → orca_core-0.4.2}/tests/__init__.py +0 -0
  160. {orca_core-0.4.0 → orca_core-0.4.2}/tests/_encoder_helpers.py +0 -0
  161. {orca_core-0.4.0 → orca_core-0.4.2}/tests/_hand_feedback_helpers.py +0 -0
  162. {orca_core-0.4.0 → orca_core-0.4.2}/tests/_helpers.py +0 -0
  163. {orca_core-0.4.0 → orca_core-0.4.2}/tests/_loop_helpers.py +0 -0
  164. {orca_core-0.4.0 → orca_core-0.4.2}/tests/reference/calibration_expected.yaml +0 -0
  165. {orca_core-0.4.0 → orca_core-0.4.2}/tests/test_base_hand_contract.py +0 -0
  166. {orca_core-0.4.0 → orca_core-0.4.2}/tests/test_calibration.py +0 -0
  167. {orca_core-0.4.0 → orca_core-0.4.2}/tests/test_calibration_reference.py +0 -0
  168. {orca_core-0.4.0 → orca_core-0.4.2}/tests/test_demo_poses.py +0 -0
  169. {orca_core-0.4.0 → orca_core-0.4.2}/tests/test_encoder_anchor_sampling.py +0 -0
  170. {orca_core-0.4.0 → orca_core-0.4.2}/tests/test_encoder_polarity_by_side.py +0 -0
  171. {orca_core-0.4.0 → orca_core-0.4.2}/tests/test_encoder_protocol.py +0 -0
  172. {orca_core-0.4.0 → orca_core-0.4.2}/tests/test_hand_serial_link.py +0 -0
  173. {orca_core-0.4.0 → orca_core-0.4.2}/tests/test_hardware_constants.py +0 -0
  174. {orca_core-0.4.0 → orca_core-0.4.2}/tests/test_hardware_hand_full.py +0 -0
  175. {orca_core-0.4.0 → orca_core-0.4.2}/tests/test_hardware_hand_joint_feedback.py +0 -0
  176. {orca_core-0.4.0 → orca_core-0.4.2}/tests/test_joint_controller.py +0 -0
  177. {orca_core-0.4.0 → orca_core-0.4.2}/tests/test_joint_encoder_client.py +0 -0
  178. {orca_core-0.4.0 → orca_core-0.4.2}/tests/test_joint_loop.py +0 -0
  179. {orca_core-0.4.0 → orca_core-0.4.2}/tests/test_kinematics.py +0 -0
  180. {orca_core-0.4.0 → orca_core-0.4.2}/tests/test_mock_sensing_connect.py +0 -0
  181. {orca_core-0.4.0 → orca_core-0.4.2}/tests/test_model_dispatch.py +0 -0
  182. {orca_core-0.4.0 → orca_core-0.4.2}/tests/test_motor_chain.py +0 -0
  183. {orca_core-0.4.0 → orca_core-0.4.2}/tests/test_sensing_errors.py +0 -0
  184. {orca_core-0.4.0 → orca_core-0.4.2}/tests/test_sensing_health.py +0 -0
  185. {orca_core-0.4.0 → orca_core-0.4.2}/tests/test_serial_discovery.py +0 -0
  186. {orca_core-0.4.0 → orca_core-0.4.2}/tests/test_tactile_protocol.py +0 -0
  187. {orca_core-0.4.0 → orca_core-0.4.2}/tests/test_tactile_rearm.py +0 -0
  188. {orca_core-0.4.0 → orca_core-0.4.2}/tests/test_tactile_sensor.py +0 -0
  189. {orca_core-0.4.0 → orca_core-0.4.2}/tests/test_taxel_frames.py +0 -0
  190. {orca_core-0.4.0 → orca_core-0.4.2}/tests/test_taxel_geometry.py +0 -0
  191. {orca_core-0.4.0 → orca_core-0.4.2}/tests/test_yaml.py +0 -0
  192. {orca_core-0.4.0 → orca_core-0.4.2}/tools/check_downstream.py +0 -0
@@ -6,8 +6,13 @@ on:
6
6
  - main
7
7
 
8
8
  jobs:
9
- test:
10
- runs-on: ubuntu-latest
9
+ test-matrix:
10
+ name: test (${{ matrix.os }})
11
+ strategy:
12
+ fail-fast: false
13
+ matrix:
14
+ os: [ubuntu-latest, windows-latest]
15
+ runs-on: ${{ matrix.os }}
11
16
 
12
17
  steps:
13
18
  - uses: actions/checkout@v4
@@ -27,3 +32,11 @@ jobs:
27
32
  - name: Run Tests
28
33
  run: |
29
34
  uv run pytest
35
+
36
+ # Single check named "test" for the main ruleset; passes only if every matrix leg passed.
37
+ test:
38
+ needs: test-matrix
39
+ if: always()
40
+ runs-on: ubuntu-latest
41
+ steps:
42
+ - run: test "${{ needs.test-matrix.result }}" = "success"
@@ -113,6 +113,48 @@ so a terminal and a GUI drive the identical routine.
113
113
  - Max 1-2 lines per comment. Longer is only OK for headstrings on files, major classes, or major functions.
114
114
  - Comments describe the current state of the code, never its history. Don't reference previous versions, past bugs, prior approaches that didn't work, commits, or plans/tasks - if it's not true of the code as it stands, it doesn't belong in a comment.
115
115
  - Don't require hardware-specific insider knowledge to understand a comment. Refer to hardware generically rather than by internal codename.
116
+ - Never put a real hand's identity in comments, docstrings, usage text, docs, or tests: no serial numbers, board IDs, USB descriptors, or adapter paths copied from a real device. Use obvious placeholders - `ser-0000` (`ser-0001`, `ser-0002`, ... when several hands are needed), `/dev/cu.usbmodemXXXX`, a patterned board ID like `0123456789ABCDEF`.
117
+
118
+ ---
119
+
120
+ ## Never hardcode what the package can resolve
121
+
122
+ Every hand differs in motor family, serial ports, side, and which sensors it carries. All of that is
123
+ discovered at runtime. Code that assumes any of it works on one bench and fails on the next, and the
124
+ failure is usually silent - the wrong model loads, or a probe searches the wrong vendor IDs.
125
+
126
+ **Motors.** Never import or instantiate a concrete client (`DynamixelClient`, `FeetechClient`). Go
127
+ through `motor_factory.motor_client_class()` / `load_hand()`, and program against the `MotorClient`
128
+ ABC in `hardware/motor_client.py`. Family differences belong behind a class attribute on the client
129
+ (`supported_modes`, `supports_multi_turn`, `waits_for_motion`, `position_range_rad`,
130
+ `baud_rate_map`, ...) - never behind an `if motor_type == ...` in generic code. Adding a capability
131
+ means adding it to the ABC and implementing it on *every* client, mocks included. Control-mode
132
+ values, current units, and position ranges are family-specific: read them from the client, don't
133
+ assume Dynamixel's.
134
+
135
+ **Ports and baud.** Never hardcode a device path or baud rate, and never default one. Use the
136
+ auto-discovery in `hardware/sensing/serial_discovery.py` and `utils.auto_detect_port()`, with
137
+ connect-time probing (`hardware/motor_resolution.py`) resolving the driver. A `--port` flag is an
138
+ override for bring-up, not the normal path.
139
+
140
+ **Hand identity.** Never assume a side, model directory, joint list, or that sensors exist.
141
+ `detect_hand()` / `load_hand()` decide which class and model a connected hand gets; `config.yaml` is
142
+ the source of truth for everything else.
143
+
144
+ **Config beats detection, and says so.** The packaged configs ship every resolvable field on `auto`
145
+ (or absent), so autodetection is what runs by default - never pin a real port, baud rate or motor
146
+ family into one. A value a human writes into a config is a deliberate override and wins over what
147
+ was detected. Whenever a pin displaces a detected value, log it at warning level naming the field,
148
+ the pinned value and the detected one: a silent override is indistinguishable from broken
149
+ autodetection. Detection results are never written back to any config - every connect re-probes what
150
+ the yaml leaves unset.
151
+
152
+ **Front-ends.** Scripts and examples carry no logic. Use the shared argparse and lifecycle helpers in
153
+ `utils/cli.py`; a flag it advertises must actually be forwarded to `load_hand()`. If a front-end
154
+ needs something new, add it to `utils/cli.py` so every front-end gets it.
155
+
156
+ The test for any change here: would this still work on a Feetech left hand with no tactile sensors,
157
+ plugged into a port nobody told it about? If not, it is hardcoding something the package can resolve.
116
158
 
117
159
  ---
118
160
 
@@ -143,9 +185,21 @@ uv sync --group dev
143
185
  ### Testing
144
186
 
145
187
  ```bash
146
- uv run pytest tests/
188
+ uv run pytest tests/ # whole suite, fanned across cores (~3s)
189
+ uv run pytest tests/ -n0 # serial: readable output when debugging a failure
147
190
  ```
148
191
 
192
+ `addopts = "-n auto"` in `pyproject.toml` makes the suite parallel by default.
193
+
194
+ Mock backends must never wait on hardware. The settle waits real hands need
195
+ (e.g. `_torque_disable_settle_s`) are class attributes the `Mock*` classes set
196
+ to `0.0`, and routines that pace themselves against `time.time()` run on the virtual clock in `tests/conftest.py`
197
+ — its `sleep` advances a per-thread counter that the thread's clock readings add
198
+ back, so a routine observes the durations it asked for at no wall-clock cost.
199
+ Assert on durations via the `virtual_clock` fixture, read on the thread that ran
200
+ the routine, never on real elapsed time; to hold a background task mid-flight,
201
+ block it on an event rather than sleeping and hoping.
202
+
149
203
  ### Downstream consumers
150
204
 
151
205
  `orca_core` is published on PyPI and imported by sibling repos checked out beside it
@@ -169,9 +223,12 @@ Note that `release.yml` publishes to PyPI on every push to `main` carrying a new
169
223
 
170
224
  ### Common Scripts
171
225
 
172
- Every script takes an optional positional `config_path` pointing at a model's `config.yaml` (defaults to the package's bundled model if omitted). Run `--help` on any script for its full flag list.
226
+ Every script takes an optional positional `config_path` pointing at a model's `config.yaml` (omit it to autodetect the connected hand). Run `--help` on any script for its full flag list.
173
227
 
174
228
  ```bash
229
+ # What is plugged in? Run this first on a new or misbehaving hand (read-only).
230
+ uv run python scripts/detect.py
231
+
175
232
  # Calibration workflow
176
233
  uv run python scripts/tension.py orca_core/models/v2/orcahand-right/config.yaml
177
234
  uv run python scripts/calibrate.py orca_core/models/v2/orcahand-right/config.yaml
@@ -192,6 +249,12 @@ uv run python scripts/monitor_sensors.py
192
249
 
193
250
  All hand-specific settings are in `config.yaml`:
194
251
  - Motor-to-joint mapping, joint ROMs (ranges of motion), neutral positions, calibration sequences
252
+ - `max_current` / `calibration_current` / `wrist_calibration_current` - `default` (what the
253
+ packaged configs say) resolves to the connected motor family's own values, the
254
+ `default_max_current_ma` / `default_calibration_current_ma` class attributes on its client
255
+ (Dynamixel 300/300, Feetech 900/900). A number pins an override for one hand. Resolution
256
+ happens in `load_hand()` when the family is detected or pinned, otherwise at connect, so
257
+ read these fields after `connect()`.
195
258
  - `use_joint_feedback` + `joint_encoder_joints` + `encoder_serial_port` - enable the closed-loop joint-encoder controller (`load_hand` then returns `OrcaHandJointFeedback`/`OrcaHandFull`)
196
259
  - `sensors:` block - enable tactile sensing (`load_hand` then returns `OrcaHandTouch`/`OrcaHandFull`)
197
260
 
@@ -1,6 +1,6 @@
1
- Metadata-Version: 2.4
1
+ Metadata-Version: 2.5
2
2
  Name: orca_core
3
- Version: 0.4.0
3
+ Version: 0.4.2
4
4
  Summary: Core Python Controller of the ORCA Hand. Handles all hardware interaction, logic and abstracts control. Provides API for basic functionality and info of the hand.
5
5
  Author-email: clemens-chr <cchristoph@student.ethz.ch>, fabricenoelbourquin <fabrice.bourquin@protonmail.ch>, maximilianeberlein <meberlein@ethz.ch>, fracapuano <capuano@robots.ox.ac.uk>
6
6
  License: MIT
@@ -47,7 +47,8 @@ To get started with Orca Core, follow these steps:
47
47
  If you prefer an activated shell, you can still use:
48
48
 
49
49
  ```sh
50
- source .venv/bin/activate
50
+ source .venv/bin/activate # macOS / Linux
51
+ .venv\Scripts\activate # Windows
51
52
  ```
52
53
 
53
54
  End users who do not use `uv` can still install the package with:
@@ -95,6 +96,16 @@ sudo usermod -aG dialout $USER
95
96
  sudo chmod 666 /dev/ttyACM0
96
97
  ```
97
98
 
99
+ ### Windows
100
+
101
+ Supported on Windows 10 and 11; no permission setup is needed. Ports are named `COM3`, `COM4`, ... and are listed with:
102
+
103
+ ```sh
104
+ uv run python -m serial.tools.list_ports -v
105
+ ```
106
+
107
+ Driver notes, latency settings and the first-connection checklist: [Running on Windows](docs/pages/getting-started-docs/windows.md).
108
+
98
109
  ### Serial port, baudrate, and motor type
99
110
 
100
111
  By default these are all **auto-detected** at connect time.
@@ -107,7 +118,7 @@ However, you can declare them explicitly in `config.yaml`. Useful when:
107
118
 
108
119
  ```yaml
109
120
  # Optional overrides: auto-detected if omitted
110
- port: /dev/ttyACM0 # or /dev/cu.usbmodemXXXX on macOS
121
+ port: /dev/ttyACM0 # /dev/cu.usbmodemXXXX on macOS, COM3 on Windows
111
122
  baudrate: 1000000 # 1M for v2; 3M for v1
112
123
  motor_type: dynamixel # or 'feetech'
113
124
  ```
@@ -31,7 +31,8 @@ To get started with Orca Core, follow these steps:
31
31
  If you prefer an activated shell, you can still use:
32
32
 
33
33
  ```sh
34
- source .venv/bin/activate
34
+ source .venv/bin/activate # macOS / Linux
35
+ .venv\Scripts\activate # Windows
35
36
  ```
36
37
 
37
38
  End users who do not use `uv` can still install the package with:
@@ -79,6 +80,16 @@ sudo usermod -aG dialout $USER
79
80
  sudo chmod 666 /dev/ttyACM0
80
81
  ```
81
82
 
83
+ ### Windows
84
+
85
+ Supported on Windows 10 and 11; no permission setup is needed. Ports are named `COM3`, `COM4`, ... and are listed with:
86
+
87
+ ```sh
88
+ uv run python -m serial.tools.list_ports -v
89
+ ```
90
+
91
+ Driver notes, latency settings and the first-connection checklist: [Running on Windows](docs/pages/getting-started-docs/windows.md).
92
+
82
93
  ### Serial port, baudrate, and motor type
83
94
 
84
95
  By default these are all **auto-detected** at connect time.
@@ -91,7 +102,7 @@ However, you can declare them explicitly in `config.yaml`. Useful when:
91
102
 
92
103
  ```yaml
93
104
  # Optional overrides: auto-detected if omitted
94
- port: /dev/ttyACM0 # or /dev/cu.usbmodemXXXX on macOS
105
+ port: /dev/ttyACM0 # /dev/cu.usbmodemXXXX on macOS, COM3 on Windows
95
106
  baudrate: 1000000 # 1M for v2; 3M for v1
96
107
  motor_type: dynamixel # or 'feetech'
97
108
  ```
@@ -15,33 +15,32 @@ This file defines parameters crucial for the hand's operation, including communi
15
15
 
16
16
  ```yaml
17
17
  port: auto
18
- baudrate: 1000000
19
- max_current: 300
18
+ max_current: default
20
19
  type: right
21
20
  control_mode: current_based_position
22
21
  ```
23
22
 
24
23
  **What should be changed?**
25
24
 
26
- Change `type` to right or left depending on the hand assembly. `max_current` is set to a sane default; adjust if your tasks need more or less. `control_mode` should generally stay at `current_based_position`.
25
+ Change `type` to right or left depending on the hand assembly. `max_current: default` uses the motor family's own limit (300 mA on Dynamixel hands, 900 mA on Feetech hands); put a number there to pin a different limit for this hand. `control_mode` should generally stay at `current_based_position`.
27
26
 
28
27
  #### Driver settings: `port`, `baudrate`, `motor_type`
29
28
 
30
- The bundled configs ship with `port: auto` and a `baudrate` pinned for the hand version (1M for v2, 3M for v1). Anything not pinned is auto-detected at connect time and persisted back to `config.yaml`:
29
+ The bundled configs leave all three on auto-detection: `port: auto`, and no `motor_type` or `baudrate` at all. They are resolved fresh on every connect and never written back to the file:
31
30
 
32
31
  - `port: auto` finds the serial adapter by USB VID, falling back to "the only adapter present" or an interactive picker.
33
- - A missing `motor_type` is identified by pinging each motor family (Dynamixel vs Feetech) on the bus.
34
- - A missing `baudrate` is probed from the family's known set (1M / 3M for Dynamixel, 1M for Feetech).
32
+ - `motor_type` is identified by pinging each motor family (Dynamixel vs Feetech) on the bus.
33
+ - `baudrate` is probed from the family's known set (1M / 3M for Dynamixel, 1M for Feetech).
35
34
 
36
- Override any of them explicitly if you need to:
35
+ Write a value into the file to override detection for that field:
37
36
 
38
37
  ```yaml
39
- port: /dev/cu.usbmodemXXXX # when multiple adapters are connected
38
+ port: /dev/cu.usbmodemXXXX # when multiple adapters are connected (COM3 on Windows)
40
39
  baudrate: 1000000 # when motors are configured for a non-default rate
41
40
  motor_type: feetech # when probing might misidentify the bus
42
41
  ```
43
42
 
44
- You won't normally need to — the script will tell you on the command line if a probe failed and asking for an override would help.
43
+ A value you write wins over what was detected, and the log says so whenever the two disagree. You won't normally need one — the script will tell you on the command line if a probe failed and asking for an override would help. Remove the line (or set `port: auto`) to go back to detection.
45
44
 
46
45
  ---
47
46
 
@@ -137,7 +136,7 @@ You can adjust this section if you want the hand to return to a different defaul
137
136
  ### 6. Calibration Parameters
138
137
 
139
138
  ```yaml
140
- calibration_current: 350
139
+ calibration_current: default
141
140
  calibration_step_size: 0.1
142
141
  calibration_step_period: 0.001
143
142
  calibration_num_stable: 10
@@ -146,6 +145,8 @@ calibration_threshold: 0.01
146
145
 
147
146
  **What should be changed?**
148
147
 
148
+ `calibration_current: default` drives the joints to their hardstops at the motor family's own calibration current (300 mA on Dynamixel hands, 900 mA on Feetech hands). A number pins a different value; `wrist_calibration_current` follows it unless set.
149
+
149
150
  These parameters should generally not be changed unless you have experience tuning the calibration behavior for a specific hardware modification.
150
151
 
151
152
  ---
@@ -0,0 +1,96 @@
1
+ # Running on Windows
2
+
3
+ orca_core runs on Windows 10 and 11. The hand is driven over a serial port through pyserial, which handles COM ports natively, and the control code itself has no platform-specific parts. This page covers the few places where Windows differs from macOS and Linux, and ends with the checklist for a first connection.
4
+
5
+ The test suite runs on every pull request on both Ubuntu and Windows, so the software path is verified continuously. Real-hardware behaviour on Windows is covered by the checklist at the bottom.
6
+
7
+ ---
8
+
9
+ ## 1. Install Python and uv
10
+
11
+ 1. Python 3.10 or newer, either from python.org (tick **Add python.exe to PATH** in the installer) or
12
+
13
+ ```powershell
14
+ winget install Python.Python.3.12
15
+ ```
16
+
17
+ 2. uv:
18
+
19
+ ```powershell
20
+ winget install astral-sh.uv
21
+ ```
22
+
23
+ 3. From the repository folder, the same commands as on every other platform:
24
+
25
+ ```powershell
26
+ uv sync --group dev
27
+ uv run pytest
28
+ ```
29
+
30
+ An activated shell, if you prefer one, is `.venv\Scripts\activate` (cmd) or `.venv\Scripts\Activate.ps1` (PowerShell).
31
+
32
+ Use **Windows Terminal** or PowerShell rather than the legacy `cmd.exe` window. The scripts switch the console to ANSI mode themselves, so colours and in-place redraws work in all three, but Windows Terminal is the one that is tested.
33
+
34
+ ---
35
+
36
+ ## 2. USB drivers
37
+
38
+ Which adapter you have depends on the hand version; look it up under **Device Manager > Ports (COM & LPT)** once the hand is plugged in.
39
+
40
+ | Device | Shows up as | Driver |
41
+ |---|---|---|
42
+ | ORCA controller board (v2 hands) | two `USB Serial Device (COMx)` entries, one for the motor bus and one for the sensing link | Built into Windows 10/11 (`usbser`). Nothing to install. |
43
+ | U2D2 or other FTDI adapter (Dynamixel) | `USB Serial Port (COMx)` | FTDI VCP. Windows Update installs it automatically when the PC is online; otherwise download it from FTDI. |
44
+ | Feetech adapter, CH340 | `USB-SERIAL CH340 (COMx)` | Windows Update usually handles it; otherwise the WCH CH341SER driver. |
45
+ | Feetech adapter, CP210x | `Silicon Labs CP210x USB to UART Bridge (COMx)` | Windows Update; otherwise the Silicon Labs VCP driver. |
46
+
47
+ If a device appears with a warning icon instead of a COM number, the driver did not bind. Right-click it, choose **Update driver**, and let Windows search online.
48
+
49
+ ### FTDI latency timer (U2D2 only)
50
+
51
+ FTDI adapters buffer incoming bytes for 16 ms by default, which caps the control loop far below what the motors can do. On Linux the package lowers this itself; Windows exposes it only in Device Manager:
52
+
53
+ **Ports (COM & LPT) > USB Serial Port (COMx) > Properties > Port Settings > Advanced > Latency Timer (msec)**: set it to **1** and click OK.
54
+
55
+ The ORCA controller board and CH340/CP210x adapters have no such setting.
56
+
57
+ ---
58
+
59
+ ## 3. Find your COM port
60
+
61
+ ```powershell
62
+ uv run python -m serial.tools.list_ports -v
63
+ ```
64
+
65
+ This lists every serial port with its USB vendor and product IDs, the same information the auto-detection uses. A v2 hand shows two ports from the same board.
66
+
67
+ Port selection works exactly as on other platforms: `port: auto` in `config.yaml` finds the adapter by USB ID, and only asks you to choose when it cannot decide. On Windows that question is a numbered list rather than the arrow-key menu, because the Python builds for Windows ship without `curses`.
68
+
69
+ To pin a port by hand:
70
+
71
+ ```yaml
72
+ port: COM3
73
+ ```
74
+
75
+ ---
76
+
77
+ ## 4. Differences worth knowing
78
+
79
+ - **No permission setup.** There is no `dialout` group and nothing to `chmod`.
80
+ - **Ports are exclusive.** Windows lets only one process open a COM port at a time. A second script gets `PermissionError: Access is denied` immediately, where Linux and macOS would rely on the advisory lock the package takes. Close the other program (including a serial monitor or the Arduino IDE) and retry.
81
+ - **Port names are not paths.** `os.path.exists("COM3")` is always false. The package asks pyserial instead, so `resolve_port`, `wait_for_port` and the motor-chain configuration behave the same as on other platforms. Keep this in mind if you write your own tooling on top of orca_core.
82
+ - **Success beep** in `configure_motor_chain.py` uses the Windows system beep.
83
+
84
+ ---
85
+
86
+ ## 5. First connection checklist
87
+
88
+ Run this once per Windows machine before relying on it for calibration or assembly. Each step should behave exactly as it does on macOS or Linux.
89
+
90
+ 1. `uv run pytest` passes.
91
+ 2. Plug in the hand. `uv run python -m serial.tools.list_ports -v` shows it with a COM number and no warning icon in Device Manager.
92
+ 3. Follow **Get Started** in the README (tension, calibrate, neutral) with the hand's `config.yaml`. Auto-detection should pick the port without being asked; if it asks, the numbered list appears and works.
93
+ 4. Hands with sensing: `uv run python scripts/check_sensors.py <config.yaml>` reports the encoder stream and tactile checks as passing.
94
+ 5. Assembly stations: `uv run python scripts/configure_motor_chain.py <config.yaml>` walks through the motors, waits for each plug and unplug, and beeps on success.
95
+
96
+ If any step differs from the macOS/Linux behaviour, open an issue on the orca_core repository with the step number, the Device Manager entry for the adapter, and the full console output.
@@ -224,10 +224,10 @@ This method maps Dynamixel mode values to Feetech equivalents:
224
224
 
225
225
  | Input Mode | Feetech Mode | Behavior |
226
226
  |------------|--------------|----------|
227
- | 0 (current) | 0 (servo) | Position with torque limit |
227
+ | 0 (current) | 0 (servo) | Position under the goal-current limit |
228
228
  | 1 (velocity) | 1 (wheel) | Continuous rotation |
229
229
  | 3 (position) | 0 (servo) | Standard position |
230
- | 5 (current-based) | 0 (servo) | Position with torque limit |
230
+ | 5 (current-based) | 0 (servo) | Position under the goal-current limit |
231
231
 
232
232
  **Example:**
233
233
  ```python
@@ -328,9 +328,11 @@ write_desired_current(
328
328
  ) -> None
329
329
  ```
330
330
 
331
- Set current/torque limits for specified motors.
332
-
333
- **Note:** Feetech servos don't have direct current control. This sets the torque limit via the Goal Time register.
331
+ Set each motor's goal-current limit in mA. The value is written at once to
332
+ register 44 (goal current, 6.5 mA per unit, rounded down) and clamped to the
333
+ motor's protection current (register 28), which the client reads at connect.
334
+ This is not the 0.1 % torque limit at register 48, which is never written.
335
+ Negative or non-finite values raise `ValueError` before anything is sent.
334
336
 
335
337
  | Parameter | Type | Description |
336
338
  |-----------|------|-------------|
@@ -339,7 +341,7 @@ Set current/torque limits for specified motors.
339
341
 
340
342
  **Example:**
341
343
  ```python
342
- # Set 500mA torque limit for motors 1-3
344
+ # Limit motors 1-3 to 500 mA (76 register units)
343
345
  client.write_desired_current([1, 2, 3], np.array([500, 500, 500]))
344
346
  ```
345
347
 
@@ -29,7 +29,7 @@ Checks a specific motor by setting its operating mode and enabling torque. It th
29
29
 
30
30
  <br><strong>Args:</strong><br>
31
31
  <ul>
32
- <li><strong>--port</strong> (<strong>str</strong>, optional): The serial port for the Dynamixel client (default: "/dev/tty.usbserial-FT9MISJT").</li><br>
32
+ <li><strong>--port</strong> (<strong>str</strong>, optional): The serial port for the Dynamixel client (auto-detected when omitted; e.g. "/dev/ttyUSB0" or "COM3").</li><br>
33
33
  <li><strong>--baudrate</strong> (<strong>int</strong>, optional): The baud rate for the Dynamixel client (default: 3000000).</li><br>
34
34
  <li><strong>--motor_id</strong> (<strong>int</strong>, optional): The ID of the motor to check (default: 2).</li><br>
35
35
  <li><strong>--wrist</strong> (<strong>action</strong>, optional): If set, configures the motor for wrist operation (position control mode 3). Recommended for motor IDs 0 or 17.</li><br>
@@ -1,6 +1,6 @@
1
1
  import argparse
2
2
 
3
- from orca_core.utils.cli import add_hand_arguments, connect_hand, create_hand, shutdown_hand
3
+ from orca_core.utils.cli import add_hand_arguments, connect_hand, create_hand_from_args, shutdown_hand
4
4
 
5
5
  from demo_runner import run_demo
6
6
 
@@ -15,7 +15,7 @@ def main() -> int:
15
15
  parser.add_argument("--step-size", type=float, default=0.02)
16
16
  args = parser.parse_args()
17
17
 
18
- hand = create_hand(args.config_path, use_mock=args.mock)
18
+ hand = create_hand_from_args(args)
19
19
  try:
20
20
  connect_hand(hand)
21
21
  hand.init_joints(force_calibrate=args.mock)
@@ -1,6 +1,6 @@
1
1
  import argparse
2
2
 
3
- from orca_core.utils.cli import add_hand_arguments, connect_hand, create_hand, shutdown_hand
3
+ from orca_core.utils.cli import add_hand_arguments, connect_hand, create_hand_from_args, shutdown_hand
4
4
 
5
5
  from demo_runner import run_demo
6
6
 
@@ -15,7 +15,7 @@ def main() -> int:
15
15
  parser.add_argument("--step-size", type=float, default=0.02)
16
16
  args = parser.parse_args()
17
17
 
18
- hand = create_hand(args.config_path, use_mock=args.mock)
18
+ hand = create_hand_from_args(args)
19
19
  try:
20
20
  connect_hand(hand)
21
21
  hand.init_joints(force_calibrate=args.mock)
@@ -9,11 +9,14 @@ import yaml
9
9
  from orca_core.utils.cli import (
10
10
  add_hand_arguments,
11
11
  connect_hand,
12
- create_hand,
12
+ create_hand_from_args,
13
13
  prepare_output_dir,
14
14
  shutdown_hand,
15
15
  )
16
16
 
17
+ # Fraction of dropped captures above which the recording is not worth saving.
18
+ MAX_STALE_FRACTION = 0.1
19
+
17
20
 
18
21
  def _build_output_path(output_dir: Path, prefix: str) -> Path:
19
22
  timestamp = time.strftime("%Y%m%d_%H%M%S")
@@ -46,8 +49,9 @@ def main() -> int:
46
49
  ).strip()
47
50
  output_path = _build_output_path(output_dir, prefix)
48
51
 
49
- hand = create_hand(args.config_path, use_mock=args.mock)
52
+ hand = create_hand_from_args(args)
50
53
  replay_buffer: list[list[float]] = []
54
+ stale_captures = 0
51
55
  try:
52
56
  connect_hand(hand)
53
57
  hand.init_joints(force_calibrate=args.force_calibrate or args.mock)
@@ -59,12 +63,30 @@ def main() -> int:
59
63
  while True:
60
64
  input("Capture waypoint")
61
65
  waypoint = hand.get_joint_position().as_list(hand.config.joint_ids)
66
+ # A failed bus read leaves cached values behind, which would replay
67
+ # as real motion; drop the capture instead of recording a lie.
68
+ if not hand.last_read_ok:
69
+ stale_captures += 1
70
+ print("Motor read failed; waypoint discarded. Try again.")
71
+ continue
62
72
  replay_buffer.append([float(value) for value in waypoint])
63
73
  print(f"Captured waypoint #{len(replay_buffer)}")
64
74
  except KeyboardInterrupt:
65
75
  print("\nRecording finished.")
66
76
  finally:
67
- if replay_buffer:
77
+ total = len(replay_buffer) + stale_captures
78
+ stale_fraction = stale_captures / total if total else 0.0
79
+ if stale_captures:
80
+ print(
81
+ f"{stale_captures}/{total} captures dropped on failed motor reads "
82
+ f"({stale_fraction:.0%})."
83
+ )
84
+ if replay_buffer and stale_fraction > MAX_STALE_FRACTION:
85
+ print(
86
+ f"Refusing to save: more than {MAX_STALE_FRACTION:.0%} of captures "
87
+ "were dropped. Check the motor chain wiring and baud rate."
88
+ )
89
+ elif replay_buffer:
68
90
  payload = {
69
91
  "metadata": {
70
92
  "type": "discrete_waypoints",
@@ -0,0 +1,133 @@
1
+
2
+
3
+ import argparse
4
+ import time
5
+ from pathlib import Path
6
+
7
+ import yaml
8
+
9
+ from orca_core.utils.cli import (
10
+ add_hand_arguments,
11
+ connect_hand,
12
+ create_hand_from_args,
13
+ prepare_output_dir,
14
+ shutdown_hand,
15
+ )
16
+
17
+ # Fraction of dropped frames above which the recording is not worth saving,
18
+ # and how far the achieved rate may fall short of the requested one silently.
19
+ MAX_STALE_FRACTION = 0.1
20
+ RATE_TOLERANCE = 0.05
21
+
22
+
23
+ def _build_output_path(output_dir: Path, prefix: str) -> Path:
24
+ timestamp = time.strftime("%Y%m%d_%H%M%S")
25
+ stem = f"{prefix}_continuous_angles_{timestamp}" if prefix else f"continuous_angles_{timestamp}"
26
+ return output_dir / f"{stem}.yaml"
27
+
28
+
29
+ def main() -> int:
30
+ parser = argparse.ArgumentParser(
31
+ description="Continuously record joint angles while manually moving the hand."
32
+ )
33
+ add_hand_arguments(parser)
34
+ parser.add_argument("--frequency", type=float, default=50.0)
35
+ parser.add_argument("--duration", type=float, default=None)
36
+ parser.add_argument("--output-dir", type=str, default=None)
37
+ parser.add_argument(
38
+ "--force-calibrate",
39
+ action="store_true",
40
+ help="Run calibration even if calibration.yaml already exists.",
41
+ )
42
+ args = parser.parse_args()
43
+
44
+ output_dir = prepare_output_dir(args.output_dir)
45
+ prefix = input("Enter an optional filename prefix. Press Enter to skip: ").strip()
46
+ output_path = _build_output_path(output_dir, prefix)
47
+ interval = 1.0 / args.frequency
48
+
49
+ hand = create_hand_from_args(args)
50
+ data = {
51
+ "metadata": {
52
+ "type": "continuous",
53
+ "created_at": time.strftime("%Y%m%d_%H%M%S"),
54
+ "requested_frequency_hz": args.frequency,
55
+ "sampling_frequency_hz": args.frequency,
56
+ },
57
+ "angles": [],
58
+ }
59
+ stale_frames = 0
60
+ start_time = None
61
+ elapsed = 0.0
62
+
63
+ try:
64
+ connect_hand(hand)
65
+ hand.init_joints(force_calibrate=args.force_calibrate or args.mock)
66
+ hand.disable_torque()
67
+
68
+ data["metadata"]["joint_ids"] = hand.config.joint_ids
69
+ data["metadata"]["hand_type"] = hand.config.type
70
+
71
+ input("Press Enter to start recording. Press Ctrl+C to stop.\n")
72
+ start_time = time.monotonic()
73
+ index = 0
74
+ while True:
75
+ elapsed = time.monotonic() - start_time
76
+ if args.duration is not None and elapsed > args.duration:
77
+ break
78
+ pose = hand.get_joint_position().as_list(hand.config.joint_ids)
79
+ # A failed bus read leaves cached values behind, which would replay
80
+ # as real motion; drop the frame instead of recording a lie.
81
+ if hand.last_read_ok:
82
+ data["angles"].append([float(value) for value in pose])
83
+ else:
84
+ stale_frames += 1
85
+ print(
86
+ f"Recording... captured {len(data['angles'])} frames "
87
+ f"({stale_frames} dropped)", end="\r",
88
+ )
89
+ index += 1
90
+ remaining = start_time + index * interval - time.monotonic()
91
+ if remaining > 0:
92
+ time.sleep(remaining)
93
+ except KeyboardInterrupt:
94
+ print("\nRecording stopped by user.")
95
+ finally:
96
+ if start_time is not None:
97
+ elapsed = time.monotonic() - start_time
98
+ frames = data["angles"]
99
+ total = len(frames) + stale_frames
100
+ stale_fraction = stale_frames / total if total else 0.0
101
+
102
+ if frames and elapsed > 0:
103
+ measured = len(frames) / elapsed
104
+ data["metadata"]["sampling_frequency_hz"] = round(measured, 3)
105
+ if measured < args.frequency * (1 - RATE_TOLERANCE):
106
+ print(
107
+ f"\nWARNING: recorded at {measured:.1f} Hz, "
108
+ f"below the requested {args.frequency:.1f} Hz; "
109
+ "the file is labelled with the measured rate."
110
+ )
111
+ if stale_frames:
112
+ print(
113
+ f"\n{stale_frames}/{total} frames dropped on failed motor reads "
114
+ f"({stale_fraction:.0%})."
115
+ )
116
+
117
+ if not frames:
118
+ print("Nothing recorded; no file written.")
119
+ elif stale_fraction > MAX_STALE_FRACTION:
120
+ print(
121
+ f"Refusing to save: more than {MAX_STALE_FRACTION:.0%} of frames "
122
+ "were dropped. Check the motor chain wiring and baud rate."
123
+ )
124
+ else:
125
+ output_path.write_text(yaml.safe_dump(data, sort_keys=False), encoding="utf-8")
126
+ print(f"Saved {len(frames)} frames to {output_path}")
127
+ shutdown_hand(hand)
128
+
129
+ return 0
130
+
131
+
132
+ if __name__ == "__main__":
133
+ raise SystemExit(main())