robot-models-lib 0.2.0__py3-none-any.whl

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 (96) hide show
  1. robot_models/__init__.py +18 -0
  2. robot_models/actuators/__init__.py +1 -0
  3. robot_models/actuators/rungs/README.md +24 -0
  4. robot_models/actuators/rungs/coulomb_viscous/README.md +61 -0
  5. robot_models/actuators/rungs/coulomb_viscous/model.js +14 -0
  6. robot_models/actuators/rungs/coulomb_viscous/model.json +102 -0
  7. robot_models/actuators/rungs/coulomb_viscous/model.py +24 -0
  8. robot_models/actuators/rungs/datasheet/README.md +65 -0
  9. robot_models/actuators/rungs/datasheet/model.js +14 -0
  10. robot_models/actuators/rungs/datasheet/model.json +138 -0
  11. robot_models/actuators/rungs/datasheet/model.py +24 -0
  12. robot_models/actuators/rungs/dcmotor/README.md +63 -0
  13. robot_models/actuators/rungs/dcmotor/model.json +163 -0
  14. robot_models/actuators/rungs/ideal/README.md +60 -0
  15. robot_models/actuators/rungs/ideal/model.js +6 -0
  16. robot_models/actuators/rungs/ideal/model.json +90 -0
  17. robot_models/actuators/rungs/ideal/model.py +13 -0
  18. robot_models/actuators/rungs/load/README.md +65 -0
  19. robot_models/actuators/rungs/load/model.js +15 -0
  20. robot_models/actuators/rungs/load/model.json +117 -0
  21. robot_models/actuators/rungs/load/model.py +25 -0
  22. robot_models/actuators/rungs/lugre/README.md +72 -0
  23. robot_models/actuators/rungs/lugre/model.js +24 -0
  24. robot_models/actuators/rungs/lugre/model.json +164 -0
  25. robot_models/actuators/rungs/lugre/model.py +30 -0
  26. robot_models/actuators/rungs/ripple/README.md +64 -0
  27. robot_models/actuators/rungs/ripple/model.js +17 -0
  28. robot_models/actuators/rungs/ripple/model.json +119 -0
  29. robot_models/actuators/rungs/ripple/model.py +27 -0
  30. robot_models/actuators/rungs/stribeck/README.md +65 -0
  31. robot_models/actuators/rungs/stribeck/model.js +17 -0
  32. robot_models/actuators/rungs/stribeck/model.json +126 -0
  33. robot_models/actuators/rungs/stribeck/model.py +28 -0
  34. robot_models/actuators/servo/README.md +278 -0
  35. robot_models/actuators/servo/__init__.py +7 -0
  36. robot_models/actuators/servo/bldc/README.md +186 -0
  37. robot_models/actuators/servo/bldc/__init__.py +5 -0
  38. robot_models/actuators/servo/bldc/bldc_motor.py +93 -0
  39. robot_models/actuators/servo/bldc/ladder.py +268 -0
  40. robot_models/actuators/servo/foc_controller/README.md +127 -0
  41. robot_models/actuators/servo/foc_controller/__init__.py +3 -0
  42. robot_models/actuators/servo/foc_controller/ladder.py +207 -0
  43. robot_models/actuators/servo/gearbox/README.md +148 -0
  44. robot_models/actuators/servo/gearbox/__init__.py +5 -0
  45. robot_models/actuators/servo/gearbox/gearbox.py +36 -0
  46. robot_models/actuators/servo/gearbox/ladder.py +214 -0
  47. robot_models/actuators/servo/integrated_servo.py +33 -0
  48. robot_models/actuators/servo/ladder.py +593 -0
  49. robot_models/arms/__init__.py +1 -0
  50. robot_models/arms/rigid_body_chain/README.md +151 -0
  51. robot_models/arms/rigid_body_chain/__init__.py +3 -0
  52. robot_models/arms/rigid_body_chain/ladder.py +228 -0
  53. robot_models/conveyors/__init__.py +1 -0
  54. robot_models/conveyors/conveyor/README.md +140 -0
  55. robot_models/conveyors/conveyor/__init__.py +1 -0
  56. robot_models/conveyors/conveyor/ladder.py +203 -0
  57. robot_models/datasheet/__init__.py +56 -0
  58. robot_models/datasheet/datasheet.py +355 -0
  59. robot_models/datasheet/literal.py +144 -0
  60. robot_models/datasheet/source.py +328 -0
  61. robot_models/datasheet/stated.py +135 -0
  62. robot_models/datasheet/units.py +57 -0
  63. robot_models/end_effectors/__init__.py +1 -0
  64. robot_models/end_effectors/gripper/README.md +112 -0
  65. robot_models/end_effectors/gripper/__init__.py +3 -0
  66. robot_models/end_effectors/gripper/ladder.py +150 -0
  67. robot_models/homing/__init__.py +38 -0
  68. robot_models/homing/cad_bundle.py +206 -0
  69. robot_models/homing/contact.py +201 -0
  70. robot_models/homing/fit.py +126 -0
  71. robot_models/homing/metrics.py +237 -0
  72. robot_models/homing/protocols.py +72 -0
  73. robot_models/homing/types.py +256 -0
  74. robot_models/ladder.py +645 -0
  75. robot_models/markers/__init__.py +1 -0
  76. robot_models/markers/aruco_marker/README.md +92 -0
  77. robot_models/markers/aruco_marker/__init__.py +2 -0
  78. robot_models/markers/aruco_marker/ladder.py +142 -0
  79. robot_models/references.py +429 -0
  80. robot_models/sensors/__init__.py +1 -0
  81. robot_models/sensors/camera/README.md +118 -0
  82. robot_models/sensors/camera/__init__.py +3 -0
  83. robot_models/sensors/camera/ladder.py +108 -0
  84. robot_models/sensors/encoder/README.md +103 -0
  85. robot_models/sensors/encoder/__init__.py +5 -0
  86. robot_models/sensors/encoder/ladder.py +133 -0
  87. robot_models/sensors/hyperspectral_camera/README.md +107 -0
  88. robot_models/sensors/hyperspectral_camera/__init__.py +1 -0
  89. robot_models/sensors/hyperspectral_camera/ladder.py +151 -0
  90. robot_models/sensors/rgbd/README.md +113 -0
  91. robot_models/sensors/rgbd/__init__.py +5 -0
  92. robot_models/sensors/rgbd/ladder.py +113 -0
  93. robot_models_lib-0.2.0.dist-info/METADATA +143 -0
  94. robot_models_lib-0.2.0.dist-info/RECORD +96 -0
  95. robot_models_lib-0.2.0.dist-info/WHEEL +4 -0
  96. robot_models_lib-0.2.0.dist-info/licenses/LICENSE +21 -0
