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.
- robot_models/__init__.py +18 -0
- robot_models/actuators/__init__.py +1 -0
- robot_models/actuators/rungs/README.md +24 -0
- robot_models/actuators/rungs/coulomb_viscous/README.md +61 -0
- robot_models/actuators/rungs/coulomb_viscous/model.js +14 -0
- robot_models/actuators/rungs/coulomb_viscous/model.json +102 -0
- robot_models/actuators/rungs/coulomb_viscous/model.py +24 -0
- robot_models/actuators/rungs/datasheet/README.md +65 -0
- robot_models/actuators/rungs/datasheet/model.js +14 -0
- robot_models/actuators/rungs/datasheet/model.json +138 -0
- robot_models/actuators/rungs/datasheet/model.py +24 -0
- robot_models/actuators/rungs/dcmotor/README.md +63 -0
- robot_models/actuators/rungs/dcmotor/model.json +163 -0
- robot_models/actuators/rungs/ideal/README.md +60 -0
- robot_models/actuators/rungs/ideal/model.js +6 -0
- robot_models/actuators/rungs/ideal/model.json +90 -0
- robot_models/actuators/rungs/ideal/model.py +13 -0
- robot_models/actuators/rungs/load/README.md +65 -0
- robot_models/actuators/rungs/load/model.js +15 -0
- robot_models/actuators/rungs/load/model.json +117 -0
- robot_models/actuators/rungs/load/model.py +25 -0
- robot_models/actuators/rungs/lugre/README.md +72 -0
- robot_models/actuators/rungs/lugre/model.js +24 -0
- robot_models/actuators/rungs/lugre/model.json +164 -0
- robot_models/actuators/rungs/lugre/model.py +30 -0
- robot_models/actuators/rungs/ripple/README.md +64 -0
- robot_models/actuators/rungs/ripple/model.js +17 -0
- robot_models/actuators/rungs/ripple/model.json +119 -0
- robot_models/actuators/rungs/ripple/model.py +27 -0
- robot_models/actuators/rungs/stribeck/README.md +65 -0
- robot_models/actuators/rungs/stribeck/model.js +17 -0
- robot_models/actuators/rungs/stribeck/model.json +126 -0
- robot_models/actuators/rungs/stribeck/model.py +28 -0
- robot_models/actuators/servo/README.md +278 -0
- robot_models/actuators/servo/__init__.py +7 -0
- robot_models/actuators/servo/bldc/README.md +186 -0
- robot_models/actuators/servo/bldc/__init__.py +5 -0
- robot_models/actuators/servo/bldc/bldc_motor.py +93 -0
- robot_models/actuators/servo/bldc/ladder.py +268 -0
- robot_models/actuators/servo/foc_controller/README.md +127 -0
- robot_models/actuators/servo/foc_controller/__init__.py +3 -0
- robot_models/actuators/servo/foc_controller/ladder.py +207 -0
- robot_models/actuators/servo/gearbox/README.md +148 -0
- robot_models/actuators/servo/gearbox/__init__.py +5 -0
- robot_models/actuators/servo/gearbox/gearbox.py +36 -0
- robot_models/actuators/servo/gearbox/ladder.py +214 -0
- robot_models/actuators/servo/integrated_servo.py +33 -0
- robot_models/actuators/servo/ladder.py +593 -0
- robot_models/arms/__init__.py +1 -0
- robot_models/arms/rigid_body_chain/README.md +151 -0
- robot_models/arms/rigid_body_chain/__init__.py +3 -0
- robot_models/arms/rigid_body_chain/ladder.py +228 -0
- robot_models/conveyors/__init__.py +1 -0
- robot_models/conveyors/conveyor/README.md +140 -0
- robot_models/conveyors/conveyor/__init__.py +1 -0
- robot_models/conveyors/conveyor/ladder.py +203 -0
- robot_models/datasheet/__init__.py +56 -0
- robot_models/datasheet/datasheet.py +355 -0
- robot_models/datasheet/literal.py +144 -0
- robot_models/datasheet/source.py +328 -0
- robot_models/datasheet/stated.py +135 -0
- robot_models/datasheet/units.py +57 -0
- robot_models/end_effectors/__init__.py +1 -0
- robot_models/end_effectors/gripper/README.md +112 -0
- robot_models/end_effectors/gripper/__init__.py +3 -0
- robot_models/end_effectors/gripper/ladder.py +150 -0
- robot_models/homing/__init__.py +38 -0
- robot_models/homing/cad_bundle.py +206 -0
- robot_models/homing/contact.py +201 -0
- robot_models/homing/fit.py +126 -0
- robot_models/homing/metrics.py +237 -0
- robot_models/homing/protocols.py +72 -0
- robot_models/homing/types.py +256 -0
- robot_models/ladder.py +645 -0
- robot_models/markers/__init__.py +1 -0
- robot_models/markers/aruco_marker/README.md +92 -0
- robot_models/markers/aruco_marker/__init__.py +2 -0
- robot_models/markers/aruco_marker/ladder.py +142 -0
- robot_models/references.py +429 -0
- robot_models/sensors/__init__.py +1 -0
- robot_models/sensors/camera/README.md +118 -0
- robot_models/sensors/camera/__init__.py +3 -0
- robot_models/sensors/camera/ladder.py +108 -0
- robot_models/sensors/encoder/README.md +103 -0
- robot_models/sensors/encoder/__init__.py +5 -0
- robot_models/sensors/encoder/ladder.py +133 -0
- robot_models/sensors/hyperspectral_camera/README.md +107 -0
- robot_models/sensors/hyperspectral_camera/__init__.py +1 -0
- robot_models/sensors/hyperspectral_camera/ladder.py +151 -0
- robot_models/sensors/rgbd/README.md +113 -0
- robot_models/sensors/rgbd/__init__.py +5 -0
- robot_models/sensors/rgbd/ladder.py +113 -0
- robot_models_lib-0.2.0.dist-info/METADATA +143 -0
- robot_models_lib-0.2.0.dist-info/RECORD +96 -0
- robot_models_lib-0.2.0.dist-info/WHEEL +4 -0
- 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)
|