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,207 @@
|
|
|
1
|
+
"""The ladder of a field-oriented-control (FOC) motor drive board: the electronics that turn a torque command into
|
|
2
|
+
the q-axis current in a motor's windings.
|
|
3
|
+
|
|
4
|
+
from robot_models.actuators.servo.foc_controller.ladder import LADDER
|
|
5
|
+
LADDER.parameters("M2.ceiling_heat") # what the voltage-ceiling and heating rung needs, M1's names included
|
|
6
|
+
|
|
7
|
+
Rungs: M0 the commanded current as is, M1 the transport delay and first-order current loop, M2 the voltage ceiling and
|
|
8
|
+
the board's heating (and M2.wear, the board's cooling ageing with hours), M6 the grey-box residual, M7 the learned net.
|
|
9
|
+
A deployment's own settings (torque cap, host loop rate, modulation-limit setting) are not on a rung: see `deployment`.
|
|
10
|
+
|
|
11
|
+
Spec: PEP 0004 §5.5 and §6.4. Sources: sim2real's `driver` card (its rungs, parameters and equations).
|
|
12
|
+
"""
|
|
13
|
+
|
|
14
|
+
from robot_models import references
|
|
15
|
+
from robot_models.ladder import Alias, DeploymentOnly, Ladder, Packed, Parameter, Rung, Wear
|
|
16
|
+
|
|
17
|
+
# --- the vocabulary, grouped by the rung that first reads each name ---------------------------------------------------
|
|
18
|
+
|
|
19
|
+
# M1.delay_loop: the command's path to the current.
|
|
20
|
+
COMMAND_LATENCY = Parameter(
|
|
21
|
+
name="command_latency",
|
|
22
|
+
unit="s",
|
|
23
|
+
shape="scalar",
|
|
24
|
+
definition="Time from a command reaching the drive to its first response: the transport delay before the "
|
|
25
|
+
"current loop.",
|
|
26
|
+
)
|
|
27
|
+
CURRENT_LOOP_BANDWIDTH = Parameter(
|
|
28
|
+
name="current_loop_bandwidth",
|
|
29
|
+
unit="Hz",
|
|
30
|
+
shape="scalar",
|
|
31
|
+
definition="The drive's closed-loop current (torque) bandwidth: the corner of its first-order current loop.",
|
|
32
|
+
)
|
|
33
|
+
TORQUE_SCALE = Parameter(
|
|
34
|
+
name="torque_scale",
|
|
35
|
+
unit="",
|
|
36
|
+
shape="scalar",
|
|
37
|
+
definition="Torque the drive delivers over the torque it was commanded: its torque-constant calibration error.",
|
|
38
|
+
)
|
|
39
|
+
|
|
40
|
+
# M2.ceiling_heat: what the bus can supply and what the board does with the losses.
|
|
41
|
+
VOLTAGE_AVAILABLE = Parameter(
|
|
42
|
+
name="voltage_available",
|
|
43
|
+
unit="V",
|
|
44
|
+
shape="scalar",
|
|
45
|
+
definition="The largest phase voltage the drive can apply: its bus voltage times its modulation limit.",
|
|
46
|
+
)
|
|
47
|
+
BOARD_THERMAL_RESISTANCE = Parameter(
|
|
48
|
+
name="board_thermal_resistance",
|
|
49
|
+
unit="K/W",
|
|
50
|
+
shape="scalar",
|
|
51
|
+
definition="The board's temperature rise per watt it dissipates.",
|
|
52
|
+
)
|
|
53
|
+
BOARD_THERMAL_TIME_CONSTANT = Parameter(
|
|
54
|
+
name="board_thermal_time_constant",
|
|
55
|
+
unit="s",
|
|
56
|
+
shape="scalar",
|
|
57
|
+
definition="Time constant of the board temperature's first-order rise.",
|
|
58
|
+
)
|
|
59
|
+
|
|
60
|
+
# M2.wear: how the board's cooling ages.
|
|
61
|
+
BOARD_THERMAL_GROWTH = Parameter(
|
|
62
|
+
name="board_thermal_growth",
|
|
63
|
+
unit="K/W/h",
|
|
64
|
+
shape="scalar",
|
|
65
|
+
definition="How fast board_thermal_resistance grows per deployment hour (its cooling ageing).",
|
|
66
|
+
)
|
|
67
|
+
|
|
68
|
+
VOCABULARY = (
|
|
69
|
+
COMMAND_LATENCY,
|
|
70
|
+
CURRENT_LOOP_BANDWIDTH,
|
|
71
|
+
TORQUE_SCALE,
|
|
72
|
+
VOLTAGE_AVAILABLE,
|
|
73
|
+
BOARD_THERMAL_RESISTANCE,
|
|
74
|
+
BOARD_THERMAL_TIME_CONSTANT,
|
|
75
|
+
BOARD_THERMAL_GROWTH,
|
|
76
|
+
)
|
|
77
|
+
|
|
78
|
+
# --- the rungs, M0 upward ---------------------------------------------------------------------------------------------
|
|
79
|
+
|
|
80
|
+
RUNGS = (
|
|
81
|
+
Rung(
|
|
82
|
+
level=0,
|
|
83
|
+
name="ideal",
|
|
84
|
+
title="An ideal drive: the commanded current",
|
|
85
|
+
base=None,
|
|
86
|
+
equation="i_q = i_cmd (a deployment's torque cap clamps it)",
|
|
87
|
+
references=(references.KRISHNAN_2010,),
|
|
88
|
+
# WHY no adds: the cap that clamps i_cmd is the deployment's (torque_cap_nm, see `deployment`), never the
|
|
89
|
+
# type's.
|
|
90
|
+
),
|
|
91
|
+
Rung(
|
|
92
|
+
level=1,
|
|
93
|
+
name="delay_loop",
|
|
94
|
+
title="Transport delay, a first-order current loop and its torque scale",
|
|
95
|
+
base="M0.ideal",
|
|
96
|
+
adds=("command_latency", "current_loop_bandwidth", "torque_scale"),
|
|
97
|
+
equation="i_q = torque_scale·LPF(current_loop_bandwidth)[i_cmd(t − command_latency)]",
|
|
98
|
+
references=(references.KRISHNAN_2010,),
|
|
99
|
+
),
|
|
100
|
+
Rung(
|
|
101
|
+
level=2,
|
|
102
|
+
name="ceiling_heat",
|
|
103
|
+
title="Voltage ceiling and board heating",
|
|
104
|
+
base="M1.delay_loop",
|
|
105
|
+
adds=("voltage_available", "board_thermal_resistance", "board_thermal_time_constant"),
|
|
106
|
+
equation="M1.delay_loop clamped to the voltage ceiling (voltage_available − ω·kt/1.5)/R of the motor it "
|
|
107
|
+
"drives; board_thermal_time_constant·dΔT/dt = board_thermal_resistance·P_loss − ΔT, ΔT the "
|
|
108
|
+
"board's rise over ambient",
|
|
109
|
+
references=(references.KRAUSE_2013, references.KRISHNAN_2010),
|
|
110
|
+
# WHY kt and R are not added here: they are the motor's own (bldc_motor), read through the servo rung that
|
|
111
|
+
# composes this one; ω is the rotor speed and the 1.5 is sim2real's driver-card form of the back-EMF term.
|
|
112
|
+
# WHY ΔT, not T: board_thermal_resistance is a rise per watt, so the state is the rise over ambient, as the
|
|
113
|
+
# winding's is on the servo's M5.envelope and the motor's M5.dcmotor (PEP 0004 amendment 1).
|
|
114
|
+
),
|
|
115
|
+
Rung(
|
|
116
|
+
level=2,
|
|
117
|
+
name="wear",
|
|
118
|
+
title="Board cooling that ages with hours",
|
|
119
|
+
base="M2.ceiling_heat",
|
|
120
|
+
adds=("board_thermal_growth",),
|
|
121
|
+
wears=(
|
|
122
|
+
Wear(
|
|
123
|
+
parameter="board_thermal_resistance",
|
|
124
|
+
usage="deployment hours",
|
|
125
|
+
usage_unit="h",
|
|
126
|
+
law="linear",
|
|
127
|
+
rate="board_thermal_growth",
|
|
128
|
+
),
|
|
129
|
+
),
|
|
130
|
+
equation="board_thermal_resistance(h) = board_thermal_resistance + board_thermal_growth·h",
|
|
131
|
+
references=(references.LU_MEEKER_1993, references.MEEKER_1998),
|
|
132
|
+
),
|
|
133
|
+
Rung(
|
|
134
|
+
level=6,
|
|
135
|
+
name="residual",
|
|
136
|
+
title="Grey-box residual on M2.wear",
|
|
137
|
+
base="M2.wear",
|
|
138
|
+
kind="residual",
|
|
139
|
+
equation="M2.wear + an MLP residual q-current from 3 samples of current command, rotor speed and bus voltage",
|
|
140
|
+
references=(references.NGUYEN_TUONG_2010,),
|
|
141
|
+
),
|
|
142
|
+
Rung(
|
|
143
|
+
level=7,
|
|
144
|
+
name="learned",
|
|
145
|
+
title="Black-box network",
|
|
146
|
+
base=None,
|
|
147
|
+
kind="learned",
|
|
148
|
+
equation="an MLP over 3 samples of current command, rotor speed, bus voltage and board temperature → "
|
|
149
|
+
"q-current",
|
|
150
|
+
references=(references.HWANGBO_2019,),
|
|
151
|
+
),
|
|
152
|
+
)
|
|
153
|
+
|
|
154
|
+
# --- other names, packed names and what a deployment sets -------------------------------------------------------------
|
|
155
|
+
|
|
156
|
+
ALIASES = (
|
|
157
|
+
Alias(
|
|
158
|
+
name="command_delay_s",
|
|
159
|
+
canonical="command_latency",
|
|
160
|
+
note="The twin's transport delay; the registry's command_latency is measured host to first response over a "
|
|
161
|
+
"named bus.",
|
|
162
|
+
),
|
|
163
|
+
Alias(
|
|
164
|
+
name="current_loop_hz",
|
|
165
|
+
canonical="current_loop_bandwidth",
|
|
166
|
+
note="The twin's first-order loop corner, which is its −3 dB bandwidth.",
|
|
167
|
+
),
|
|
168
|
+
Alias(name="voltage_available_v", canonical="voltage_available"),
|
|
169
|
+
Alias(name="board_thermal_growth_per_h", canonical="board_thermal_growth"),
|
|
170
|
+
)
|
|
171
|
+
|
|
172
|
+
PACKED = (
|
|
173
|
+
Packed(
|
|
174
|
+
name="board_thermal",
|
|
175
|
+
holds=("board_thermal_resistance", "board_thermal_time_constant"),
|
|
176
|
+
ordered=True,
|
|
177
|
+
note="sim2real's driver card: (K/W, s).",
|
|
178
|
+
),
|
|
179
|
+
)
|
|
180
|
+
|
|
181
|
+
DEPLOYMENT = (
|
|
182
|
+
DeploymentOnly(
|
|
183
|
+
name="torque_cap_nm",
|
|
184
|
+
role="config",
|
|
185
|
+
why="The runner's torque cap: the deployment's config.",
|
|
186
|
+
),
|
|
187
|
+
DeploymentOnly(
|
|
188
|
+
name="telemetry_rate_hz",
|
|
189
|
+
role="config",
|
|
190
|
+
why="The host loop's rate: the deployment's config.",
|
|
191
|
+
),
|
|
192
|
+
DeploymentOnly(
|
|
193
|
+
name="max_voltage_factor",
|
|
194
|
+
role="config",
|
|
195
|
+
why="The firmware's modulation-limit setting: the deployment's config.",
|
|
196
|
+
),
|
|
197
|
+
)
|
|
198
|
+
|
|
199
|
+
LADDER = Ladder(
|
|
200
|
+
type="foc_controller",
|
|
201
|
+
title="A field-oriented-control motor drive board.",
|
|
202
|
+
vocabulary=VOCABULARY,
|
|
203
|
+
rungs=RUNGS,
|
|
204
|
+
aliases=ALIASES,
|
|
205
|
+
packed=PACKED,
|
|
206
|
+
deployment=DEPLOYMENT,
|
|
207
|
+
)
|
|
@@ -0,0 +1,148 @@
|
|
|
1
|
+
> **Generated file.** Written by [`tools/make_type_docs.py`](../../../../../tools/make_type_docs.py) from this folder's [`ladder.py`](ladder.py): edit the ladder, not this file, then run `python tools/make_type_docs.py` from the repository root.
|
|
2
|
+
|
|
3
|
+
# gearbox
|
|
4
|
+
|
|
5
|
+
A gear stage between a motor and its load.
|
|
6
|
+
|
|
7
|
+
**8 rungs** · 17 parameters · 10 aliases · 0 packed names · 0 deployment-only names · folder `actuators/servo/gearbox/` · datasheet class [`Gearbox`](gearbox.py), whose typed fields rung `M1.datasheet` states.
|
|
8
|
+
|
|
9
|
+
In code: `ladders()["gearbox"]` from [`robot_models.ladder`](../../../ladder.py). Every type: [docs/TYPES.md](../../../../../docs/TYPES.md). Spec: [PEP 0004](../../../../../docs/peps/0004-model-ladders-by-type.md).
|
|
10
|
+
Projects the notes below name, and what they are: [MuJoCo](../../../../../docs/TYPES.md#name-mujoco), [robotparts](../../../../../docs/TYPES.md#name-robotparts), [sim2real](../../../../../docs/TYPES.md#name-sim2real).
|
|
11
|
+
|
|
12
|
+
## About
|
|
13
|
+
|
|
14
|
+
From the docstring of [`ladder.py`](ladder.py):
|
|
15
|
+
|
|
16
|
+
The ladder climbs from the ideal ratio (M0) through the datasheet's stated values (M1), no-load friction (M2),
|
|
17
|
+
friction that grows with the transmitted load (M3) and backlash with torsional stiffness (M4), to backlash that opens
|
|
18
|
+
with use (M4.wear), a grey-box residual (M6) and a black-box network (M7).
|
|
19
|
+
|
|
20
|
+
Its vocabulary is the `Gearbox` datasheet's typed fields (which M1 states) plus the names a fit adds on the rungs
|
|
21
|
+
above. A gearbox has no packed names and no deployment-only names: its parameters are all its own.
|
|
22
|
+
|
|
23
|
+
Spec: PEP 0004 §5.4 and §6.3.
|
|
24
|
+
|
|
25
|
+
## The ladder
|
|
26
|
+
|
|
27
|
+
```mermaid
|
|
28
|
+
flowchart BT
|
|
29
|
+
M0_ideal["M0.ideal<br/>An ideal ratio and its<br/>reflected inertia"]
|
|
30
|
+
M1_datasheet["M1.datasheet<br/>The datasheet: the<br/>stated values, nothing<br/>fitted"]
|
|
31
|
+
M2_coulomb_viscous["M2.coulomb_viscous<br/>Coulomb and viscous<br/>friction at the output"]
|
|
32
|
+
M3_load["M3.load<br/>Mesh friction that grows<br/>with the transmitted<br/>load"]
|
|
33
|
+
M4_drivetrain["M4.drivetrain<br/>Backlash and torsional<br/>stiffness"]
|
|
34
|
+
M4_wear["M4.wear<br/>Backlash that opens with<br/>use (Archard)"]
|
|
35
|
+
M6_residual{{"M6.residual<br/>Grey-box residual on<br/>M4.wear"}}
|
|
36
|
+
M7_learned(["M7.learned<br/>Black-box network"])
|
|
37
|
+
M0_ideal --> M1_datasheet
|
|
38
|
+
M1_datasheet --> M2_coulomb_viscous
|
|
39
|
+
M2_coulomb_viscous --> M3_load
|
|
40
|
+
M3_load --> M4_drivetrain
|
|
41
|
+
M4_drivetrain --> M4_wear
|
|
42
|
+
M4_wear --> M6_residual
|
|
43
|
+
M6_residual ~~~ M7_learned
|
|
44
|
+
classDef physics fill:#e8f1fb,stroke:#2f6aa3,color:#10243a
|
|
45
|
+
classDef wear fill:#e8f1fb,stroke:#2f6aa3,color:#10243a,stroke-dasharray:6 3
|
|
46
|
+
classDef residual fill:#fdf0dc,stroke:#b06a00,color:#3a2400
|
|
47
|
+
classDef learned fill:#f1e6fb,stroke:#7a3db3,color:#2a1040
|
|
48
|
+
class M0_ideal,M1_datasheet,M2_coulomb_viscous,M3_load,M4_drivetrain physics
|
|
49
|
+
class M4_wear wear
|
|
50
|
+
class M6_residual residual
|
|
51
|
+
class M7_learned learned
|
|
52
|
+
```
|
|
53
|
+
|
|
54
|
+
Read it bottom up: each solid arrow runs from a rung's base to the rung that extends it, and a rung needs everything below it on its own chain (its fallback). Blue box: a physics rung; dashed blue box: a wear rung (a parameter that grows with use); amber hexagon: the grey-box residual (M6) on a physics rung; purple rounded box: the learned net (M7), which extends no model.
|
|
55
|
+
|
|
56
|
+
## Rungs
|
|
57
|
+
|
|
58
|
+
Bottom up. *Needs* is what the rung's model cannot run without, new over its base; *reads when stated* is what it uses when a source states it. A rung needs everything its base needs.
|
|
59
|
+
|
|
60
|
+
| rung | title | base | needs (adds) | reads when stated (optional) | code | equation | references |
|
|
61
|
+
| --- | --- | --- | --- | --- | --- | --- | --- |
|
|
62
|
+
| <a id="rung-m0-ideal"></a>`M0.ideal` | An ideal ratio and its reflected inertia<br>*the actuator's M0.ideal for a reducer.* | — | `gear_ratio`, `gearbox_input_inertia` | — | — | `q_out = q_in/gear_ratio; reflected inertia = gear_ratio²·gearbox_input_inertia` | [SICILIANO_2009](#ref-siciliano_2009), [MUJOCO_ARMATURE](#ref-mujoco_armature) |
|
|
63
|
+
| <a id="rung-m1-datasheet"></a>`M1.datasheet` | The datasheet: the stated values, nothing fitted | [`M0.ideal`](#rung-m0-ideal) | — | every `Gearbox` typed field its base does not hold: 9 names, each listed under [Vocabulary](#vocabulary) | — | `the ideal ratio, with τ_out = efficiency·gear_ratio·τ_in when efficiency is stated` | [SICILIANO_2009](#ref-siciliano_2009) |
|
|
64
|
+
| <a id="rung-m2-coulomb_viscous"></a>`M2.coulomb_viscous` | Coulomb and viscous friction at the output<br>*the actuator's M2 on a reducer, its no-load running torque: robotparts' load rung requires both, and its coverage ruler asks a gearbox's M2 for coulomb_friction.* | [`M1.datasheet`](#rung-m1-datasheet) | `coulomb_friction`, `viscous_friction` | — | — | `τ_r = coulomb_friction·sign(v) + viscous_friction·v at the output` | [ARMSTRONG_1994](#ref-armstrong_1994), [OLSSON_1998](#ref-olsson_1998) |
|
|
65
|
+
| <a id="rung-m3-load"></a>`M3.load` | Mesh friction that grows with the transmitted load<br>*sim2real's gearbox M3. efficiency (η) is needed; friction_load_coefficient (μ) is read only when a source states μ, and then the two agree: driving forward μ = (1 − η)/η.* | [`M2.coulomb_viscous`](#rung-m2-coulomb_viscous) | `efficiency`, `output_friction_fraction` | `friction_load_coefficient` | — | `τ_out = efficiency·gear_ratio·τ_in; output_friction_fraction of the friction acts on the output side` | [KIRCANSKI_1997](#ref-kircanski_1997), [OLSSON_1998](#ref-olsson_1998) |
|
|
66
|
+
| <a id="rung-m4-drivetrain"></a>`M4.drivetrain` | Backlash and torsional stiffness | [`M3.load`](#rung-m3-load) | `backlash`, `torsional_stiffness` | — | — | `q_out = q_in/gear_ratio + lash(τ, backlash) + τ/torsional_stiffness` | [KIRCANSKI_1997](#ref-kircanski_1997), [NORDIN_2002](#ref-nordin_2002), [TUTTLE_1996](#ref-tuttle_1996) |
|
|
67
|
+
| <a id="rung-m4-wear"></a>`M4.wear` | Backlash that opens with use (Archard)<br>wears `backlash`: see [Wear](#wear) | [`M4.drivetrain`](#rung-m4-drivetrain) | `backlash_wear` | — | — | `backlash(u) = backlash + backlash_wear·Σ\|τ\|·Δrev, over the output revolutions Δrev` | [ARCHARD_1953](#ref-archard_1953), [FLODIN_1997](#ref-flodin_1997) |
|
|
68
|
+
| <a id="rung-m6-residual"></a>`M6.residual` | Grey-box residual on M4.wear | [`M4.wear`](#rung-m4-wear) | — | — | — | `M4.wear + an MLP residual transmission error from 3 samples of input angle, output torque and input speed` | [NGUYEN_TUONG_2010](#ref-nguyen_tuong_2010), [ZENG_2020](#ref-zeng_2020) |
|
|
69
|
+
| <a id="rung-m7-learned"></a>`M7.learned` | Black-box network | — | — | — | — | `an MLP over 5 samples of input angle, input speed and output torque → output angle error` | [HWANGBO_2019](#ref-hwangbo_2019), [ZHU_2025](#ref-zhu_2025) |
|
|
70
|
+
|
|
71
|
+
## Wear
|
|
72
|
+
|
|
73
|
+
Which parameter grows with use, with what, by which law, at which rate.
|
|
74
|
+
|
|
75
|
+
| rung | parameter that wears | grows with | law | rate |
|
|
76
|
+
| --- | --- | --- | --- | --- |
|
|
77
|
+
| [`M4.wear`](#rung-m4-wear) | [`backlash`](#param-backlash) | torque-weighted output revolutions (N·m·rev) | archard: `p(u) = p0 + k·Σ(load·distance): wear grows with the load carried times the distance slid` | [`backlash_wear`](#param-backlash_wear) |
|
|
78
|
+
|
|
79
|
+
## Vocabulary
|
|
80
|
+
|
|
81
|
+
Every parameter the ladder holds, by the rung that first reads it. — as a unit: dimensionless (a ratio or a count).
|
|
82
|
+
|
|
83
|
+
| parameter | SI unit | shape | definition | first read on |
|
|
84
|
+
| --- | --- | --- | --- | --- |
|
|
85
|
+
| <a id="param-gear_ratio"></a>`gear_ratio` | — | scalar | Input turns per output turn, > 0. | [`M0.ideal`](#rung-m0-ideal) |
|
|
86
|
+
| <a id="param-gearbox_input_inertia"></a>`gearbox_input_inertia` | kg·m² | scalar | Inertia referred to the input shaft. | [`M0.ideal`](#rung-m0-ideal) |
|
|
87
|
+
| <a id="param-rated_torque"></a>`rated_torque` | N·m | scalar | Continuous torque at the output. | [`M1.datasheet`](#rung-m1-datasheet) (when stated) |
|
|
88
|
+
| <a id="param-peak_torque"></a>`peak_torque` | N·m | scalar | Peak torque at the output. | [`M1.datasheet`](#rung-m1-datasheet) (when stated) |
|
|
89
|
+
| <a id="param-backlash"></a>`backlash` | rad | scalar | Backlash at the output. | [`M1.datasheet`](#rung-m1-datasheet) (when stated); needed from [`M4.drivetrain`](#rung-m4-drivetrain) |
|
|
90
|
+
| <a id="param-efficiency"></a>`efficiency` | — | scalar | Power out over power in, at the source's operating point. | [`M1.datasheet`](#rung-m1-datasheet) (when stated); needed from [`M3.load`](#rung-m3-load) |
|
|
91
|
+
| <a id="param-mass"></a>`mass` | kg | scalar | Mass as sold. | [`M1.datasheet`](#rung-m1-datasheet) (when stated) |
|
|
92
|
+
| <a id="param-outer_diameter"></a>`outer_diameter` | m | scalar | Largest diameter of a round housing. | [`M1.datasheet`](#rung-m1-datasheet) (when stated) |
|
|
93
|
+
| <a id="param-axial_length"></a>`axial_length` | m | scalar | Overall length along the axis. | [`M1.datasheet`](#rung-m1-datasheet) (when stated) |
|
|
94
|
+
| <a id="param-max_axial_load"></a>`max_axial_load` | N | scalar | Largest axial load on the output (catalogue name). | [`M1.datasheet`](#rung-m1-datasheet) (when stated) |
|
|
95
|
+
| <a id="param-max_radial_load"></a>`max_radial_load` | N | scalar | Largest radial load on the output (catalogue name). | [`M1.datasheet`](#rung-m1-datasheet) (when stated) |
|
|
96
|
+
| <a id="param-coulomb_friction"></a>`coulomb_friction` | N·m | scalar | Coulomb friction torque at the output: the constant torque that opposes motion. | [`M2.coulomb_viscous`](#rung-m2-coulomb_viscous) |
|
|
97
|
+
| <a id="param-viscous_friction"></a>`viscous_friction` | N·m·s/rad | scalar | Viscous friction coefficient at the output. | [`M2.coulomb_viscous`](#rung-m2-coulomb_viscous) |
|
|
98
|
+
| <a id="param-friction_load_coefficient"></a>`friction_load_coefficient` | — | scalar | Extra output friction per N·m of load torque the part transmits: Fc + μ·abs(τ_load). | [`M3.load`](#rung-m3-load) (when stated) |
|
|
99
|
+
| <a id="param-output_friction_fraction"></a>`output_friction_fraction` | — | scalar | The share of the reducer's friction that acts on its output side. | [`M3.load`](#rung-m3-load) |
|
|
100
|
+
| <a id="param-torsional_stiffness"></a>`torsional_stiffness` | N·m/rad | scalar | Drivetrain stiffness at the output with the rotor held: output torque per radian of twist. | [`M4.drivetrain`](#rung-m4-drivetrain) |
|
|
101
|
+
| <a id="param-backlash_wear"></a>`backlash_wear` | rad/(N·m·rev) | scalar | How fast backlash opens per torque-weighted output revolution (Archard). | [`M4.wear`](#rung-m4-wear) |
|
|
102
|
+
|
|
103
|
+
## Aliases
|
|
104
|
+
|
|
105
|
+
Other names a source uses for one of these parameters. A note says how it differs when it is not the same quantity one for one. The unit is the one the source writes its values in; *(canonical)* after it marks an alias stored with no unit of its own, which robot_models reads as the canonical parameter's SI unit, shown here spelled out. A note can still qualify that unit.
|
|
106
|
+
|
|
107
|
+
| alias | canonical | unit | note |
|
|
108
|
+
| --- | --- | --- | --- |
|
|
109
|
+
| `backlash_arcmin` | [`backlash`](#param-backlash) | arcmin | |
|
|
110
|
+
| `backlash_rad` | [`backlash`](#param-backlash) | rad *(canonical)* | |
|
|
111
|
+
| `backlash_wear_rad_per_nm_rev` | [`backlash_wear`](#param-backlash_wear) | rad/(N·m·rev) *(canonical)* | |
|
|
112
|
+
| `gear_stiffness_nm_rad` | [`torsional_stiffness`](#param-torsional_stiffness) | N·m/rad *(canonical)* | Fitted on a mounted unit: it includes the mount's compliance. |
|
|
113
|
+
| `length_mm` | [`axial_length`](#param-axial_length) | mm | |
|
|
114
|
+
| `mass_kg` | [`mass`](#param-mass) | kg *(canonical)* | |
|
|
115
|
+
| `mesh_efficiency_eta` | [`efficiency`](#param-efficiency) | dimensionless *(canonical)* | The twin's constant η in τ_out = η·N·τ_in; a datasheet's efficiency is at its stated operating point; μ = (1 − η)/η driving forward. |
|
|
116
|
+
| `od_mm` | [`outer_diameter`](#param-outer_diameter) | mm | |
|
|
117
|
+
| `peak_torque_nm` | [`peak_torque`](#param-peak_torque) | N·m *(canonical)* | |
|
|
118
|
+
| `rated_torque_nm` | [`rated_torque`](#param-rated_torque) | N·m *(canonical)* | |
|
|
119
|
+
|
|
120
|
+
## Packed names
|
|
121
|
+
|
|
122
|
+
Names for one array that carries several of these parameters; never read as one parameter.
|
|
123
|
+
|
|
124
|
+
None.
|
|
125
|
+
|
|
126
|
+
## Deployment-only names
|
|
127
|
+
|
|
128
|
+
Names some model reads that are not the type's own: a deployment sets them, or the mount gives them.
|
|
129
|
+
|
|
130
|
+
None.
|
|
131
|
+
|
|
132
|
+
## References
|
|
133
|
+
|
|
134
|
+
The works the rungs cite, by their names in [`robot_models.references`](../../../references.py).
|
|
135
|
+
|
|
136
|
+
- <a id="ref-archard_1953"></a>**ARCHARD_1953**: Archard (1953). Contact and rubbing of flat surfaces. Journal of Applied Physics. [doi:10.1063/1.1721448](https://doi.org/10.1063/1.1721448). What the rung uses: wear volume grows with the load carried times the distance slid. Cited by [`M4.wear`](#rung-m4-wear).
|
|
137
|
+
- <a id="ref-armstrong_1994"></a>**ARMSTRONG_1994**: Armstrong-Hélouvry, Dupont, Canudas de Wit (1994). A survey of models, analysis tools and compensation methods for the control of machines with friction. Automatica. [doi:10.1016/0005-1098(94)90209-7](https://doi.org/10.1016/0005-1098%2894%2990209-7). What the rung uses: Coulomb, viscous and Stribeck friction. Cited by [`M2.coulomb_viscous`](#rung-m2-coulomb_viscous).
|
|
138
|
+
- <a id="ref-flodin_1997"></a>**FLODIN_1997**: Flodin, Andersson (1997). Simulation of mild wear in spur gears. Wear. [doi:10.1016/S0043-1648(96)07467-4](https://doi.org/10.1016/S0043-1648%2896%2907467-4). What the rung uses: Archard's law on gear teeth: the flank wear that opens backlash. Cited by [`M4.wear`](#rung-m4-wear).
|
|
139
|
+
- <a id="ref-hwangbo_2019"></a>**HWANGBO_2019**: Hwangbo, Lee, Dosovitskiy, Bellicoso, Tsounis, Koltun, Hutter (2019). Learning agile and dynamic motor skills for legged robots. Science Robotics. [doi:10.1126/scirobotics.aau5872](https://doi.org/10.1126/scirobotics.aau5872). What the rung uses: ANYmal's actuator net: an MLP over position error and velocity at t, t − 10 ms, t − 20 ms, 3 × 32 softsign (arXiv:1901.08652). Cited by [`M7.learned`](#rung-m7-learned).
|
|
140
|
+
- <a id="ref-kircanski_1997"></a>**KIRCANSKI_1997**: Kircanski, Goldenberg (1997). An experimental study of nonlinear stiffness, hysteresis, and friction effects in robot joints with harmonic drives and torque sensors. The International Journal of Robotics Research. [doi:10.1177/027836499701600207](https://doi.org/10.1177/027836499701600207). What the rung uses: load-dependent friction and torsional stiffness measured in a joint. Cited by [`M3.load`](#rung-m3-load), [`M4.drivetrain`](#rung-m4-drivetrain).
|
|
141
|
+
- <a id="ref-mujoco_armature"></a>**MUJOCO_ARMATURE**: MuJoCo (2026). XML reference: joint armature. [https://mujoco.readthedocs.io/en/stable/XMLreference.html#body-joint-armature](https://mujoco.readthedocs.io/en/stable/XMLreference.html#body-joint-armature) (doc). What the rung uses: the rotor's inertia reflected through the gear, as the simulator takes it. Cited by [`M0.ideal`](#rung-m0-ideal).
|
|
142
|
+
- <a id="ref-nguyen_tuong_2010"></a>**NGUYEN_TUONG_2010**: Nguyen-Tuong, Peters (2010). Using model knowledge for learning inverse dynamics. IEEE International Conference on Robotics and Automation. [doi:10.1109/ROBOT.2010.5509858](https://doi.org/10.1109/ROBOT.2010.5509858). What the rung uses: a physics model plus a learned residual. Cited by [`M6.residual`](#rung-m6-residual).
|
|
143
|
+
- <a id="ref-nordin_2002"></a>**NORDIN_2002**: Nordin, Gutman (2002). Controlling mechanical systems with backlash—a survey. Automatica. [doi:10.1016/S0005-1098(02)00047-X](https://doi.org/10.1016/S0005-1098%2802%2900047-X). What the rung uses: dead-zone backlash between motor and load. Cited by [`M4.drivetrain`](#rung-m4-drivetrain).
|
|
144
|
+
- <a id="ref-olsson_1998"></a>**OLSSON_1998**: Olsson, Åström, Canudas de Wit, Gäfvert, Lischinsky (1998). Friction models and friction compensation. European Journal of Control. [doi:10.1016/S0947-3580(98)70113-X](https://doi.org/10.1016/S0947-3580%2898%2970113-X). What the rung uses: static friction models from Coulomb + viscous to Stribeck. Cited by [`M2.coulomb_viscous`](#rung-m2-coulomb_viscous), [`M3.load`](#rung-m3-load).
|
|
145
|
+
- <a id="ref-siciliano_2009"></a>**SICILIANO_2009**: Siciliano, Sciavicco, Villani, Oriolo (2009). Robotics: Modelling, Planning and Control. Springer. [doi:10.1007/978-1-84628-642-1](https://doi.org/10.1007/978-1-84628-642-1) (book). What the rung uses: rigid-body joint dynamics and reflected inertia. Cited by [`M0.ideal`](#rung-m0-ideal), [`M1.datasheet`](#rung-m1-datasheet).
|
|
146
|
+
- <a id="ref-tuttle_1996"></a>**TUTTLE_1996**: Tuttle, Seering (1996). A nonlinear model of a harmonic drive gear transmission. IEEE Transactions on Robotics and Automation. [doi:10.1109/70.499819](https://doi.org/10.1109/70.499819). What the rung uses: a gear's compliance, friction and kinematic error. Cited by [`M4.drivetrain`](#rung-m4-drivetrain).
|
|
147
|
+
- <a id="ref-zeng_2020"></a>**ZENG_2020**: Zeng, Song, Lee, Rodriguez, Funkhouser (2020). TossingBot: learning to throw arbitrary objects with residual physics. IEEE Transactions on Robotics. [doi:10.1109/TRO.2020.2988642](https://doi.org/10.1109/TRO.2020.2988642). What the rung uses: residual physics: learn what the physics estimate misses. Cited by [`M6.residual`](#rung-m6-residual).
|
|
148
|
+
- <a id="ref-zhu_2025"></a>**ZHU_2025**: Zhu, Tanaka, Rafeedi, Hong (2025). Cycloidal quasi-direct drive actuator designs with learning-based torque estimation for legged robotics. arXiv:2410.16591. [https://arxiv.org/abs/2410.16591](https://arxiv.org/abs/2410.16591) (preprint). What the rung uses: a longer history (a 30-step GRU) when ripple or backlash matter. Cited by [`M7.learned`](#rung-m7-learned).
|
|
@@ -0,0 +1,36 @@
|
|
|
1
|
+
"""Gearbox: the typed datasheet fields of a reducer sold on its own.
|
|
2
|
+
|
|
3
|
+
Names are robotparts registry keys (key_specs["gearbox"] first); `max_axial_load` / `max_radial_load` are the
|
|
4
|
+
catalogue's names. No part is migrated onto this type yet (PEP 0003 §9); it is here so the servo tree is whole.
|
|
5
|
+
"""
|
|
6
|
+
|
|
7
|
+
from __future__ import annotations
|
|
8
|
+
|
|
9
|
+
from dataclasses import dataclass
|
|
10
|
+
from typing import ClassVar
|
|
11
|
+
|
|
12
|
+
from ....datasheet import MECHANICAL, PERFORMANCE, Datasheet, Field, Stated
|
|
13
|
+
from ....datasheet.units import FORCE, FRACTION, INERTIA, LENGTH, MASS, RATIO, SMALL_ANGLE, TORQUE
|
|
14
|
+
|
|
15
|
+
|
|
16
|
+
@dataclass(frozen=True)
|
|
17
|
+
class Gearbox(Datasheet):
|
|
18
|
+
"""A reducer's datasheet. Torques at its output."""
|
|
19
|
+
|
|
20
|
+
KEY_SPECS: ClassVar[tuple[str, ...]] = ("gear_ratio", "rated_torque", "peak_torque")
|
|
21
|
+
|
|
22
|
+
gear_ratio: Stated | None = Field(RATIO, "Input turns per output turn, > 0.", group=PERFORMANCE, positive=True)
|
|
23
|
+
rated_torque: Stated | None = Field(TORQUE, "Continuous torque at the output.", group=PERFORMANCE, positive=True)
|
|
24
|
+
peak_torque: Stated | None = Field(TORQUE, "Peak torque at the output.", group=PERFORMANCE, positive=True)
|
|
25
|
+
backlash: Stated | None = Field(SMALL_ANGLE, "Backlash at the output.", group=PERFORMANCE)
|
|
26
|
+
efficiency: Stated | None = Field(FRACTION, "Power out over power in, at the source's operating point.",
|
|
27
|
+
group=PERFORMANCE, positive=True)
|
|
28
|
+
gearbox_input_inertia: Stated | None = Field(INERTIA, "Inertia referred to the input shaft.", group=MECHANICAL,
|
|
29
|
+
positive=True)
|
|
30
|
+
mass: Stated | None = Field(MASS, "Mass as sold.", group=MECHANICAL, positive=True)
|
|
31
|
+
outer_diameter: Stated | None = Field(LENGTH, "Largest diameter of a round housing.", group=MECHANICAL, positive=True)
|
|
32
|
+
axial_length: Stated | None = Field(LENGTH, "Overall length along the axis.", group=MECHANICAL, positive=True)
|
|
33
|
+
max_axial_load: Stated | None = Field(FORCE, "Largest axial load on the output (catalogue name).", group=MECHANICAL,
|
|
34
|
+
positive=True)
|
|
35
|
+
max_radial_load: Stated | None = Field(FORCE, "Largest radial load on the output (catalogue name).",
|
|
36
|
+
group=MECHANICAL, positive=True)
|
|
@@ -0,0 +1,214 @@
|
|
|
1
|
+
"""A gear stage between a motor and its load: its ladder of models (PEP 0004).
|
|
2
|
+
|
|
3
|
+
The ladder climbs from the ideal ratio (M0) through the datasheet's stated values (M1), no-load friction (M2),
|
|
4
|
+
friction that grows with the transmitted load (M3) and backlash with torsional stiffness (M4), to backlash that opens
|
|
5
|
+
with use (M4.wear), a grey-box residual (M6) and a black-box network (M7).
|
|
6
|
+
|
|
7
|
+
Its vocabulary is the `Gearbox` datasheet's typed fields (which M1 states) plus the names a fit adds on the rungs
|
|
8
|
+
above. A gearbox has no packed names and no deployment-only names: its parameters are all its own.
|
|
9
|
+
|
|
10
|
+
Spec: PEP 0004 §5.4 and §6.3.
|
|
11
|
+
"""
|
|
12
|
+
|
|
13
|
+
from __future__ import annotations
|
|
14
|
+
|
|
15
|
+
from robot_models import references
|
|
16
|
+
from robot_models.actuators.servo.gearbox.gearbox import Gearbox
|
|
17
|
+
from robot_models.ladder import Alias, Ladder, Parameter, Rung, Wear, datasheet_vocabulary
|
|
18
|
+
|
|
19
|
+
# --- the vocabulary, grouped by the rung that first reads it ----------------------------------------------------------
|
|
20
|
+
|
|
21
|
+
# M0 and M1: the datasheet's typed fields, with their units and definitions taken from the class.
|
|
22
|
+
# WHY not restated here (PEP 0003 §6, PEP 0004 decision 3): the datasheet and the ladder can then never hold two
|
|
23
|
+
# spellings of one field, and M1.datasheet holds exactly these.
|
|
24
|
+
DATASHEET_FIELDS = datasheet_vocabulary(Gearbox)
|
|
25
|
+
|
|
26
|
+
# M2: friction with the rotor turning at no load, at the output.
|
|
27
|
+
M2_PARAMETERS = (
|
|
28
|
+
Parameter(
|
|
29
|
+
name="coulomb_friction",
|
|
30
|
+
unit="N·m",
|
|
31
|
+
definition="Coulomb friction torque at the output: the constant torque that opposes motion.",
|
|
32
|
+
),
|
|
33
|
+
Parameter(
|
|
34
|
+
name="viscous_friction",
|
|
35
|
+
unit="N·m·s/rad",
|
|
36
|
+
definition="Viscous friction coefficient at the output.",
|
|
37
|
+
),
|
|
38
|
+
)
|
|
39
|
+
|
|
40
|
+
# M3: friction that depends on the load the mesh transmits.
|
|
41
|
+
M3_PARAMETERS = (
|
|
42
|
+
Parameter(
|
|
43
|
+
name="friction_load_coefficient",
|
|
44
|
+
unit="",
|
|
45
|
+
definition="Extra output friction per N·m of load torque the part transmits: Fc + μ·abs(τ_load).",
|
|
46
|
+
),
|
|
47
|
+
Parameter(
|
|
48
|
+
name="output_friction_fraction",
|
|
49
|
+
unit="",
|
|
50
|
+
definition="The share of the reducer's friction that acts on its output side.",
|
|
51
|
+
),
|
|
52
|
+
)
|
|
53
|
+
|
|
54
|
+
# M4: the drivetrain's lost motion and compliance.
|
|
55
|
+
M4_PARAMETERS = (
|
|
56
|
+
Parameter(
|
|
57
|
+
name="torsional_stiffness",
|
|
58
|
+
unit="N·m/rad",
|
|
59
|
+
definition="Drivetrain stiffness at the output with the rotor held: output torque per radian of twist.",
|
|
60
|
+
),
|
|
61
|
+
)
|
|
62
|
+
|
|
63
|
+
# M4.wear: how fast the lost motion grows.
|
|
64
|
+
M4_WEAR_PARAMETERS = (
|
|
65
|
+
Parameter(
|
|
66
|
+
name="backlash_wear",
|
|
67
|
+
unit="rad/(N·m·rev)",
|
|
68
|
+
definition="How fast backlash opens per torque-weighted output revolution (Archard).",
|
|
69
|
+
),
|
|
70
|
+
)
|
|
71
|
+
|
|
72
|
+
VOCABULARY = (
|
|
73
|
+
*DATASHEET_FIELDS,
|
|
74
|
+
*M2_PARAMETERS,
|
|
75
|
+
*M3_PARAMETERS,
|
|
76
|
+
*M4_PARAMETERS,
|
|
77
|
+
*M4_WEAR_PARAMETERS,
|
|
78
|
+
)
|
|
79
|
+
|
|
80
|
+
# --- the rungs, M0 upward ---------------------------------------------------------------------------------------------
|
|
81
|
+
|
|
82
|
+
RUNGS = (
|
|
83
|
+
Rung(
|
|
84
|
+
level=0,
|
|
85
|
+
name="ideal",
|
|
86
|
+
title="An ideal ratio and its reflected inertia",
|
|
87
|
+
base=None,
|
|
88
|
+
adds=("gear_ratio", "gearbox_input_inertia"),
|
|
89
|
+
equation="q_out = q_in/gear_ratio; reflected inertia = gear_ratio²·gearbox_input_inertia",
|
|
90
|
+
references=(references.SICILIANO_2009, references.MUJOCO_ARMATURE),
|
|
91
|
+
note="the actuator's M0.ideal for a reducer.",
|
|
92
|
+
),
|
|
93
|
+
Rung(
|
|
94
|
+
level=1,
|
|
95
|
+
name="datasheet",
|
|
96
|
+
title="The datasheet: the stated values, nothing fitted",
|
|
97
|
+
base="M0.ideal",
|
|
98
|
+
# WHY optional and not adds (PEP 0004 decision 3): M1 states every typed field but needs none beyond M0.
|
|
99
|
+
optional=tuple(
|
|
100
|
+
parameter.name for parameter in DATASHEET_FIELDS
|
|
101
|
+
if parameter.name not in ("gear_ratio", "gearbox_input_inertia")
|
|
102
|
+
),
|
|
103
|
+
equation="the ideal ratio, with τ_out = efficiency·gear_ratio·τ_in when efficiency is stated",
|
|
104
|
+
references=(references.SICILIANO_2009,),
|
|
105
|
+
),
|
|
106
|
+
Rung(
|
|
107
|
+
level=2,
|
|
108
|
+
name="coulomb_viscous",
|
|
109
|
+
title="Coulomb and viscous friction at the output",
|
|
110
|
+
base="M1.datasheet",
|
|
111
|
+
adds=("coulomb_friction", "viscous_friction"),
|
|
112
|
+
equation="τ_r = coulomb_friction·sign(v) + viscous_friction·v at the output",
|
|
113
|
+
references=(references.ARMSTRONG_1994, references.OLSSON_1998),
|
|
114
|
+
note=("the actuator's M2 on a reducer, its no-load running torque: robotparts' load rung requires both, and "
|
|
115
|
+
"its coverage ruler asks a gearbox's M2 for coulomb_friction."),
|
|
116
|
+
),
|
|
117
|
+
Rung(
|
|
118
|
+
level=3,
|
|
119
|
+
name="load",
|
|
120
|
+
title="Mesh friction that grows with the transmitted load",
|
|
121
|
+
base="M2.coulomb_viscous",
|
|
122
|
+
adds=("efficiency", "output_friction_fraction"),
|
|
123
|
+
optional=("friction_load_coefficient",),
|
|
124
|
+
equation=("τ_out = efficiency·gear_ratio·τ_in; output_friction_fraction of the friction acts on the output "
|
|
125
|
+
"side"),
|
|
126
|
+
references=(references.KIRCANSKI_1997, references.OLSSON_1998),
|
|
127
|
+
# WHY efficiency needed and friction_load_coefficient only read when stated: they state one effect
|
|
128
|
+
# (load-dependent mesh loss) two ways. The rung runs on η, as sim2real's gearbox does; μ is read only when a
|
|
129
|
+
# source states μ, and then the two must agree, driving forward μ = (1 − η)/η. WHY no μ term in the equation:
|
|
130
|
+
# coulomb_friction + μ·abs(τ_load) on top of η would charge the same mesh loss twice.
|
|
131
|
+
note=("sim2real's gearbox M3. efficiency (η) is needed; friction_load_coefficient (μ) is read only when a "
|
|
132
|
+
"source states μ, and then the two agree: driving forward μ = (1 − η)/η."),
|
|
133
|
+
),
|
|
134
|
+
Rung(
|
|
135
|
+
level=4,
|
|
136
|
+
name="drivetrain",
|
|
137
|
+
title="Backlash and torsional stiffness",
|
|
138
|
+
base="M3.load",
|
|
139
|
+
adds=("backlash", "torsional_stiffness"),
|
|
140
|
+
equation="q_out = q_in/gear_ratio + lash(τ, backlash) + τ/torsional_stiffness",
|
|
141
|
+
references=(references.KIRCANSKI_1997, references.NORDIN_2002, references.TUTTLE_1996),
|
|
142
|
+
),
|
|
143
|
+
Rung(
|
|
144
|
+
level=4,
|
|
145
|
+
name="wear",
|
|
146
|
+
title="Backlash that opens with use (Archard)",
|
|
147
|
+
base="M4.drivetrain",
|
|
148
|
+
adds=("backlash_wear",),
|
|
149
|
+
wears=(
|
|
150
|
+
Wear(
|
|
151
|
+
parameter="backlash",
|
|
152
|
+
usage="torque-weighted output revolutions",
|
|
153
|
+
usage_unit="N·m·rev",
|
|
154
|
+
law="archard",
|
|
155
|
+
rate="backlash_wear",
|
|
156
|
+
),
|
|
157
|
+
),
|
|
158
|
+
equation="backlash(u) = backlash + backlash_wear·Σ|τ|·Δrev, over the output revolutions Δrev",
|
|
159
|
+
references=(references.ARCHARD_1953, references.FLODIN_1997),
|
|
160
|
+
),
|
|
161
|
+
Rung(
|
|
162
|
+
level=6,
|
|
163
|
+
name="residual",
|
|
164
|
+
title="Grey-box residual on M4.wear",
|
|
165
|
+
base="M4.wear",
|
|
166
|
+
kind="residual",
|
|
167
|
+
equation=("M4.wear + an MLP residual transmission error from 3 samples of input angle, output torque and "
|
|
168
|
+
"input speed"),
|
|
169
|
+
references=(references.NGUYEN_TUONG_2010, references.ZENG_2020),
|
|
170
|
+
),
|
|
171
|
+
Rung(
|
|
172
|
+
level=7,
|
|
173
|
+
name="learned",
|
|
174
|
+
title="Black-box network",
|
|
175
|
+
base=None,
|
|
176
|
+
kind="learned",
|
|
177
|
+
# WHY 5 samples: hysteresis and backlash need a longer memory than a residual's 3 (Zhu 2025).
|
|
178
|
+
equation="an MLP over 5 samples of input angle, input speed and output torque → output angle error",
|
|
179
|
+
references=(references.HWANGBO_2019, references.ZHU_2025),
|
|
180
|
+
),
|
|
181
|
+
)
|
|
182
|
+
|
|
183
|
+
# --- other names for the same quantities (PEP 0004 §6.3) --------------------------------------------------------------
|
|
184
|
+
|
|
185
|
+
ALIASES = (
|
|
186
|
+
Alias(
|
|
187
|
+
name="mesh_efficiency_eta",
|
|
188
|
+
canonical="efficiency",
|
|
189
|
+
note=("The twin's constant η in τ_out = η·N·τ_in; a datasheet's efficiency is at its stated operating "
|
|
190
|
+
"point; μ = (1 − η)/η driving forward."),
|
|
191
|
+
),
|
|
192
|
+
Alias(name="backlash_rad", canonical="backlash"),
|
|
193
|
+
Alias(name="backlash_arcmin", canonical="backlash", unit="arcmin"),
|
|
194
|
+
Alias(
|
|
195
|
+
name="gear_stiffness_nm_rad",
|
|
196
|
+
canonical="torsional_stiffness",
|
|
197
|
+
note="Fitted on a mounted unit: it includes the mount's compliance.",
|
|
198
|
+
),
|
|
199
|
+
Alias(name="backlash_wear_rad_per_nm_rev", canonical="backlash_wear"),
|
|
200
|
+
Alias(name="rated_torque_nm", canonical="rated_torque"),
|
|
201
|
+
Alias(name="peak_torque_nm", canonical="peak_torque"),
|
|
202
|
+
Alias(name="mass_kg", canonical="mass"),
|
|
203
|
+
Alias(name="od_mm", canonical="outer_diameter", unit="mm"),
|
|
204
|
+
Alias(name="length_mm", canonical="axial_length", unit="mm"),
|
|
205
|
+
)
|
|
206
|
+
|
|
207
|
+
LADDER = Ladder(
|
|
208
|
+
type="gearbox",
|
|
209
|
+
title="A gear stage between a motor and its load.",
|
|
210
|
+
vocabulary=VOCABULARY,
|
|
211
|
+
rungs=RUNGS,
|
|
212
|
+
aliases=ALIASES,
|
|
213
|
+
datasheet=Gearbox,
|
|
214
|
+
)
|
|
@@ -0,0 +1,33 @@
|
|
|
1
|
+
"""IntegratedServo: the typed datasheet fields of a motor, a reducer and a driver sold as one SKU.
|
|
2
|
+
|
|
3
|
+
Every BldcMotor field, plus the reducer's. Torques and speeds are at the OUTPUT, after the reducer; Kv, Kt and rotor
|
|
4
|
+
inertia stay on the rotor (registry definitions), so a source that states them after the reducer says at='output'
|
|
5
|
+
and the datasheet carries them through gear_ratio, marked derived.
|
|
6
|
+
"""
|
|
7
|
+
|
|
8
|
+
from __future__ import annotations
|
|
9
|
+
|
|
10
|
+
from dataclasses import dataclass
|
|
11
|
+
|
|
12
|
+
from ...datasheet import MECHANICAL, PERFORMANCE, Field, Stated
|
|
13
|
+
from ...datasheet.units import FORCE, FRACTION, INERTIA, RATIO, SMALL_ANGLE
|
|
14
|
+
from .bldc.bldc_motor import BldcMotor
|
|
15
|
+
|
|
16
|
+
|
|
17
|
+
@dataclass(frozen=True)
|
|
18
|
+
class IntegratedServo(BldcMotor):
|
|
19
|
+
"""An integrated servo's datasheet: the motor's fields and the reducer's."""
|
|
20
|
+
|
|
21
|
+
gear_ratio: Stated | None = Field(RATIO, "Rotor turns per output turn, > 0: 10 for a 10:1 reducer.",
|
|
22
|
+
group=PERFORMANCE, positive=True)
|
|
23
|
+
backlash: Stated | None = Field(SMALL_ANGLE, "Backlash at the output.", group=PERFORMANCE)
|
|
24
|
+
efficiency: Stated | None = Field(FRACTION, "Reducer efficiency, power out over power in, at the source's "
|
|
25
|
+
"operating point.", group=PERFORMANCE, positive=True)
|
|
26
|
+
gearbox_input_inertia: Stated | None = Field(INERTIA, "The reducer's inertia referred to its input shaft.",
|
|
27
|
+
group=MECHANICAL, positive=True)
|
|
28
|
+
output_inertia: Stated | None = Field(INERTIA, "The part's own inertia about its axis, referred to the output "
|
|
29
|
+
"(MuJoCo's armature).", group=MECHANICAL, positive=True)
|
|
30
|
+
max_axial_load: Stated | None = Field(FORCE, "Largest axial load on the output (catalogue name).",
|
|
31
|
+
group=MECHANICAL, positive=True)
|
|
32
|
+
max_radial_load: Stated | None = Field(FORCE, "Largest radial load on the output (catalogue name).",
|
|
33
|
+
group=MECHANICAL, positive=True)
|