@@ -0,0 +1,256 @@
1
+ """The homing stop core's frozen types (docs/peps/0001-homing-stop-core.md).
2
+
3
+ Every angle is radians in the URDF joint coordinate (zero = the CAD export pose, sign per the
4
+ URDF ``<axis>``). Degrees are for display only; convert at the edge.
5
+
6
+ Sign convention (the same as ``gear_backlash``): ``twist = q_link - q_motor``, both output
7
+ referred. Pressing a joint into its ``side`` stop (-1 lower, +1 upper) with torque ``T`` pins the
8
+ link on the stop and leaves the motor *past* it by ``side * (gap / 2 + compliance * T)``.
9
+
10
+ The zero sits at the centre of the gap (``gear_backlash`` ``zero="center"``): an unloaded link
11
+ rests at ``q_motor`` on average, so ``raw + offset`` is the joint angle a controller should use.
12
+ """
13
+
14
+ from __future__ import annotations
15
+
16
+ import math
17
+ from dataclasses import dataclass
18
+ from typing import Literal
19
+
20
+ from robot_msgs import Msg
21
+
22
+ LOWER = -1
23
+ UPPER = +1
24
+ SIDES = (LOWER, UPPER)
25
+
26
+ BacklashKind = Literal["B0", "B1", "B2"]
27
+ BACKLASH_KINDS: tuple[str, ...] = ("B0", "B1", "B2")
28
+ STOP_BASES = ("cad", "typed", "measured")
29
+
30
+
31
+ def _check_side(side: int) -> None:
32
+ if side not in SIDES:
33
+ raise ValueError(f"side must be -1 (lower) or +1 (upper), not {side!r}")
34
+
35
+
36
+ def _finite(name: str, value: float) -> None:
37
+ if not isinstance(value, (int, float)) or not math.isfinite(value):
38
+ raise ValueError(f"{name} must be a finite number, not {value!r}")
39
+
40
+
41
+ # --------------------------------------------------------------------------------------------
42
+ # where the stops are
43
+ # --------------------------------------------------------------------------------------------
44
+
45
+
46
+ @dataclass(frozen=True, eq=False, repr=False)
47
+ class StopSide(Msg):
48
+ """One side of one joint's hard stop.
49
+
50
+ ``q_rad`` is the joint angle at first contact of the stop pair; ``None`` means the geometry
51
+ never stops the joint that way (a passive loop joint, a free-turning axis) -- never a
52
+ silent 0. ``basis`` says where the number came from: ``cad`` (an exporter sweep),
53
+ ``typed`` (Zach typed it) or ``measured`` (a homing rung found it).
54
+ """
55
+
56
+ joint: str
57
+ side: int
58
+ q_rad: float | None
59
+ basis: str = "cad"
60
+ source: str = ""
61
+ pair: tuple[str, ...] = ()
62
+
63
+ def __post_init__(self) -> None:
64
+ _check_side(self.side)
65
+ if self.q_rad is not None:
66
+ _finite("q_rad", self.q_rad)
67
+ if self.basis not in STOP_BASES:
68
+ raise ValueError(f"basis must be one of {STOP_BASES}, not {self.basis!r}")
69
+
70
+ @property
71
+ def q_deg(self) -> float | None:
72
+ return None if self.q_rad is None else math.degrees(self.q_rad)
73
+
74
+
75
+ @dataclass(frozen=True, eq=False, repr=False)
76
+ class StopMap(Msg):
77
+ """Every stop side of one robot, from one source."""
78
+
79
+ sides: tuple[StopSide, ...]
80
+ source: str = ""
81
+
82
+ def __post_init__(self) -> None:
83
+ seen = set()
84
+ for stop in self.sides:
85
+ key = (stop.joint, stop.side)
86
+ if key in seen:
87
+ raise ValueError(f"duplicate stop side {key}")
88
+ seen.add(key)
89
+
90
+ @property
91
+ def joints(self) -> tuple[str, ...]:
92
+ return tuple(dict.fromkeys(stop.joint for stop in self.sides))
93
+
94
+ def get(self, joint: str, side: int) -> StopSide | None:
95
+ _check_side(side)
96
+ for stop in self.sides:
97
+ if stop.joint == joint and stop.side == side:
98
+ return stop
99
+ return None
100
+
101
+ def q_rad(self, joint: str, side: int) -> float | None:
102
+ stop = self.get(joint, side)
103
+ return None if stop is None else stop.q_rad
104
+
105
+ def span_rad(self, joint: str) -> float | None:
106
+ """Upper minus lower stop, or None unless both sides stop."""
107
+ lower, upper = self.q_rad(joint, LOWER), self.q_rad(joint, UPPER)
108
+ return None if lower is None or upper is None else upper - lower
109
+
110
+
111
+ # --------------------------------------------------------------------------------------------
112
+ # backlash: the B0 / B1 / B2 ladder
113
+ # --------------------------------------------------------------------------------------------
114
+
115
+
116
+ @dataclass(frozen=True, eq=False, repr=False)
117
+ class BacklashModel(Msg):
118
+ """One drive's lost motion between motor and link, output referred.
119
+
120
+ ``B0`` none: link = motor (``gap_rad = compliance = 0``).
121
+ ``B1`` dead zone: ``gear_backlash.BacklashModel(method="deadzone", zero="center")`` in its
122
+ rigid limit -- the link floats ``+-gap/2`` about the motor and carries no torque
123
+ inside the gap; outside it nothing gives.
124
+ ``B2`` elastic: the same dead zone plus a series compliance ``1/k``. Without an output
125
+ sensor the gear mesh, the stop and the structure are not separable, so
126
+ ``compliance_rad_per_nm`` is their sum -- all the zero needs.
127
+ """
128
+
129
+ kind: str = "B0"
130
+ gap_rad: float = 0.0
131
+ compliance_rad_per_nm: float = 0.0
132
+
133
+ def __post_init__(self) -> None:
134
+ if self.kind not in BACKLASH_KINDS:
135
+ raise ValueError(f"kind must be one of {BACKLASH_KINDS}, not {self.kind!r}")
136
+ _finite("gap_rad", self.gap_rad)
137
+ _finite("compliance_rad_per_nm", self.compliance_rad_per_nm)
138
+ if self.gap_rad < 0 or self.compliance_rad_per_nm < 0:
139
+ raise ValueError("gap_rad and compliance_rad_per_nm must be >= 0")
140
+ if self.kind == "B0" and (self.gap_rad or self.compliance_rad_per_nm):
141
+ raise ValueError("B0 has no gap and no compliance")
142
+ if self.kind == "B1" and self.compliance_rad_per_nm:
143
+ raise ValueError("B1 is rigid outside the gap: use B2 for a compliance")
144
+
145
+ def motor_past_link_rad(self, side: int, torque_nm: float) -> float:
146
+ """``q_motor - q_link`` while the link is pressed into its ``side`` stop with ``torque_nm``."""
147
+ _check_side(side)
148
+ if torque_nm < 0:
149
+ raise ValueError("torque_nm is the magnitude pressing into the stop: >= 0")
150
+ return side * (0.5 * self.gap_rad + self.compliance_rad_per_nm * torque_nm)
151
+
152
+
153
+ @dataclass(frozen=True, eq=False, repr=False)
154
+ class JointBacklash(Msg):
155
+ """One joint's backlash model and what was actually observed.
156
+
157
+ A flag that is False means that part of the model is a prior (or 0 for B0), not a
158
+ measurement: a page shows it as '--', never as an identified 0.
159
+ """
160
+
161
+ joint: str
162
+ model: BacklashModel
163
+ gap_observable: bool = False
164
+ compliance_observable: bool = False
165
+ source: str = ""
166
+
167
+
168
+ @dataclass(frozen=True, eq=False, repr=False)
169
+ class BacklashTable(Msg):
170
+ """The stored per-joint backlash ``home()`` uses on every boot; ``identify_backlash()`` writes it."""
171
+
172
+ entries: tuple[JointBacklash, ...] = ()
173
+
174
+ def __post_init__(self) -> None:
175
+ names = [entry.joint for entry in self.entries]
176
+ if len(names) != len(set(names)):
177
+ raise ValueError(f"duplicate joints in BacklashTable: {names}")
178
+
179
+ def get(self, joint: str) -> JointBacklash | None:
180
+ for entry in self.entries:
181
+ if entry.joint == joint:
182
+ return entry
183
+ return None
184
+
185
+
186
+ # --------------------------------------------------------------------------------------------
187
+ # what a stall gives, and what homing returns
188
+ # --------------------------------------------------------------------------------------------
189
+
190
+
191
+ @dataclass(frozen=True, eq=False, repr=False)
192
+ class StallEvidence(Msg):
193
+ """One settled stall of one joint against one stop.
194
+
195
+ ``motor_raw_rad`` is the motor-side encoder, output referred, in the encoder's own frame
196
+ (before any zero). ``torque_nm`` is the magnitude pressing into the stop.
197
+ """
198
+
199
+ joint: str
200
+ side: int
201
+ torque_nm: float
202
+ motor_raw_rad: float
203
+ rung: str = "kinematic"
204
+ settled: bool = True
205
+
206
+ def __post_init__(self) -> None:
207
+ _check_side(self.side)
208
+ _finite("torque_nm", self.torque_nm)
209
+ _finite("motor_raw_rad", self.motor_raw_rad)
210
+ if self.torque_nm < 0:
211
+ raise ValueError("torque_nm is the magnitude pressing into the stop: >= 0")
212
+
213
+
214
+ @dataclass(frozen=True, eq=False, repr=False)
215
+ class JointZero(Msg):
216
+ """One joint's zero: ``q_joint = motor_raw_rad + offset_rad``.
217
+
218
+ ``spread_rad`` is max minus min of the per-stall offsets (0 for a single stall): the repeat
219
+ check, never the error against truth.
220
+ """
221
+
222
+ joint: str
223
+ offset_rad: float
224
+ spread_rad: float = 0.0
225
+ n_evidence: int = 0
226
+ sides: tuple[int, ...] = ()
227
+
228
+ @property
229
+ def offset_deg(self) -> float:
230
+ return math.degrees(self.offset_rad)
231
+
232
+
233
+ @dataclass(frozen=True, eq=False, repr=False)
234
+ class HomingResult(Msg):
235
+ """What a homing run concludes, plus everything needed to re-derive it without moving.
236
+
237
+ ``corrected(table)`` re-fits the same stalls with a new BacklashTable (a fresh calibration
238
+ re-derives the zero with no motion).
239
+ """
240
+
241
+ zeros: tuple[JointZero, ...]
242
+ backlash: BacklashTable
243
+ stops: StopMap
244
+ evidence: tuple[StallEvidence, ...] = ()
245
+ rung: str = "kinematic"
246
+
247
+ def zero(self, joint: str) -> JointZero | None:
248
+ for item in self.zeros:
249
+ if item.joint == joint:
250
+ return item
251
+ return None
252
+
253
+ def corrected(self, table: BacklashTable) -> HomingResult:
254
+ from robot_models.homing.fit import fit # noqa: PLC0415 -- fit imports this module
255
+
256
+ return fit(self.evidence, self.stops, table=table, rung=self.rung)