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,278 @@
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
+ # integrated_servo
4
+
5
+ A joint in one housing: a motor, its drive, a reducer or none, and an encoder.
6
+
7
+ **14 rungs** · 52 parameters · 44 aliases · 7 packed names · 6 deployment-only names · folder `actuators/servo/` · datasheet class [`IntegratedServo`](integrated_servo.py), whose typed fields rung `M1.datasheet` states.
8
+
9
+ In code: `ladders()["integrated_servo"]` 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
+ Types in the folders below this one: [`bldc_motor`](bldc/README.md), [`foc_controller`](foc_controller/README.md), [`gearbox`](gearbox/README.md).
11
+ Projects the notes below name, and what they are: [Cad2Robot](../../../../docs/TYPES.md#name-cad2robot), [MuJoCo](../../../../docs/TYPES.md#name-mujoco), [robotparts](../../../../docs/TYPES.md#name-robotparts), [sim2real](../../../../docs/TYPES.md#name-sim2real), [the rack twin](../../../../docs/TYPES.md#name-the-rack-twin).
12
+
13
+ ## About
14
+
15
+ From the docstring of [`ladder.py`](ladder.py):
16
+
17
+ Spec: PEP 0004 §5.2 and §6.1 (docs/peps/0004-model-ladders-by-type.md).
18
+
19
+ The ladder climbs the way a joint's torque model grows:
20
+
21
+ - M0 and M1 state the part (its inertia and ratio, then every datasheet field) and fit nothing.
22
+ - M2 to M3 are friction, from Coulomb and viscous through Stribeck, load, LuGre, and weakening with a capture level.
23
+ - M4 adds the drivetrain, rotor ripple, backlash and compliance, and composes the drive's own delay loop.
24
+ - M5 is the electrics and heat (MuJoCo's DC motor, and the drive's ceiling) and the wear that grows with use.
25
+ - M6 is a learned residual on the wear rung and M7 a black-box network.
26
+
27
+ Torques, speeds and inertias are at the OUTPUT, after the reducer, as `IntegratedServo`'s datasheet states them; kt,
28
+ kv and rotor_inertia stay on the rotor. Every name below is a canonical one: sim2real's twin names, the registry's
29
+ keys and the exporter's fields are aliases (a unit never appears in a canonical name), and MuJoCo's arrays are packed
30
+ names. What a deployment sets (gains, current limit) is `deployment`, never a rung's parameter.
31
+
32
+ ## The ladder
33
+
34
+ ```mermaid
35
+ flowchart BT
36
+ M0_ideal["M0.ideal<br/>The ideal actuator: the<br/>stated inertia and<br/>ratio, no losses"]
37
+ M1_datasheet["M1.datasheet<br/>The datasheet: the<br/>stated values, nothing<br/>fitted"]
38
+ M2_coulomb_viscous["M2.coulomb_viscous<br/>Coulomb and viscous<br/>friction, fitted"]
39
+ M3_stribeck["M3.stribeck<br/>Stribeck friction:<br/>breakaway falling to<br/>Coulomb with speed"]
40
+ M3_load["M3.load<br/>Friction that grows with<br/>the transmitted load"]
41
+ M3_lugre["M3.lugre<br/>LuGre dynamic friction"]
42
+ M3_weakening_capture["M3.weakening_capture<br/>Stribeck with weakening<br/>and a capture level at<br/>rest"]
43
+ M4_ripple["M4.ripple<br/>Rotor ripple on Coulomb<br/>and viscous friction"]
44
+ M4_drivetrain["M4.drivetrain<br/>The drivetrain: ripple,<br/>backlash and compliance<br/>on the full friction<br/>model"]
45
+ M5_dcmotor["M5.dcmotor<br/>MuJoCo's DC motor:<br/>electrics, heat, cogging<br/>and LuGre friction"]
46
+ M5_envelope["M5.envelope<br/>The drive's ceiling, the<br/>motor's electrics and<br/>heat on the drivetrain"]
47
+ M5_wear["M5.wear<br/>Wear: friction grows<br/>with hours, backlash<br/>opens with load"]
48
+ M6_residual{{"M6.residual<br/>Grey-box residual on<br/>M5.wear"}}
49
+ M7_learned(["M7.learned<br/>Black-box network"])
50
+ M0_ideal --> M1_datasheet
51
+ M1_datasheet --> M2_coulomb_viscous
52
+ M2_coulomb_viscous --> M3_stribeck
53
+ M2_coulomb_viscous --> M3_load
54
+ M3_stribeck --> M3_lugre
55
+ M3_stribeck --> M3_weakening_capture
56
+ M2_coulomb_viscous --> M4_ripple
57
+ M3_weakening_capture --> M4_drivetrain
58
+ M3_lugre --> M5_dcmotor
59
+ M4_drivetrain --> M5_envelope
60
+ M5_envelope --> M5_wear
61
+ M5_wear --> M6_residual
62
+ subgraph S_foc_controller ["foc_controller (another type)"]
63
+ T_foc_controller__M1_delay_loop["M1.delay_loop<br/>Transport delay, a<br/>first-order current loop<br/>and its torque scale"]
64
+ T_foc_controller__M2_ceiling_heat["M2.ceiling_heat<br/>Voltage ceiling and<br/>board heating"]
65
+ end
66
+ T_foc_controller__M1_delay_loop -.->|composed into| M4_drivetrain
67
+ T_foc_controller__M2_ceiling_heat -.->|composed into| M5_envelope
68
+ M6_residual ~~~ M7_learned
69
+ classDef physics fill:#e8f1fb,stroke:#2f6aa3,color:#10243a
70
+ classDef wear fill:#e8f1fb,stroke:#2f6aa3,color:#10243a,stroke-dasharray:6 3
71
+ classDef residual fill:#fdf0dc,stroke:#b06a00,color:#3a2400
72
+ classDef learned fill:#f1e6fb,stroke:#7a3db3,color:#2a1040
73
+ classDef other fill:#f2f2f2,stroke:#8a8a8a,color:#222222
74
+ class M0_ideal,M1_datasheet,M2_coulomb_viscous,M3_stribeck,M3_load,M3_lugre,M3_weakening_capture,M4_ripple,M4_drivetrain,M5_dcmotor,M5_envelope physics
75
+ class M5_wear wear
76
+ class M6_residual residual
77
+ class M7_learned learned
78
+ class T_foc_controller__M1_delay_loop,T_foc_controller__M2_ceiling_heat other
79
+ ```
80
+
81
+ 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; grey box in a frame: another type's rung, its dashed arrow into the rung that composes it.
82
+
83
+ ## Rungs
84
+
85
+ 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.
86
+
87
+ | rung | title | base | needs (adds) | reads when stated (optional) | code | equation | references |
88
+ | --- | --- | --- | --- | --- | --- | --- | --- |
89
+ | <a id="rung-m0-ideal"></a>`M0.ideal` | The ideal actuator: the stated inertia and ratio, no losses | — | `output_inertia`, `gear_ratio` | — | [`actuators/rungs/ideal`](../rungs/ideal/README.md) | `tau_r = 0; armature = output_inertia` | [SICILIANO_2009](#ref-siciliano_2009), [MUJOCO_ARMATURE](#ref-mujoco_armature) |
90
+ | <a id="rung-m1-datasheet"></a>`M1.datasheet` | The datasheet: the stated values, nothing fitted<br>*States every IntegratedServo field and needs none beyond M0 (robotparts' M1: required false).* | [`M0.ideal`](#rung-m0-ideal) | — | every `IntegratedServo` typed field its base does not hold: 33 names, each listed under [Vocabulary](#vocabulary) | [`actuators/rungs/datasheet`](../rungs/datasheet/README.md) | `tau_r = coulomb_friction·sign(v) + viscous_friction·v when stated; armature = output_inertia, or gear_ratio²·(rotor_inertia + gearbox_input_inertia)` | [ARMSTRONG_1994](#ref-armstrong_1994), [MUJOCO_ARMATURE](#ref-mujoco_armature) |
91
+ | <a id="rung-m2-coulomb_viscous"></a>`M2.coulomb_viscous` | Coulomb and viscous friction, fitted | [`M1.datasheet`](#rung-m1-datasheet) | `coulomb_friction`, `viscous_friction` | — | [`actuators/rungs/coulomb_viscous`](../rungs/coulomb_viscous/README.md) | `tau_r = coulomb_friction·sign(v) + viscous_friction·v` | [ARMSTRONG_1994](#ref-armstrong_1994), [OLSSON_1998](#ref-olsson_1998) |
92
+ | <a id="rung-m3-stribeck"></a>`M3.stribeck` | Stribeck friction: breakaway falling to Coulomb with speed | [`M2.coulomb_viscous`](#rung-m2-coulomb_viscous) | `breakaway_torque`, `stribeck_velocity` | `stribeck_exponent` | [`actuators/rungs/stribeck`](../rungs/stribeck/README.md) | `tau_r = (coulomb_friction + (breakaway_torque − coulomb_friction)·exp(−(\|v\|/stribeck_velocity)^stribeck_exponent))·sign(v) + viscous_friction·v` | [ARMSTRONG_1994](#ref-armstrong_1994), [OLSSON_1998](#ref-olsson_1998) |
93
+ | <a id="rung-m3-load"></a>`M3.load` | Friction that grows with the transmitted load | [`M2.coulomb_viscous`](#rung-m2-coulomb_viscous) | `friction_load_coefficient` | — | [`actuators/rungs/load`](../rungs/load/README.md) | `tau_r = (coulomb_friction + friction_load_coefficient·\|tau_load\|)·sign(v) + viscous_friction·v` | [KIRCANSKI_1997](#ref-kircanski_1997), [OLSSON_1998](#ref-olsson_1998) |
94
+ | <a id="rung-m3-lugre"></a>`M3.lugre` | LuGre dynamic friction | [`M3.stribeck`](#rung-m3-stribeck) | `sigma0`, `sigma1` | — | [`actuators/rungs/lugre`](../rungs/lugre/README.md) | `dz/dt = v − sigma0·\|v\|·z/g(v), g(v) the Stribeck level of M3.stribeck; tau_r = sigma0·z + sigma1·dz/dt + viscous_friction·v (LuGre's sigma2)` | [CANUDAS_1995](#ref-canudas_1995) |
95
+ | <a id="rung-m3-weakening_capture"></a>`M3.weakening_capture` | Stribeck with weakening and a capture level at rest<br>*sim2real's servo M3, the rack twin's friction: its structure only, the twin is never published.* | [`M3.stribeck`](#rung-m3-stribeck) | `friction_weakening`, `friction_weakening_limit`, `friction_capture`, `friction_capture_speed`, `friction_capture_dwell` | — | — | `level(v) = breakaway_torque − friction_weakening·min(\|v\|, friction_weakening_limit) − (breakaway_torque − coulomb_friction)·(1 − exp(−(\|v\|/stribeck_velocity)²)); friction_capture holds below friction_capture_speed until friction_capture_dwell has passed` | [ARMSTRONG_1994](#ref-armstrong_1994), [CANUDAS_1995](#ref-canudas_1995) |
96
+ | <a id="rung-m4-ripple"></a>`M4.ripple` | Rotor ripple on Coulomb and viscous friction | [`M2.coulomb_viscous`](#rung-m2-coulomb_viscous) | `harmonics` | — | [`actuators/rungs/ripple`](../rungs/ripple/README.md) | `tau_r = Σ_k amplitude_k·sin(rotor_harmonic_k·gear_ratio·θ + phase_k) + coulomb_friction·sign(v) + viscous_friction·v` | [JAHNS_1996](#ref-jahns_1996) |
97
+ | <a id="rung-m4-drivetrain"></a>`M4.drivetrain` | The drivetrain: ripple, backlash and compliance on the full friction model<br>*sim2real's servo M4, the rack twin (today's model), less its heat: that is M5.envelope's.*<br>composes [`foc_controller` `M1.delay_loop`](foc_controller/README.md#rung-m1-delay_loop) | [`M3.weakening_capture`](#rung-m3-weakening_capture) | `harmonics`, `backlash`, `torsional_stiffness` | — | — | `output_inertia·q̈ = tau_drive − tau_r; tau_r = level(v)·sign(v) + viscous_friction·v + the harmonics; the output across a backlash gap and torsional_stiffness; tau_drive from foc_controller M1.delay_loop` | [JAHNS_1996](#ref-jahns_1996), [NORDIN_2002](#ref-nordin_2002), [TUTTLE_1996](#ref-tuttle_1996), [KRISHNAN_2010](#ref-krishnan_2010) |
98
+ | <a id="rung-m5-dcmotor"></a>`M5.dcmotor` | MuJoCo's DC motor: electrics, heat, cogging and LuGre friction<br>*robotparts' rung: its terms are MuJoCo's arrays (the packed names); motorconst and resistance required, the rest optional, as its model.json marks them.* | [`M3.lugre`](#rung-m3-lugre) | `kt`, `resistance_line_to_line` | `harmonics`, `thermal_resistance`, `thermal_time_constant` | [`actuators/rungs/dcmotor`](../rungs/dcmotor/README.md) | `MuJoCo's own: mjDYN_DCMOTOR (electrical dynamics), mjGAIN_DCMOTOR (K or K/R), mjBIAS_DCMOTOR (back-EMF, cogging, LuGre friction)` | [KRAUSE_2013](#ref-krause_2013), [MUJOCO_DCMOTOR](#ref-mujoco_dcmotor) |
99
+ | <a id="rung-m5-envelope"></a>`M5.envelope` | The drive's ceiling, the motor's electrics and heat on the drivetrain<br>*sim2real's servo M5 (the envelope ladder): the rack twin plus the drive's ceiling and the motor's electrics; the heat the twin carries at its M4 sits here, robotparts' layer 5.*<br>composes [`foc_controller` `M2.ceiling_heat`](foc_controller/README.md#rung-m2-ceiling_heat) | [`M4.drivetrain`](#rung-m4-drivetrain) | `kt`, `resistance_line_to_line`, `thermal_resistance`, `thermal_time_constant` | — | — | `kt_out = kt·gear_ratio, R = resistance_line_to_line/2 per phase: motoring torque ≤ kt_out·(voltage_available − \|v\|·kt_out/1.5)/R; any torque ≤ kt_out·I_max (the deployment's current cap); winding rise ΔT over ambient: thermal_time_constant·dΔT/dt = thermal_resistance·1.5·i²R − ΔT (the three phases' copper loss, i the phase-current amplitude)` | [KRAUSE_2013](#ref-krause_2013), [KRISHNAN_2010](#ref-krishnan_2010), [MUJOCO_DCMOTOR](#ref-mujoco_dcmotor) |
100
+ | <a id="rung-m5-wear"></a>`M5.wear` | Wear: friction grows with hours, backlash opens with load<br>wears `breakaway_torque`, `coulomb_friction`, `backlash`: see [Wear](#wear) | [`M5.envelope`](#rung-m5-envelope) | `friction_growth`, `backlash_wear` | — | — | `backlash(u) = backlash + backlash_wear·Σ\|τ\|·Δrev; breakaway_torque and coulomb_friction both grow by friction_growth·h (the Stribeck drop stays)` | [ARCHARD_1953](#ref-archard_1953), [FLODIN_1997](#ref-flodin_1997), [LU_MEEKER_1993](#ref-lu_meeker_1993) |
101
+ | <a id="rung-m6-residual"></a>`M6.residual` | Grey-box residual on M5.wear | [`M5.wear`](#rung-m5-wear) | — | — | — | `M5.wear + an MLP residual torque from 3 samples of position error, velocity and torque command` | [NGUYEN_TUONG_2010](#ref-nguyen_tuong_2010), [ZENG_2020](#ref-zeng_2020), [KOVALEV_2026](#ref-kovalev_2026) |
102
+ | <a id="rung-m7-learned"></a>`M7.learned` | Black-box network | — | — | — | — | `an MLP over 3 samples of position error and velocity → output torque` | [HWANGBO_2019](#ref-hwangbo_2019), [HWANGBO_2019_ARXIV](#ref-hwangbo_2019_arxiv), [ZHU_2025](#ref-zhu_2025) |
103
+
104
+ ## Wear
105
+
106
+ Which parameter grows with use, with what, by which law, at which rate.
107
+
108
+ | rung | parameter that wears | grows with | law | rate |
109
+ | --- | --- | --- | --- | --- |
110
+ | [`M5.wear`](#rung-m5-wear) | [`breakaway_torque`](#param-breakaway_torque) | deployment hours (h) | linear: `p(u) = p0 + k·u` | [`friction_growth`](#param-friction_growth) |
111
+ | [`M5.wear`](#rung-m5-wear) | [`coulomb_friction`](#param-coulomb_friction) | deployment hours (h) | linear: `p(u) = p0 + k·u` | [`friction_growth`](#param-friction_growth) |
112
+ | [`M5.wear`](#rung-m5-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) |
113
+
114
+ ## Vocabulary
115
+
116
+ Every parameter the ladder holds, by the rung that first reads it. — as a unit: dimensionless (a ratio or a count).
117
+
118
+ | parameter | SI unit | shape | definition | first read on |
119
+ | --- | --- | --- | --- | --- |
120
+ | <a id="param-gear_ratio"></a>`gear_ratio` | — | scalar | Rotor turns per output turn, > 0: 10 for a 10:1 reducer. | [`M0.ideal`](#rung-m0-ideal) |
121
+ | <a id="param-output_inertia"></a>`output_inertia` | kg·m² | scalar | The part's own inertia about its axis, referred to the output (MuJoCo's armature). | [`M0.ideal`](#rung-m0-ideal) |
122
+ | <a id="param-peak_torque"></a>`peak_torque` | N·m | scalar | Peak (stall, max) torque at the output. | [`M1.datasheet`](#rung-m1-datasheet) (when stated) |
123
+ | <a id="param-rated_torque"></a>`rated_torque` | N·m | scalar | Continuous (rated) torque at the output. | [`M1.datasheet`](#rung-m1-datasheet) (when stated) |
124
+ | <a id="param-max_output_speed"></a>`max_output_speed` | rad/s | scalar | No-load (maximum) speed at the output. | [`M1.datasheet`](#rung-m1-datasheet) (when stated) |
125
+ | <a id="param-rated_speed"></a>`rated_speed` | rad/s | scalar | Speed at rated torque, at the output. | [`M1.datasheet`](#rung-m1-datasheet) (when stated) |
126
+ | <a id="param-rated_power"></a>`rated_power` | W | scalar | Continuous MECHANICAL output power, rated torque × rated speed; an electrical input power is not this. | [`M1.datasheet`](#rung-m1-datasheet) (when stated) |
127
+ | <a id="param-nominal_voltage"></a>`nominal_voltage` | V | scalar | Nominal supply voltage. | [`M1.datasheet`](#rung-m1-datasheet) (when stated) |
128
+ | <a id="param-voltage_min"></a>`voltage_min` | V | scalar | Lowest supply voltage the part is rated for. | [`M1.datasheet`](#rung-m1-datasheet) (when stated) |
129
+ | <a id="param-voltage_max"></a>`voltage_max` | V | scalar | Highest supply voltage the part is rated for. | [`M1.datasheet`](#rung-m1-datasheet) (when stated) |
130
+ | <a id="param-rated_phase_current"></a>`rated_phase_current` | A | scalar | Continuous phase current at rated torque (catalogue name). | [`M1.datasheet`](#rung-m1-datasheet) (when stated) |
131
+ | <a id="param-max_phase_current"></a>`max_phase_current` | A | scalar | Peak phase current, at peak torque (catalogue name). | [`M1.datasheet`](#rung-m1-datasheet) (when stated) |
132
+ | <a id="param-kv"></a>`kv` | rad/(s·V) | scalar | Velocity constant: no-load ROTOR speed per volt (line-to-line peak back-EMF). A geared part's source may state it at the output: say at='output'. | [`M1.datasheet`](#rung-m1-datasheet) (when stated) |
133
+ | <a id="param-kt"></a>`kt` | N·m/A | scalar | Torque constant: ROTOR torque per ampere of phase-current amplitude. A geared part's source may state it at the output: say at='output'. | [`M1.datasheet`](#rung-m1-datasheet) (when stated); needed from [`M5.dcmotor`](#rung-m5-dcmotor) |
134
+ | <a id="param-back_emf_constant"></a>`back_emf_constant` | V·s/rad | scalar | Line-to-line back-EMF per speed (catalogue name). | [`M1.datasheet`](#rung-m1-datasheet) (when stated) |
135
+ | <a id="param-resistance_line_to_line"></a>`resistance_line_to_line` | Ω | scalar | Winding resistance between two leads (line to line); a page's 'phase to phase' is this. | [`M1.datasheet`](#rung-m1-datasheet) (when stated); needed from [`M5.dcmotor`](#rung-m5-dcmotor) |
136
+ | <a id="param-inductance_line_to_line"></a>`inductance_line_to_line` | H | scalar | Winding inductance between two leads (line to line). | [`M1.datasheet`](#rung-m1-datasheet) (when stated) |
137
+ | <a id="param-pole_pairs"></a>`pole_pairs` | — | integer | Magnetic pole pairs. | [`M1.datasheet`](#rung-m1-datasheet) (when stated) |
138
+ | <a id="param-encoder_lines"></a>`encoder_lines` | — | integer | Encoder lines (pulses) per rotor turn (catalogue name). | [`M1.datasheet`](#rung-m1-datasheet) (when stated) |
139
+ | <a id="param-encoder_bits"></a>`encoder_bits` | — | integer | Encoder resolution in bits per rotor turn (catalogue name). | [`M1.datasheet`](#rung-m1-datasheet) (when stated) |
140
+ | <a id="param-mass"></a>`mass` | kg | scalar | Mass as sold, without optional accessories. | [`M1.datasheet`](#rung-m1-datasheet) (when stated) |
141
+ | <a id="param-rotor_inertia"></a>`rotor_inertia` | kg·m² | scalar | The rotor's moment of inertia on the INPUT (rotor) side. Read as output-side it is off by gear_ratio²; a source stating the reflected value says at='output'. | [`M1.datasheet`](#rung-m1-datasheet) (when stated) |
142
+ | <a id="param-coulomb_friction"></a>`coulomb_friction` | N·m | scalar | Coulomb friction torque at the output. | [`M1.datasheet`](#rung-m1-datasheet) (when stated); needed from [`M2.coulomb_viscous`](#rung-m2-coulomb_viscous) |
143
+ | <a id="param-viscous_friction"></a>`viscous_friction` | N·m·s/rad | scalar | Viscous friction coefficient at the output. | [`M1.datasheet`](#rung-m1-datasheet) (when stated); needed from [`M2.coulomb_viscous`](#rung-m2-coulomb_viscous) |
144
+ | <a id="param-torque_ripple"></a>`torque_ripple` | N·m | scalar | Amplitude of a rotor-periodic torque harmonic at the output (cogging); the note says which harmonic. | [`M1.datasheet`](#rung-m1-datasheet) (when stated) |
145
+ | <a id="param-outer_diameter"></a>`outer_diameter` | m | scalar | Largest diameter of a round housing. | [`M1.datasheet`](#rung-m1-datasheet) (when stated) |
146
+ | <a id="param-axial_length"></a>`axial_length` | m | scalar | Overall length of a round housing along its axis. | [`M1.datasheet`](#rung-m1-datasheet) (when stated) |
147
+ | <a id="param-flange_size"></a>`flange_size` | m | scalar | Square flange edge (catalogue name). | [`M1.datasheet`](#rung-m1-datasheet) (when stated) |
148
+ | <a id="param-body_length"></a>`body_length` | m | scalar | Body length behind the flange, without the shaft (catalogue name). | [`M1.datasheet`](#rung-m1-datasheet) (when stated) |
149
+ | <a id="param-shaft_diameter"></a>`shaft_diameter` | m | scalar | Output shaft diameter (catalogue name). | [`M1.datasheet`](#rung-m1-datasheet) (when stated) |
150
+ | <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) |
151
+ | <a id="param-efficiency"></a>`efficiency` | — | scalar | Reducer efficiency, power out over power in, at the source's operating point. | [`M1.datasheet`](#rung-m1-datasheet) (when stated) |
152
+ | <a id="param-gearbox_input_inertia"></a>`gearbox_input_inertia` | kg·m² | scalar | The reducer's inertia referred to its input shaft. | [`M1.datasheet`](#rung-m1-datasheet) (when stated) |
153
+ | <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) |
154
+ | <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) |
155
+ | <a id="param-breakaway_torque"></a>`breakaway_torque` | N·m | scalar | Static friction at the output: the torque that starts it moving from rest, the top of the Stribeck curve. | [`M3.stribeck`](#rung-m3-stribeck) |
156
+ | <a id="param-stribeck_velocity"></a>`stribeck_velocity` | rad/s | scalar | Output speed over which friction falls from breakaway_torque to coulomb_friction. | [`M3.stribeck`](#rung-m3-stribeck) |
157
+ | <a id="param-stribeck_exponent"></a>`stribeck_exponent` | — | scalar | Shape exponent of the Stribeck curve, how sharply friction falls with speed; 2 when absent. | [`M3.stribeck`](#rung-m3-stribeck) (when stated) |
158
+ | <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) |
159
+ | <a id="param-sigma0"></a>`sigma0` | N·m/rad | scalar | LuGre bristle stiffness: output torque per radian of bristle deflection. | [`M3.lugre`](#rung-m3-lugre) |
160
+ | <a id="param-sigma1"></a>`sigma1` | N·m·s/rad | scalar | LuGre bristle damping: output torque per rad/s of bristle deflection rate. | [`M3.lugre`](#rung-m3-lugre) |
161
+ | <a id="param-friction_weakening"></a>`friction_weakening` | N·m·s/rad | scalar | How fast the static friction level falls with output speed, up to friction_weakening_limit. | [`M3.weakening_capture`](#rung-m3-weakening_capture) |
162
+ | <a id="param-friction_weakening_limit"></a>`friction_weakening_limit` | rad/s | scalar | The output speed up to which the friction level keeps weakening. | [`M3.weakening_capture`](#rung-m3-weakening_capture) |
163
+ | <a id="param-friction_capture"></a>`friction_capture` | N·m | scalar | The friction level that holds a slowed output until it has stayed slow for friction_capture_dwell. | [`M3.weakening_capture`](#rung-m3-weakening_capture) |
164
+ | <a id="param-friction_capture_speed"></a>`friction_capture_speed` | rad/s | scalar | Below this output speed a joint counts as slow for capture. | [`M3.weakening_capture`](#rung-m3-weakening_capture) |
165
+ | <a id="param-friction_capture_dwell"></a>`friction_capture_dwell` | s | scalar | How long a joint must stay slow before the static level returns. | [`M3.weakening_capture`](#rung-m3-weakening_capture) |
166
+ | <a id="param-harmonics"></a>`harmonics` | N·m | list | Rotor-periodic torque harmonics at the output, a list of (rotor_harmonic, amplitude, phase): cogging and commutation ripple. | [`M4.ripple`](#rung-m4-ripple) |
167
+ | <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) |
168
+ | <a id="param-thermal_resistance"></a>`thermal_resistance` | K/W | scalar | Winding-to-ambient thermal resistance: winding temperature rise per watt of copper loss. | [`M5.dcmotor`](#rung-m5-dcmotor) (when stated); needed from [`M5.envelope`](#rung-m5-envelope) |
169
+ | <a id="param-thermal_time_constant"></a>`thermal_time_constant` | s | scalar | Time constant of the winding temperature's first-order rise. | [`M5.dcmotor`](#rung-m5-dcmotor) (when stated); needed from [`M5.envelope`](#rung-m5-envelope) |
170
+ | <a id="param-friction_growth"></a>`friction_growth` | N·m/h | scalar | How fast the friction level grows per deployment hour (seals, grease, bearings); on a Stribeck curve breakaway and Coulomb grow together. | [`M5.wear`](#rung-m5-wear) |
171
+ | <a id="param-backlash_wear"></a>`backlash_wear` | rad/(N·m·rev) | scalar | How fast backlash opens per torque-weighted output revolution (Archard). | [`M5.wear`](#rung-m5-wear) |
172
+
173
+ ## Aliases
174
+
175
+ 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.
176
+
177
+ | alias | canonical | unit | note |
178
+ | --- | --- | --- | --- |
179
+ | `armature_kg_m2` | [`output_inertia`](#param-output_inertia) | kg·m² *(canonical)* | As mounted: the whole axis' inertia at the output, the part's own plus what it drives; output_inertia is the part alone. |
180
+ | `backlash_arcmin` | [`backlash`](#param-backlash) | arcmin | |
181
+ | `backlash_rad` | [`backlash`](#param-backlash) | rad *(canonical)* | |
182
+ | `backlash_wear_rad_per_nm_rev` | [`backlash_wear`](#param-backlash_wear) | rad/(N·m·rev) *(canonical)* | |
183
+ | `damping_nm_s_rad` | [`viscous_friction`](#param-viscous_friction) | N·m·s/rad *(canonical)* | |
184
+ | `encoder_counts` | [`encoder_lines`](#param-encoder_lines) | dimensionless *(canonical)* | Counts per turn: 4 × lines on a quadrature encoder. |
185
+ | `friction_capture_dwell_s` | [`friction_capture_dwell`](#param-friction_capture_dwell) | s *(canonical)* | |
186
+ | `friction_capture_nm` | [`friction_capture`](#param-friction_capture) | N·m *(canonical)* | |
187
+ | `friction_capture_speed_rad_s` | [`friction_capture_speed`](#param-friction_capture_speed) | rad/s *(canonical)* | |
188
+ | `friction_growth_nm_per_h` | [`friction_growth`](#param-friction_growth) | N·m/h *(canonical)* | It grows the rack twin's frictionloss, the static level: breakaway_torque and coulomb_friction together. |
189
+ | `friction_stribeck_drop_nm` | [`breakaway_torque`](#param-breakaway_torque) | N·m *(canonical)* | A difference, not a level: breakaway_torque − coulomb_friction. |
190
+ | `friction_stribeck_speed_rad_s` | [`stribeck_velocity`](#param-stribeck_velocity) | rad/s *(canonical)* | The twin's Stribeck exponent is fixed at 2. |
191
+ | `friction_weakening_limit_rad_s` | [`friction_weakening_limit`](#param-friction_weakening_limit) | rad/s *(canonical)* | |
192
+ | `friction_weakening_nm_s_rad` | [`friction_weakening`](#param-friction_weakening) | N·m·s/rad *(canonical)* | |
193
+ | `frictionloss_nm` | [`coulomb_friction`](#param-coulomb_friction) | N·m *(canonical)* | The rack twin's frictionloss is the static level: with no Stribeck term it is coulomb_friction; with one it is breakaway_torque, and coulomb_friction = frictionloss − friction_stribeck_drop. |
194
+ | `gear_stiffness_nm_rad` | [`torsional_stiffness`](#param-torsional_stiffness) | N·m/rad *(canonical)* | Fitted on a mounted unit: it includes the mount's compliance. |
195
+ | `kt_out_nm_a` | [`kt`](#param-kt) | N·m/A *(canonical)* | Output side: kt_out = kt × gear_ratio. |
196
+ | `length_mm` | [`axial_length`](#param-axial_length) | mm | |
197
+ | `mass_kg` | [`mass`](#param-mass) | kg *(canonical)* | |
198
+ | `max_effort_nm` | [`peak_torque`](#param-peak_torque) | N·m *(canonical)* | Cad2Robot's servo field: the effort limit it exports. |
199
+ | `max_speed` | [`max_output_speed`](#param-max_output_speed) | rad/s *(canonical)* | Old user-part key: may be a mechanical limit rather than the no-load speed. |
200
+ | `max_velocity_rad_s` | [`max_output_speed`](#param-max_output_speed) | rad/s *(canonical)* | Cad2Robot's servo field: the velocity limit it exports. |
201
+ | `noload_speed` | [`max_output_speed`](#param-max_output_speed) | rad/s *(canonical)* | Old user-part key: its unit is the part file's; check it before converting. |
202
+ | `noload_speed_rpm` | [`max_output_speed`](#param-max_output_speed) | rpm | |
203
+ | `od_mm` | [`outer_diameter`](#param-outer_diameter) | mm | |
204
+ | `peak_current_a` | [`max_phase_current`](#param-max_phase_current) | A *(canonical)* | |
205
+ | `peak_phase_current` | [`max_phase_current`](#param-max_phase_current) | A *(canonical)* | The registry's driver key: what the integrated drive can deliver; the motor alone may take more. |
206
+ | `peak_torque_nm` | [`peak_torque`](#param-peak_torque) | N·m *(canonical)* | |
207
+ | `phase_inductance` | [`inductance_line_to_line`](#param-inductance_line_to_line) | H *(canonical)* | Old user-part key: per phase is half of line to line on a wye winding. |
208
+ | `phase_inductance_h` | [`inductance_line_to_line`](#param-inductance_line_to_line) | H | Per phase (Cad2Robot's motor): half of line to line on a wye winding. |
209
+ | `phase_resistance` | [`resistance_line_to_line`](#param-resistance_line_to_line) | Ω *(canonical)* | Old user-part key: a 'phase to phase' value is line to line; a per-phase value is half of it on a wye winding. |
210
+ | `phase_resistance_ohm` | [`resistance_line_to_line`](#param-resistance_line_to_line) | Ω | Per phase (sim2real's servo, Cad2Robot's motor): line to line is twice it on a wye winding. |
211
+ | `rated_current_a` | [`rated_phase_current`](#param-rated_phase_current) | A *(canonical)* | |
212
+ | `rated_power_w` | [`rated_power`](#param-rated_power) | W *(canonical)* | |
213
+ | `rated_speed_rpm` | [`rated_speed`](#param-rated_speed) | rpm | |
214
+ | `rated_torque_nm` | [`rated_torque`](#param-rated_torque) | N·m *(canonical)* | |
215
+ | `resistance` | [`resistance_line_to_line`](#param-resistance_line_to_line) | Ω | M5.dcmotor's winding resistance as MuJoCo takes it, per phase as sim2real reads it (phase_resistance_ohm): line to line is twice it on a wye winding. |
216
+ | `ripple_harmonics` | [`harmonics`](#param-harmonics) | N·m *(canonical)* | |
217
+ | `ripple_rotor_per_output` | [`gear_ratio`](#param-gear_ratio) | dimensionless *(canonical)* | The ripple's rotor turns per output turn: the gear ratio as the twin's ripple reads it. |
218
+ | `rotor_inertia_kg_m2` | [`rotor_inertia`](#param-rotor_inertia) | kg·m² *(canonical)* | |
219
+ | `sigma2` | [`viscous_friction`](#param-viscous_friction) | N·m·s/rad *(canonical)* | LuGre's own symbol (M3.lugre) for the same viscous coefficient. |
220
+ | `torque_coefficient` | [`kt`](#param-kt) | N·m/A *(canonical)* | Catalogue part key: check RMS against peak amperes (kt is per peak ampere). |
221
+ | `torque_constant` | [`kt`](#param-kt) | N·m/A *(canonical)* | Old user-part key: a geared part's source may state it at the output (kt × gear_ratio). |
222
+ | `voltage_v` | [`nominal_voltage`](#param-nominal_voltage) | V *(canonical)* | |
223
+
224
+ ## Packed names
225
+
226
+ Names for one array that carries several of these parameters; never read as one parameter.
227
+
228
+ | packed name | carries | order | note |
229
+ | --- | --- | --- | --- |
230
+ | `cogging` | [`harmonics`](#param-harmonics) | at least these; entry order not stated | M5.dcmotor's MuJoCo array (unit mujoco), 3 numbers: one cogging harmonic (harmonic, amplitude, phase) in MuJoCo's order, unverified here. |
231
+ | `inductance` | [`inductance_line_to_line`](#param-inductance_line_to_line) | at least these; entry order not stated | M5.dcmotor's MuJoCo array (unit mujoco), 2 numbers; per phase or line to line is MuJoCo's convention, unverified here. |
232
+ | `lugre` | [`sigma0`](#param-sigma0), [`sigma1`](#param-sigma1) | at least these; entry order not stated | M5.dcmotor's MuJoCo array (unit mujoco), 5 numbers: the M3.lugre terms in MuJoCo's order, unverified here. |
233
+ | `motorconst` | [`kt`](#param-kt) | at least these; entry order not stated | M5.dcmotor's MuJoCo array (unit mujoco), 2 numbers: sim2real reads the torque constant from it at the OUTPUT (kt × gear_ratio, unless the actuator's gear carries the ratio); the other entry is MuJoCo's, unverified here. |
234
+ | `nominal` | [`nominal_voltage`](#param-nominal_voltage) | at least these; entry order not stated | M5.dcmotor's MuJoCo array (unit mujoco), 3 numbers of nominal ratings; the other entries are MuJoCo's, unverified here. |
235
+ | `thermal` | [`thermal_resistance`](#param-thermal_resistance), [`thermal_time_constant`](#param-thermal_time_constant) | at least these; entry order not stated | M5.dcmotor's MuJoCo array (unit mujoco), 6 numbers; the rest and the order are MuJoCo's, unverified here. |
236
+ | `thermal_r_c` | [`thermal_resistance`](#param-thermal_resistance), [`thermal_time_constant`](#param-thermal_time_constant) | its full entry order | The rack twin's (K/W, s) pair. Its thermal model fits a Foster network of one or two poles; with two, thermal_resistance = ΣR_k and no single time constant holds. |
237
+
238
+ ## Deployment-only names
239
+
240
+ Names some model reads that are not the type's own: a deployment sets them, or the mount gives them.
241
+
242
+ - *assembly*: a property of where the part is mounted (the station's gravity, a base frame): the description's.
243
+ - *config*: a setting a deployment writes (a gain, a cap, a rate): read from its config, never fitted to the type.
244
+
245
+ | name | role | where it belongs |
246
+ | --- | --- | --- |
247
+ | `controller` | config | M5.dcmotor's MuJoCo controller array: the drive's control settings. |
248
+ | `gravity_nm` | assembly | The station's gravity torque on the joint: the description's. |
249
+ | `kd_nm_s_rad` | config | The drive's velocity gain: the deployment's config. |
250
+ | `kp_nm_rad` | config | The drive's position gain: the deployment's config. |
251
+ | `max_current_a` | config | The drive's current limit: the deployment's config. |
252
+ | `saturation` | config | M5.dcmotor's MuJoCo saturation array: the drive's ceilings. |
253
+
254
+ ## References
255
+
256
+ The works the rungs cite, by their names in [`robot_models.references`](../../references.py).
257
+
258
+ - <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 [`M5.wear`](#rung-m5-wear).
259
+ - <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 [`M1.datasheet`](#rung-m1-datasheet), [`M2.coulomb_viscous`](#rung-m2-coulomb_viscous), [`M3.stribeck`](#rung-m3-stribeck), [`M3.weakening_capture`](#rung-m3-weakening_capture).
260
+ - <a id="ref-canudas_1995"></a>**CANUDAS_1995**: Canudas de Wit, Olsson, Åström, Lischinsky (1995). A new model for control of systems with friction. IEEE Transactions on Automatic Control. [doi:10.1109/9.376053](https://doi.org/10.1109/9.376053). What the rung uses: LuGre: the dynamic friction model robotparts' M3.lugre is. Cited by [`M3.lugre`](#rung-m3-lugre), [`M3.weakening_capture`](#rung-m3-weakening_capture).
261
+ - <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 [`M5.wear`](#rung-m5-wear).
262
+ - <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).
263
+ - <a id="ref-hwangbo_2019_arxiv"></a>**HWANGBO_2019_ARXIV**: Hwangbo, Lee, Dosovitskiy, Bellicoso, Tsounis, Koltun, Hutter (2019). Learning agile and dynamic motor skills for legged robots. arXiv:1901.08652. [https://arxiv.org/abs/1901.08652](https://arxiv.org/abs/1901.08652) (preprint). What the rung uses: the open version. Cited by [`M7.learned`](#rung-m7-learned).
264
+ - <a id="ref-jahns_1996"></a>**JAHNS_1996**: Jahns, Soong (1996). Pulsating torque minimization techniques for permanent magnet AC motor drives—a review. IEEE Transactions on Industrial Electronics. [doi:10.1109/41.491356](https://doi.org/10.1109/41.491356). What the rung uses: cogging and commutation ripple as rotor harmonics. Cited by [`M4.ripple`](#rung-m4-ripple), [`M4.drivetrain`](#rung-m4-drivetrain).
265
+ - <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).
266
+ - <a id="ref-kovalev_2026"></a>**KOVALEV_2026**: Kovalev, Chaikovskaia, Davydenko, Gorbachev et al. (2026). Trajectory-based actuator identification via differentiable simulation. arXiv:2604.10351. [https://arxiv.org/abs/2604.10351](https://arxiv.org/abs/2604.10351) (preprint). What the rung uses: a structured servo fit vs an MLP vs a residual model on held-out position error. Cited by [`M6.residual`](#rung-m6-residual).
267
+ - <a id="ref-krause_2013"></a>**KRAUSE_2013**: Krause, Wasynczuk, Sudhoff, Pekarek (2013). Analysis of Electric Machinery and Drive Systems, 3rd ed. Wiley-IEEE Press. [doi:10.1002/9781118524336](https://doi.org/10.1002/9781118524336) (book). What the rung uses: the PM machine's electrical model: R, L, back-EMF, the voltage ceiling. Cited by [`M5.dcmotor`](#rung-m5-dcmotor), [`M5.envelope`](#rung-m5-envelope).
268
+ - <a id="ref-krishnan_2010"></a>**KRISHNAN_2010**: Krishnan (2010). Permanent Magnet Synchronous and Brushless DC Motor Drives. CRC Press. [doi:10.1201/9781420014235](https://doi.org/10.1201/9781420014235) (book). What the rung uses: field-oriented current loops of PM drives. Cited by [`M4.drivetrain`](#rung-m4-drivetrain), [`M5.envelope`](#rung-m5-envelope).
269
+ - <a id="ref-lu_meeker_1993"></a>**LU_MEEKER_1993**: Lu, Meeker (1993). Using degradation measures to estimate a time-to-failure distribution. Technometrics. [doi:10.1080/00401706.1993.10485038](https://doi.org/10.1080/00401706.1993.10485038). What the rung uses: a degradation path in usage, linear the simplest, crossing a failure threshold. Cited by [`M5.wear`](#rung-m5-wear).
270
+ - <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), [`M1.datasheet`](#rung-m1-datasheet).
271
+ - <a id="ref-mujoco_dcmotor"></a>**MUJOCO_DCMOTOR**: MuJoCo (2026). XML reference: the dcmotor actuator. [https://mujoco.readthedocs.io/en/stable/XMLreference.html#actuator-dcmotor](https://mujoco.readthedocs.io/en/stable/XMLreference.html#actuator-dcmotor) (doc). What the rung uses: robotparts' M5.dcmotor: electrics, heat, cogging and LuGre as MuJoCo takes them. Cited by [`M5.dcmotor`](#rung-m5-dcmotor), [`M5.envelope`](#rung-m5-envelope).
272
+ - <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).
273
+ - <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).
274
+ - <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.stribeck`](#rung-m3-stribeck), [`M3.load`](#rung-m3-load).
275
+ - <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).
276
+ - <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).
277
+ - <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).
278
+ - <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,7 @@
1
+ """Servo types: the integrated servo here, its constituents in bldc/ and gearbox/ (as user/parts/actuators/servo/)."""
2
+
3
+ from .bldc import BldcMotor
4
+ from .gearbox import Gearbox
5
+ from .integrated_servo import IntegratedServo
6
+
7
+ __all__ = ["BldcMotor", "Gearbox", "IntegratedServo"]
@@ -0,0 +1,186 @@
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
+ # bldc_motor
4
+
5
+ A brushless motor alone, at its shaft.
6
+
7
+ **9 rungs** · 35 parameters · 27 aliases · 1 packed names · 0 deployment-only names · folder `actuators/servo/bldc/` · datasheet class [`BldcMotor`](bldc_motor.py), whose typed fields rung `M1.datasheet` states.
8
+
9
+ In code: `ladders()["bldc_motor"]` 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: [Cad2Robot](../../../../../docs/TYPES.md#name-cad2robot), [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
+ Rung M1 states every `BldcMotor` field; the fitted rungs above it are sim2real's `motor` card, moved here, with a
17
+ Stribeck rung (M3: breakaway falling to Coulomb with shaft speed) between its bearing friction (M2) and its cogging
18
+ (M4). A bare motor has no reducer, so the output the ladder speaks of is the rotor itself, its shaft, and robotparts'
19
+ actuator rungs (M0 to M5) read as 1:1 actuators on it.
20
+
21
+ Spec: PEP 0004 §5.3 and §6.2.
22
+
23
+ ## The ladder
24
+
25
+ ```mermaid
26
+ flowchart BT
27
+ M0_ideal["M0.ideal<br/>An ideal torque source:<br/>kt·i on the rotor<br/>inertia"]
28
+ M1_datasheet["M1.datasheet<br/>The datasheet: the<br/>stated values, nothing<br/>fitted"]
29
+ M2_coulomb_viscous["M2.coulomb_viscous<br/>Coulomb and viscous<br/>bearing friction"]
30
+ M3_stribeck["M3.stribeck<br/>Stribeck friction:<br/>breakaway falling to<br/>Coulomb with shaft speed"]
31
+ M4_ripple["M4.ripple<br/>Cogging: rotor-periodic<br/>ripple"]
32
+ M5_dcmotor["M5.dcmotor<br/>DC motor electrics and<br/>heat"]
33
+ M5_wear["M5.wear<br/>Bearing friction that<br/>grows with hours"]
34
+ M6_residual{{"M6.residual<br/>Grey-box residual on<br/>M5.wear"}}
35
+ M7_learned(["M7.learned<br/>Black-box network"])
36
+ M0_ideal --> M1_datasheet
37
+ M1_datasheet --> M2_coulomb_viscous
38
+ M2_coulomb_viscous --> M3_stribeck
39
+ M3_stribeck --> M4_ripple
40
+ M4_ripple --> M5_dcmotor
41
+ M5_dcmotor --> M5_wear
42
+ M5_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_stribeck,M4_ripple,M5_dcmotor physics
49
+ class M5_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 torque source: kt·i on the rotor inertia<br>*robotparts' M0.ideal read as a 1:1 actuator, whose output is the rotor.* | — | `kt`, `rotor_inertia` | — | — | `τ = kt·i; rotor_inertia·ω̇ = τ − τ_load` | [SICILIANO_2009](#ref-siciliano_2009), [KRAUSE_2013](#ref-krause_2013) |
63
+ | <a id="rung-m1-datasheet"></a>`M1.datasheet` | The datasheet: the stated values, nothing fitted | [`M0.ideal`](#rung-m0-ideal) | — | every `BldcMotor` typed field its base does not hold: 26 names, each listed under [Vocabulary](#vocabulary) | — | `τ = kt·i on rotor_inertia, less coulomb_friction·sign(ω) + viscous_friction·ω when stated` | [KRAUSE_2013](#ref-krause_2013), [ARMSTRONG_1994](#ref-armstrong_1994) |
64
+ | <a id="rung-m2-coulomb_viscous"></a>`M2.coulomb_viscous` | Coulomb and viscous bearing friction<br>*the actuator's M2 on a bare motor: robotparts' actuator rungs cover its category, and its coverage ruler asks a BLDC motor's M2 for both.* | [`M1.datasheet`](#rung-m1-datasheet) | `coulomb_friction`, `viscous_friction` | — | — | `τ_r = coulomb_friction·sign(ω) + viscous_friction·ω` | [ARMSTRONG_1994](#ref-armstrong_1994), [OLSSON_1998](#ref-olsson_1998) |
65
+ | <a id="rung-m3-stribeck"></a>`M3.stribeck` | Stribeck friction: breakaway falling to Coulomb with shaft speed<br>*the actuator's M3.stribeck on a bare motor, whose output is the shaft: robotparts' coverage ruler asks a BLDC motor's M3 for both.* | [`M2.coulomb_viscous`](#rung-m2-coulomb_viscous) | `breakaway_torque`, `stribeck_velocity` | `stribeck_exponent` | — | `τ_r = (coulomb_friction + (breakaway_torque − coulomb_friction)·exp(−(\|ω\|/stribeck_velocity)^stribeck_exponent))·sign(ω) + viscous_friction·ω` | [ARMSTRONG_1994](#ref-armstrong_1994), [OLSSON_1998](#ref-olsson_1998) |
66
+ | <a id="rung-m4-ripple"></a>`M4.ripple` | Cogging: rotor-periodic ripple<br>*sim2real's motor M4; a datasheet's torque_ripple states one amplitude of it.* | [`M3.stribeck`](#rung-m3-stribeck) | `harmonics` | — | — | `τ = kt·i − Σ_k amplitude_k·sin(k·θ + phase_k)` | [JAHNS_1996](#ref-jahns_1996) |
67
+ | <a id="rung-m5-dcmotor"></a>`M5.dcmotor` | DC motor electrics and heat<br>*sim2real's motor M5 (today's model): the actuator's M5 on a bare motor, without LuGre friction.* | [`M4.ripple`](#rung-m4-ripple) | `resistance_line_to_line`, `inductance_line_to_line`, `thermal_resistance`, `thermal_time_constant` | — | — | `τ = kt·i, i the phase-current amplitude; per phase on a wye winding: V = (resistance_line_to_line/2)·i + (inductance_line_to_line/2)·di/dt + (kt/1.5)·ω, the per-phase EMF amplitude; thermal_time_constant·dΔT/dt = thermal_resistance·(3/4)·resistance_line_to_line·i² − ΔT, ΔT the winding's rise over ambient (the three phases' copper loss)` | [KRAUSE_2013](#ref-krause_2013), [KRISHNAN_2010](#ref-krishnan_2010), [MUJOCO_DCMOTOR](#ref-mujoco_dcmotor) |
68
+ | <a id="rung-m5-wear"></a>`M5.wear` | Bearing friction that grows with hours<br>wears `breakaway_torque`, `coulomb_friction`: see [Wear](#wear) | [`M5.dcmotor`](#rung-m5-dcmotor) | `friction_growth` | — | — | `breakaway_torque and coulomb_friction both grow by friction_growth·h (the Stribeck drop stays)` | [LU_MEEKER_1993](#ref-lu_meeker_1993), [ARMSTRONG_1994](#ref-armstrong_1994) |
69
+ | <a id="rung-m6-residual"></a>`M6.residual` | Grey-box residual on M5.wear | [`M5.wear`](#rung-m5-wear) | — | — | — | `M5.wear + an MLP residual shaft torque from 3 samples of q-axis current, rotor speed and winding temperature` | [NGUYEN_TUONG_2010](#ref-nguyen_tuong_2010), [ZENG_2020](#ref-zeng_2020) |
70
+ | <a id="rung-m7-learned"></a>`M7.learned` | Black-box network | — | — | — | — | `an MLP over 3 samples of q-axis current command and rotor speed → shaft torque` | [HWANGBO_2019](#ref-hwangbo_2019), [HWANGBO_2019_ARXIV](#ref-hwangbo_2019_arxiv) |
71
+
72
+ ## Wear
73
+
74
+ Which parameter grows with use, with what, by which law, at which rate.
75
+
76
+ | rung | parameter that wears | grows with | law | rate |
77
+ | --- | --- | --- | --- | --- |
78
+ | [`M5.wear`](#rung-m5-wear) | [`breakaway_torque`](#param-breakaway_torque) | deployment hours (h) | linear: `p(u) = p0 + k·u` | [`friction_growth`](#param-friction_growth) |
79
+ | [`M5.wear`](#rung-m5-wear) | [`coulomb_friction`](#param-coulomb_friction) | deployment hours (h) | linear: `p(u) = p0 + k·u` | [`friction_growth`](#param-friction_growth) |
80
+
81
+ ## Vocabulary
82
+
83
+ Every parameter the ladder holds, by the rung that first reads it. — as a unit: dimensionless (a ratio or a count).
84
+
85
+ | parameter | SI unit | shape | definition | first read on |
86
+ | --- | --- | --- | --- | --- |
87
+ | <a id="param-kt"></a>`kt` | N·m/A | scalar | Torque constant: ROTOR torque per ampere of phase-current amplitude. A geared part's source may state it at the output: say at='output'. | [`M0.ideal`](#rung-m0-ideal) |
88
+ | <a id="param-rotor_inertia"></a>`rotor_inertia` | kg·m² | scalar | The rotor's moment of inertia on the INPUT (rotor) side. Read as output-side it is off by gear_ratio²; a source stating the reflected value says at='output'. | [`M0.ideal`](#rung-m0-ideal) |
89
+ | <a id="param-peak_torque"></a>`peak_torque` | N·m | scalar | Peak (stall, max) torque at the output. | [`M1.datasheet`](#rung-m1-datasheet) (when stated) |
90
+ | <a id="param-rated_torque"></a>`rated_torque` | N·m | scalar | Continuous (rated) torque at the output. | [`M1.datasheet`](#rung-m1-datasheet) (when stated) |
91
+ | <a id="param-max_output_speed"></a>`max_output_speed` | rad/s | scalar | No-load (maximum) speed at the output. | [`M1.datasheet`](#rung-m1-datasheet) (when stated) |
92
+ | <a id="param-rated_speed"></a>`rated_speed` | rad/s | scalar | Speed at rated torque, at the output. | [`M1.datasheet`](#rung-m1-datasheet) (when stated) |
93
+ | <a id="param-rated_power"></a>`rated_power` | W | scalar | Continuous MECHANICAL output power, rated torque × rated speed; an electrical input power is not this. | [`M1.datasheet`](#rung-m1-datasheet) (when stated) |
94
+ | <a id="param-nominal_voltage"></a>`nominal_voltage` | V | scalar | Nominal supply voltage. | [`M1.datasheet`](#rung-m1-datasheet) (when stated) |
95
+ | <a id="param-voltage_min"></a>`voltage_min` | V | scalar | Lowest supply voltage the part is rated for. | [`M1.datasheet`](#rung-m1-datasheet) (when stated) |
96
+ | <a id="param-voltage_max"></a>`voltage_max` | V | scalar | Highest supply voltage the part is rated for. | [`M1.datasheet`](#rung-m1-datasheet) (when stated) |
97
+ | <a id="param-rated_phase_current"></a>`rated_phase_current` | A | scalar | Continuous phase current at rated torque (catalogue name). | [`M1.datasheet`](#rung-m1-datasheet) (when stated) |
98
+ | <a id="param-max_phase_current"></a>`max_phase_current` | A | scalar | Peak phase current, at peak torque (catalogue name). | [`M1.datasheet`](#rung-m1-datasheet) (when stated) |
99
+ | <a id="param-kv"></a>`kv` | rad/(s·V) | scalar | Velocity constant: no-load ROTOR speed per volt (line-to-line peak back-EMF). A geared part's source may state it at the output: say at='output'. | [`M1.datasheet`](#rung-m1-datasheet) (when stated) |
100
+ | <a id="param-back_emf_constant"></a>`back_emf_constant` | V·s/rad | scalar | Line-to-line back-EMF per speed (catalogue name). | [`M1.datasheet`](#rung-m1-datasheet) (when stated) |
101
+ | <a id="param-pole_pairs"></a>`pole_pairs` | — | integer | Magnetic pole pairs. | [`M1.datasheet`](#rung-m1-datasheet) (when stated) |
102
+ | <a id="param-encoder_lines"></a>`encoder_lines` | — | integer | Encoder lines (pulses) per rotor turn (catalogue name). | [`M1.datasheet`](#rung-m1-datasheet) (when stated) |
103
+ | <a id="param-encoder_bits"></a>`encoder_bits` | — | integer | Encoder resolution in bits per rotor turn (catalogue name). | [`M1.datasheet`](#rung-m1-datasheet) (when stated) |
104
+ | <a id="param-mass"></a>`mass` | kg | scalar | Mass as sold, without optional accessories. | [`M1.datasheet`](#rung-m1-datasheet) (when stated) |
105
+ | <a id="param-torque_ripple"></a>`torque_ripple` | N·m | scalar | Amplitude of a rotor-periodic torque harmonic at the output (cogging); the note says which harmonic. | [`M1.datasheet`](#rung-m1-datasheet) (when stated) |
106
+ | <a id="param-outer_diameter"></a>`outer_diameter` | m | scalar | Largest diameter of a round housing. | [`M1.datasheet`](#rung-m1-datasheet) (when stated) |
107
+ | <a id="param-axial_length"></a>`axial_length` | m | scalar | Overall length of a round housing along its axis. | [`M1.datasheet`](#rung-m1-datasheet) (when stated) |
108
+ | <a id="param-flange_size"></a>`flange_size` | m | scalar | Square flange edge (catalogue name). | [`M1.datasheet`](#rung-m1-datasheet) (when stated) |
109
+ | <a id="param-body_length"></a>`body_length` | m | scalar | Body length behind the flange, without the shaft (catalogue name). | [`M1.datasheet`](#rung-m1-datasheet) (when stated) |
110
+ | <a id="param-shaft_diameter"></a>`shaft_diameter` | m | scalar | Output shaft diameter (catalogue name). | [`M1.datasheet`](#rung-m1-datasheet) (when stated) |
111
+ | <a id="param-coulomb_friction"></a>`coulomb_friction` | N·m | scalar | Coulomb friction torque at the output. | [`M1.datasheet`](#rung-m1-datasheet) (when stated); needed from [`M2.coulomb_viscous`](#rung-m2-coulomb_viscous) |
112
+ | <a id="param-viscous_friction"></a>`viscous_friction` | N·m·s/rad | scalar | Viscous friction coefficient at the output. | [`M1.datasheet`](#rung-m1-datasheet) (when stated); needed from [`M2.coulomb_viscous`](#rung-m2-coulomb_viscous) |
113
+ | <a id="param-resistance_line_to_line"></a>`resistance_line_to_line` | Ω | scalar | Winding resistance between two leads (line to line); a page's 'phase to phase' is this. | [`M1.datasheet`](#rung-m1-datasheet) (when stated); needed from [`M5.dcmotor`](#rung-m5-dcmotor) |
114
+ | <a id="param-inductance_line_to_line"></a>`inductance_line_to_line` | H | scalar | Winding inductance between two leads (line to line). | [`M1.datasheet`](#rung-m1-datasheet) (when stated); needed from [`M5.dcmotor`](#rung-m5-dcmotor) |
115
+ | <a id="param-breakaway_torque"></a>`breakaway_torque` | N·m | scalar | Static friction at the output: the torque that starts it moving from rest, the top of the Stribeck curve. | [`M3.stribeck`](#rung-m3-stribeck) |
116
+ | <a id="param-stribeck_velocity"></a>`stribeck_velocity` | rad/s | scalar | Output speed over which friction falls from breakaway_torque to coulomb_friction. | [`M3.stribeck`](#rung-m3-stribeck) |
117
+ | <a id="param-stribeck_exponent"></a>`stribeck_exponent` | — | scalar | Shape exponent of the Stribeck curve, how sharply friction falls with speed; 2 when absent. | [`M3.stribeck`](#rung-m3-stribeck) (when stated) |
118
+ | <a id="param-harmonics"></a>`harmonics` | N·m | list | Rotor-periodic torque harmonics at the output, a list of (rotor_harmonic, amplitude, phase): cogging and commutation ripple. | [`M4.ripple`](#rung-m4-ripple) |
119
+ | <a id="param-thermal_resistance"></a>`thermal_resistance` | K/W | scalar | Winding-to-ambient thermal resistance: winding temperature rise per watt of copper loss. | [`M5.dcmotor`](#rung-m5-dcmotor) |
120
+ | <a id="param-thermal_time_constant"></a>`thermal_time_constant` | s | scalar | Time constant of the winding temperature's first-order rise. | [`M5.dcmotor`](#rung-m5-dcmotor) |
121
+ | <a id="param-friction_growth"></a>`friction_growth` | N·m/h | scalar | How fast the friction level grows per deployment hour (seals, grease, bearings); on a Stribeck curve breakaway and Coulomb grow together. | [`M5.wear`](#rung-m5-wear) |
122
+
123
+ ## Aliases
124
+
125
+ 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.
126
+
127
+ | alias | canonical | unit | note |
128
+ | --- | --- | --- | --- |
129
+ | `bearing_friction_growth_nm_per_h` | [`friction_growth`](#param-friction_growth) | N·m/h *(canonical)* | |
130
+ | `bearing_friction_nm` | [`coulomb_friction`](#param-coulomb_friction) | N·m *(canonical)* | A bare motor's Coulomb friction is its bearings'. |
131
+ | `cogging` | [`torque_ripple`](#param-torque_ripple) | N·m *(canonical)* | sim2real's motor card: one cogging amplitude; its harmonic is not stated. |
132
+ | `encoder_counts` | [`encoder_lines`](#param-encoder_lines) | dimensionless *(canonical)* | Counts per turn: 4 × lines on a quadrature encoder. |
133
+ | `inductance` | [`inductance_line_to_line`](#param-inductance_line_to_line) | H | sim2real's motor card: the convention as for resistance. |
134
+ | `length_mm` | [`axial_length`](#param-axial_length) | mm | |
135
+ | `mass_kg` | [`mass`](#param-mass) | kg *(canonical)* | |
136
+ | `max_speed` | [`max_output_speed`](#param-max_output_speed) | rad/s *(canonical)* | Old user-part key: may be a mechanical limit rather than the no-load speed. |
137
+ | `motorconst` | [`kt`](#param-kt) | N·m/A *(canonical)* | sim2real's motor card: the scalar kt, rotor side (robotparts' dcmotor packs an array under this name). |
138
+ | `noload_speed` | [`max_output_speed`](#param-max_output_speed) | rad/s *(canonical)* | Old user-part key: its unit is the part file's; check it before converting. |
139
+ | `noload_speed_rpm` | [`max_output_speed`](#param-max_output_speed) | rpm | |
140
+ | `od_mm` | [`outer_diameter`](#param-outer_diameter) | mm | |
141
+ | `peak_current_a` | [`max_phase_current`](#param-max_phase_current) | A *(canonical)* | |
142
+ | `peak_torque_nm` | [`peak_torque`](#param-peak_torque) | N·m *(canonical)* | |
143
+ | `phase_inductance` | [`inductance_line_to_line`](#param-inductance_line_to_line) | H *(canonical)* | Old user-part key: per phase is half of line to line on a wye winding. |
144
+ | `phase_inductance_h` | [`inductance_line_to_line`](#param-inductance_line_to_line) | H | Per phase (Cad2Robot's motor): half of line to line on a wye winding. |
145
+ | `phase_resistance` | [`resistance_line_to_line`](#param-resistance_line_to_line) | Ω *(canonical)* | Old user-part key: a 'phase to phase' value is line to line; a per-phase value is half of it on a wye winding. |
146
+ | `phase_resistance_ohm` | [`resistance_line_to_line`](#param-resistance_line_to_line) | Ω | Per phase (sim2real's servo, Cad2Robot's motor): line to line is twice it on a wye winding. |
147
+ | `rated_current_a` | [`rated_phase_current`](#param-rated_phase_current) | A *(canonical)* | |
148
+ | `rated_power_w` | [`rated_power`](#param-rated_power) | W *(canonical)* | |
149
+ | `rated_speed_rpm` | [`rated_speed`](#param-rated_speed) | rpm | |
150
+ | `rated_torque_nm` | [`rated_torque`](#param-rated_torque) | N·m *(canonical)* | |
151
+ | `resistance` | [`resistance_line_to_line`](#param-resistance_line_to_line) | Ω | sim2real's motor card, after robotparts' dcmotor: per phase or line to line is not stated; check it before converting. |
152
+ | `rotor_inertia_kg_m2` | [`rotor_inertia`](#param-rotor_inertia) | kg·m² *(canonical)* | |
153
+ | `torque_coefficient` | [`kt`](#param-kt) | N·m/A *(canonical)* | Catalogue part key: check RMS against peak amperes (kt is per peak ampere). |
154
+ | `torque_constant` | [`kt`](#param-kt) | N·m/A *(canonical)* | Old user-part key: a geared part's source may state it at the output (kt × gear_ratio). |
155
+ | `voltage_v` | [`nominal_voltage`](#param-nominal_voltage) | V *(canonical)* | |
156
+
157
+ ## Packed names
158
+
159
+ Names for one array that carries several of these parameters; never read as one parameter.
160
+
161
+ | packed name | carries | order | note |
162
+ | --- | --- | --- | --- |
163
+ | `thermal` | [`thermal_resistance`](#param-thermal_resistance), [`thermal_time_constant`](#param-thermal_time_constant) | its full entry order | sim2real's motor card: (K/W, s). |
164
+
165
+ ## Deployment-only names
166
+
167
+ Names some model reads that are not the type's own: a deployment sets them, or the mount gives them.
168
+
169
+ None.
170
+
171
+ ## References
172
+
173
+ The works the rungs cite, by their names in [`robot_models.references`](../../../references.py).
174
+
175
+ - <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 [`M1.datasheet`](#rung-m1-datasheet), [`M2.coulomb_viscous`](#rung-m2-coulomb_viscous), [`M3.stribeck`](#rung-m3-stribeck), [`M5.wear`](#rung-m5-wear).
176
+ - <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).
177
+ - <a id="ref-hwangbo_2019_arxiv"></a>**HWANGBO_2019_ARXIV**: Hwangbo, Lee, Dosovitskiy, Bellicoso, Tsounis, Koltun, Hutter (2019). Learning agile and dynamic motor skills for legged robots. arXiv:1901.08652. [https://arxiv.org/abs/1901.08652](https://arxiv.org/abs/1901.08652) (preprint). What the rung uses: the open version. Cited by [`M7.learned`](#rung-m7-learned).
178
+ - <a id="ref-jahns_1996"></a>**JAHNS_1996**: Jahns, Soong (1996). Pulsating torque minimization techniques for permanent magnet AC motor drives—a review. IEEE Transactions on Industrial Electronics. [doi:10.1109/41.491356](https://doi.org/10.1109/41.491356). What the rung uses: cogging and commutation ripple as rotor harmonics. Cited by [`M4.ripple`](#rung-m4-ripple).
179
+ - <a id="ref-krause_2013"></a>**KRAUSE_2013**: Krause, Wasynczuk, Sudhoff, Pekarek (2013). Analysis of Electric Machinery and Drive Systems, 3rd ed. Wiley-IEEE Press. [doi:10.1002/9781118524336](https://doi.org/10.1002/9781118524336) (book). What the rung uses: the PM machine's electrical model: R, L, back-EMF, the voltage ceiling. Cited by [`M0.ideal`](#rung-m0-ideal), [`M1.datasheet`](#rung-m1-datasheet), [`M5.dcmotor`](#rung-m5-dcmotor).
180
+ - <a id="ref-krishnan_2010"></a>**KRISHNAN_2010**: Krishnan (2010). Permanent Magnet Synchronous and Brushless DC Motor Drives. CRC Press. [doi:10.1201/9781420014235](https://doi.org/10.1201/9781420014235) (book). What the rung uses: field-oriented current loops of PM drives. Cited by [`M5.dcmotor`](#rung-m5-dcmotor).
181
+ - <a id="ref-lu_meeker_1993"></a>**LU_MEEKER_1993**: Lu, Meeker (1993). Using degradation measures to estimate a time-to-failure distribution. Technometrics. [doi:10.1080/00401706.1993.10485038](https://doi.org/10.1080/00401706.1993.10485038). What the rung uses: a degradation path in usage, linear the simplest, crossing a failure threshold. Cited by [`M5.wear`](#rung-m5-wear).
182
+ - <a id="ref-mujoco_dcmotor"></a>**MUJOCO_DCMOTOR**: MuJoCo (2026). XML reference: the dcmotor actuator. [https://mujoco.readthedocs.io/en/stable/XMLreference.html#actuator-dcmotor](https://mujoco.readthedocs.io/en/stable/XMLreference.html#actuator-dcmotor) (doc). What the rung uses: robotparts' M5.dcmotor: electrics, heat, cogging and LuGre as MuJoCo takes them. Cited by [`M5.dcmotor`](#rung-m5-dcmotor).
183
+ - <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).
184
+ - <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.stribeck`](#rung-m3-stribeck).
185
+ - <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).
186
+ - <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).
@@ -0,0 +1,5 @@
1
+ """Bare brushless motors (user/parts/actuators/servo/bldc/)."""
2
+
3
+ from .bldc_motor import BldcMotor
4
+
5
+ __all__ = ["BldcMotor"]