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,93 @@
1
+ """BldcMotor: the typed datasheet fields of a bare brushless motor (a PMSM / BLDC with its own encoder, no reducer).
2
+
3
+ The fields are rung 1 of the type's model ladder, "the datasheet: the stated values, nothing fitted" (robotparts
4
+ registry `model_rungs.actuator`); the fitted rungs above it move here from sim2real's type cards (the layering
5
+ decision's step 7), not in this file.
6
+
7
+ Names are robotparts registry keys; the ones marked `catalogue name` are not registry keys yet but are the names the
8
+ catalogue already uses (PEP 0003 §3). Torques and speeds are at the part's output, which on a bare motor is its shaft.
9
+ """
10
+
11
+ from __future__ import annotations
12
+
13
+ from dataclasses import dataclass
14
+ from typing import ClassVar
15
+
16
+ from ....datasheet import ELECTRICAL, MECHANICAL, PERFORMANCE, Datasheet, Field, Stated
17
+ from ....datasheet.units import (
18
+ BACK_EMF_CONSTANT,
19
+ COUNT,
20
+ CURRENT,
21
+ DAMPING,
22
+ INDUCTANCE,
23
+ INERTIA,
24
+ LENGTH,
25
+ MASS,
26
+ POWER,
27
+ RESISTANCE,
28
+ SPEED,
29
+ TORQUE,
30
+ TORQUE_CONSTANT,
31
+ VELOCITY_CONSTANT,
32
+ VOLTAGE,
33
+ )
34
+
35
+
36
+ @dataclass(frozen=True)
37
+ class BldcMotor(Datasheet):
38
+ """A bare brushless motor's datasheet. One `Stated` per field, or None when no source states it."""
39
+
40
+ # robotparts registry key_specs["actuator"]
41
+ KEY_SPECS: ClassVar[tuple[str, ...]] = ("peak_torque", "rated_torque", "max_output_speed", "mass")
42
+
43
+ # --- performance ---
44
+ peak_torque: Stated | None = Field(TORQUE, "Peak (stall, max) torque at the output.", group=PERFORMANCE, positive=True)
45
+ rated_torque: Stated | None = Field(TORQUE, "Continuous (rated) torque at the output.", group=PERFORMANCE, positive=True)
46
+ max_output_speed: Stated | None = Field(SPEED, "No-load (maximum) speed at the output.", group=PERFORMANCE, positive=True)
47
+ rated_speed: Stated | None = Field(SPEED, "Speed at rated torque, at the output.", group=PERFORMANCE, positive=True)
48
+ rated_power: Stated | None = Field(POWER, "Continuous MECHANICAL output power, rated torque × rated speed; an "
49
+ "electrical input power is not this.", group=PERFORMANCE, positive=True)
50
+
51
+ # --- electrical ---
52
+ nominal_voltage: Stated | None = Field(VOLTAGE, "Nominal supply voltage.", group=ELECTRICAL, positive=True)
53
+ voltage_min: Stated | None = Field(VOLTAGE, "Lowest supply voltage the part is rated for.", group=ELECTRICAL)
54
+ voltage_max: Stated | None = Field(VOLTAGE, "Highest supply voltage the part is rated for.", group=ELECTRICAL)
55
+ rated_phase_current: Stated | None = Field(CURRENT, "Continuous phase current at rated torque (catalogue name).",
56
+ group=ELECTRICAL, positive=True)
57
+ max_phase_current: Stated | None = Field(CURRENT, "Peak phase current, at peak torque (catalogue name).",
58
+ group=ELECTRICAL, positive=True)
59
+ kv: Stated | None = Field(VELOCITY_CONSTANT, "Velocity constant: no-load ROTOR speed per volt (line-to-line peak "
60
+ "back-EMF). A geared part's source may state it at the output: say at='output'.",
61
+ group=ELECTRICAL, positive=True, side="rotor", reflect=1)
62
+ kt: Stated | None = Field(TORQUE_CONSTANT, "Torque constant: ROTOR torque per ampere of phase-current amplitude. "
63
+ "A geared part's source may state it at the output: say at='output'.",
64
+ group=ELECTRICAL, positive=True, side="rotor", reflect=-1)
65
+ back_emf_constant: Stated | None = Field(BACK_EMF_CONSTANT, "Line-to-line back-EMF per speed (catalogue name).",
66
+ group=ELECTRICAL, positive=True)
67
+ resistance_line_to_line: Stated | None = Field(RESISTANCE, "Winding resistance between two leads (line to line); "
68
+ "a page's 'phase to phase' is this.", group=ELECTRICAL, positive=True)
69
+ inductance_line_to_line: Stated | None = Field(INDUCTANCE, "Winding inductance between two leads (line to line).",
70
+ group=ELECTRICAL, positive=True)
71
+ pole_pairs: Stated | None = Field(COUNT, "Magnetic pole pairs.", group=ELECTRICAL, kind="integer", positive=True)
72
+ encoder_lines: Stated | None = Field(COUNT, "Encoder lines (pulses) per rotor turn (catalogue name).",
73
+ group=ELECTRICAL, kind="integer", positive=True)
74
+ encoder_bits: Stated | None = Field(COUNT, "Encoder resolution in bits per rotor turn (catalogue name).",
75
+ group=ELECTRICAL, kind="integer", positive=True)
76
+
77
+ # --- mechanical ---
78
+ mass: Stated | None = Field(MASS, "Mass as sold, without optional accessories.", group=MECHANICAL, positive=True)
79
+ rotor_inertia: Stated | None = Field(INERTIA, "The rotor's moment of inertia on the INPUT (rotor) side. Read as "
80
+ "output-side it is off by gear_ratio²; a source stating the reflected value "
81
+ "says at='output'.", group=MECHANICAL, positive=True, side="rotor", reflect=-2)
82
+ coulomb_friction: Stated | None = Field(TORQUE, "Coulomb friction torque at the output.", group=MECHANICAL)
83
+ viscous_friction: Stated | None = Field(DAMPING, "Viscous friction coefficient at the output.", group=MECHANICAL)
84
+ torque_ripple: Stated | None = Field(TORQUE, "Amplitude of a rotor-periodic torque harmonic at the output (cogging); "
85
+ "the note says which harmonic.", group=MECHANICAL)
86
+ outer_diameter: Stated | None = Field(LENGTH, "Largest diameter of a round housing.", group=MECHANICAL, positive=True)
87
+ axial_length: Stated | None = Field(LENGTH, "Overall length of a round housing along its axis.", group=MECHANICAL,
88
+ positive=True)
89
+ flange_size: Stated | None = Field(LENGTH, "Square flange edge (catalogue name).", group=MECHANICAL, positive=True)
90
+ body_length: Stated | None = Field(LENGTH, "Body length behind the flange, without the shaft (catalogue name).",
91
+ group=MECHANICAL, positive=True)
92
+ shaft_diameter: Stated | None = Field(LENGTH, "Output shaft diameter (catalogue name).", group=MECHANICAL,
93
+ positive=True)
@@ -0,0 +1,268 @@
1
+ """A brushless motor alone, at its shaft: its ladder of models (PEP 0004).
2
+
3
+ Rung M1 states every `BldcMotor` field; the fitted rungs above it are sim2real's `motor` card, moved here, with a
4
+ Stribeck rung (M3: breakaway falling to Coulomb with shaft speed) between its bearing friction (M2) and its cogging
5
+ (M4). A bare motor has no reducer, so the output the ladder speaks of is the rotor itself, its shaft, and robotparts'
6
+ actuator rungs (M0 to M5) read as 1:1 actuators on it.
7
+
8
+ Spec: PEP 0004 §5.3 and §6.2.
9
+ """
10
+
11
+ from __future__ import annotations
12
+
13
+ from robot_models import references
14
+ from robot_models.ladder import Alias, Ladder, Packed, Parameter, Rung, Wear, datasheet_vocabulary
15
+
16
+ from .bldc_motor import BldcMotor
17
+
18
+ # --- the vocabulary, grouped by the rung that first reads it ----------------------------------------------------------
19
+
20
+ DATASHEET = {parameter.name: parameter for parameter in datasheet_vocabulary(BldcMotor)}
21
+
22
+ # WHY the datasheet's own Parameters and nothing re-typed (PEP 0003 §6, PEP 0004 decision 3): names, SI units and
23
+ # definitions come from the BldcMotor class, so the datasheet and the ladder can never hold two spellings of a field.
24
+ M0_NEEDS = ("kt", "rotor_inertia")
25
+ M2_NEEDS = ("coulomb_friction", "viscous_friction")
26
+ M5_NEEDS = ("resistance_line_to_line", "inductance_line_to_line")
27
+
28
+ M0_VOCABULARY = tuple(DATASHEET[name] for name in M0_NEEDS)
29
+ M1_VOCABULARY = tuple(parameter for name, parameter in DATASHEET.items()
30
+ if name not in (*M0_NEEDS, *M2_NEEDS, *M5_NEEDS))
31
+ M2_VOCABULARY = tuple(DATASHEET[name] for name in M2_NEEDS)
32
+
33
+ # WHY the integrated servo's own definitions, "at the output", word for word: a bare motor's output is its shaft (the
34
+ # docstring says so once), and the datasheet's coulomb_friction and viscous_friction say "at the output" too, so the
35
+ # whole friction curve reads at one point and the README matches PEP 0004 §5.3 (amendment 1).
36
+ M3_VOCABULARY = (
37
+ Parameter(
38
+ name="breakaway_torque", unit="N·m",
39
+ definition=("Static friction at the output: the torque that starts it moving from rest, the top of the "
40
+ "Stribeck curve."),
41
+ ),
42
+ Parameter(
43
+ name="stribeck_velocity", unit="rad/s",
44
+ definition="Output speed over which friction falls from breakaway_torque to coulomb_friction.",
45
+ ),
46
+ Parameter(
47
+ name="stribeck_exponent", unit="",
48
+ definition="Shape exponent of the Stribeck curve, how sharply friction falls with speed; 2 when absent.",
49
+ ),
50
+ )
51
+
52
+ M4_VOCABULARY = (
53
+ Parameter(
54
+ name="harmonics", unit="N·m", shape="list",
55
+ definition=("Rotor-periodic torque harmonics at the output, a list of (rotor_harmonic, amplitude, phase): "
56
+ "cogging and commutation ripple."),
57
+ ),
58
+ )
59
+
60
+ M5_VOCABULARY = (
61
+ *(DATASHEET[name] for name in M5_NEEDS),
62
+ Parameter(
63
+ name="thermal_resistance", unit="K/W",
64
+ definition=("Winding-to-ambient thermal resistance: winding temperature rise per watt of copper loss."),
65
+ ),
66
+ Parameter(
67
+ name="thermal_time_constant", unit="s",
68
+ definition="Time constant of the winding temperature's first-order rise.",
69
+ ),
70
+ )
71
+
72
+ WEAR_VOCABULARY = (
73
+ Parameter(
74
+ name="friction_growth", unit="N·m/h",
75
+ definition=("How fast the friction level grows per deployment hour (seals, grease, bearings); on a Stribeck "
76
+ "curve breakaway and Coulomb grow together."),
77
+ ),
78
+ )
79
+
80
+ VOCABULARY = (
81
+ *M0_VOCABULARY, *M1_VOCABULARY, *M2_VOCABULARY, *M3_VOCABULARY, *M4_VOCABULARY, *M5_VOCABULARY, *WEAR_VOCABULARY,
82
+ )
83
+
84
+ # --- the rungs, M0 upward ---------------------------------------------------------------------------------------------
85
+
86
+ # WHY computed from the class: M1.datasheet reads every typed field not already needed at M0 (PEP 0004 decision 3), and
87
+ # robotparts' M1 marks all its terms required: false, so none is needed here beyond M0.
88
+ M1_OPTIONAL = tuple(name for name in BldcMotor.typed_fields() if name not in M0_NEEDS)
89
+
90
+ # WHY these usages: the motor card counts a deployment's hours; both friction levels grow with them (M5.wear).
91
+ DEPLOYMENT_HOURS = "deployment hours"
92
+ HOURS_UNIT = "h"
93
+
94
+ RUNGS = (
95
+ Rung(
96
+ level=0, name="ideal",
97
+ title="An ideal torque source: kt·i on the rotor inertia",
98
+ base=None,
99
+ adds=M0_NEEDS,
100
+ equation="τ = kt·i; rotor_inertia·ω̇ = τ − τ_load",
101
+ references=(references.SICILIANO_2009, references.KRAUSE_2013),
102
+ note="robotparts' M0.ideal read as a 1:1 actuator, whose output is the rotor.",
103
+ ),
104
+ Rung(
105
+ level=1, name="datasheet",
106
+ title="The datasheet: the stated values, nothing fitted",
107
+ base="M0.ideal",
108
+ optional=M1_OPTIONAL,
109
+ equation="τ = kt·i on rotor_inertia, less coulomb_friction·sign(ω) + viscous_friction·ω when stated",
110
+ references=(references.KRAUSE_2013, references.ARMSTRONG_1994),
111
+ ),
112
+ Rung(
113
+ level=2, name="coulomb_viscous",
114
+ title="Coulomb and viscous bearing friction",
115
+ base="M1.datasheet",
116
+ adds=M2_NEEDS,
117
+ equation="τ_r = coulomb_friction·sign(ω) + viscous_friction·ω",
118
+ references=(references.ARMSTRONG_1994, references.OLSSON_1998),
119
+ note=("the actuator's M2 on a bare motor: robotparts' actuator rungs cover its category, and its coverage "
120
+ "ruler asks a BLDC motor's M2 for both."),
121
+ ),
122
+ # WHY an M3 the motor card does not have (PEP 0004 amendment 1): robotparts' coverage ruler asks a BLDC motor's M3
123
+ # for breakaway_torque and stribeck_velocity, and sim2real's motor card has no M3 to say otherwise. No code
124
+ # folder: the eight rung folders are the integrated servo's (PEP 0004 §11, call 6); this is that model at the shaft.
125
+ Rung(
126
+ level=3, name="stribeck",
127
+ title="Stribeck friction: breakaway falling to Coulomb with shaft speed",
128
+ base="M2.coulomb_viscous",
129
+ adds=("breakaway_torque", "stribeck_velocity"),
130
+ optional=("stribeck_exponent",),
131
+ equation=("τ_r = (coulomb_friction + (breakaway_torque − coulomb_friction)·exp(−(|ω|/stribeck_velocity)"
132
+ "^stribeck_exponent))·sign(ω) + viscous_friction·ω"),
133
+ references=(references.ARMSTRONG_1994, references.OLSSON_1998),
134
+ note=("the actuator's M3.stribeck on a bare motor, whose output is the shaft: robotparts' coverage ruler asks "
135
+ "a BLDC motor's M3 for both."),
136
+ ),
137
+ Rung(
138
+ level=4, name="ripple",
139
+ title="Cogging: rotor-periodic ripple",
140
+ base="M3.stribeck",
141
+ adds=("harmonics",),
142
+ equation="τ = kt·i − Σ_k amplitude_k·sin(k·θ + phase_k)",
143
+ references=(references.JAHNS_1996,),
144
+ note="sim2real's motor M4; a datasheet's torque_ripple states one amplitude of it.",
145
+ ),
146
+ Rung(
147
+ level=5, name="dcmotor",
148
+ title="DC motor electrics and heat",
149
+ base="M4.ripple",
150
+ adds=(*M5_NEEDS, "thermal_resistance", "thermal_time_constant"),
151
+ # WHY the EMF from kt: kt is per phase-current amplitude, so τ = (3/2)·λ·i and the per-phase EMF amplitude is
152
+ # λ·ω = (kt/1.5)·ω, from a name this rung needs; it equals back_emf_constant/√3 only for a line-to-line PEAK
153
+ # constant, and back_emf_constant is read at M1 alone, when stated, with its rms-or-peak convention unsaid.
154
+ # The servo's M5.envelope and foc_controller's M2.ceiling_heat write the same kt/1.5. WHY the 3/4:
155
+ # resistance_line_to_line is line to line, so the three-phase copper loss is
156
+ # (3/2)·i²·R_phase = (3/4)·i²·resistance_line_to_line.
157
+ equation=("τ = kt·i, i the phase-current amplitude; per phase on a wye winding: "
158
+ "V = (resistance_line_to_line/2)·i + (inductance_line_to_line/2)·di/dt "
159
+ "+ (kt/1.5)·ω, the per-phase EMF amplitude; "
160
+ "thermal_time_constant·dΔT/dt = thermal_resistance·(3/4)·resistance_line_to_line·i² − ΔT, "
161
+ "ΔT the winding's rise over ambient (the three phases' copper loss)"),
162
+ references=(references.KRAUSE_2013, references.KRISHNAN_2010, references.MUJOCO_DCMOTOR),
163
+ note="sim2real's motor M5 (today's model): the actuator's M5 on a bare motor, without LuGre friction.",
164
+ ),
165
+ Rung(
166
+ level=5, name="wear",
167
+ title="Bearing friction that grows with hours",
168
+ base="M5.dcmotor",
169
+ adds=("friction_growth",),
170
+ # WHY both levels at one rate: growing Coulomb alone would pass breakaway and turn the Stribeck term
171
+ # negative (friction rising with speed, no static peak); the drop between them stays as fitted.
172
+ wears=(
173
+ Wear(parameter="breakaway_torque", usage=DEPLOYMENT_HOURS, usage_unit=HOURS_UNIT, law="linear",
174
+ rate="friction_growth"),
175
+ Wear(parameter="coulomb_friction", usage=DEPLOYMENT_HOURS, usage_unit=HOURS_UNIT, law="linear",
176
+ rate="friction_growth"),
177
+ ),
178
+ equation=("breakaway_torque and coulomb_friction both grow by friction_growth·h "
179
+ "(the Stribeck drop stays)"),
180
+ references=(references.LU_MEEKER_1993, references.ARMSTRONG_1994),
181
+ ),
182
+ Rung(
183
+ level=6, name="residual", kind="residual",
184
+ title="Grey-box residual on M5.wear",
185
+ base="M5.wear",
186
+ equation=("M5.wear + an MLP residual shaft torque from 3 samples of q-axis current, rotor speed and winding "
187
+ "temperature"),
188
+ references=(references.NGUYEN_TUONG_2010, references.ZENG_2020),
189
+ ),
190
+ Rung(
191
+ level=7, name="learned", kind="learned",
192
+ title="Black-box network",
193
+ base=None,
194
+ equation="an MLP over 3 samples of q-axis current command and rotor speed → shaft torque",
195
+ references=(references.HWANGBO_2019, references.HWANGBO_2019_ARXIV),
196
+ ),
197
+ )
198
+
199
+ # --- other names for the same quantities -----------------------------------------------------------------------------
200
+
201
+ ALIASES = (
202
+ # old user-part keys, catalogue atlas columns, Cad2Robot exporter fields: the datasheet's other spellings
203
+ Alias(name="torque_constant", canonical="kt",
204
+ note="Old user-part key: a geared part's source may state it at the output (kt × gear_ratio)."),
205
+ Alias(name="torque_coefficient", canonical="kt",
206
+ note="Catalogue part key: check RMS against peak amperes (kt is per peak ampere)."),
207
+ Alias(name="phase_resistance", canonical="resistance_line_to_line",
208
+ note=("Old user-part key: a 'phase to phase' value is line to line; a per-phase value is half of it on a "
209
+ "wye winding.")),
210
+ Alias(name="phase_resistance_ohm", canonical="resistance_line_to_line", unit="Ω",
211
+ note="Per phase (sim2real's servo, Cad2Robot's motor): line to line is twice it on a wye winding."),
212
+ Alias(name="phase_inductance", canonical="inductance_line_to_line",
213
+ note="Old user-part key: per phase is half of line to line on a wye winding."),
214
+ Alias(name="phase_inductance_h", canonical="inductance_line_to_line", unit="H",
215
+ note="Per phase (Cad2Robot's motor): half of line to line on a wye winding."),
216
+ Alias(name="noload_speed", canonical="max_output_speed",
217
+ note="Old user-part key: its unit is the part file's; check it before converting."),
218
+ Alias(name="max_speed", canonical="max_output_speed",
219
+ note="Old user-part key: may be a mechanical limit rather than the no-load speed."),
220
+ Alias(name="rated_torque_nm", canonical="rated_torque"),
221
+ Alias(name="peak_torque_nm", canonical="peak_torque"),
222
+ Alias(name="noload_speed_rpm", canonical="max_output_speed", unit="rpm"),
223
+ Alias(name="rated_speed_rpm", canonical="rated_speed", unit="rpm"),
224
+ Alias(name="rated_power_w", canonical="rated_power"),
225
+ Alias(name="voltage_v", canonical="nominal_voltage"),
226
+ Alias(name="mass_kg", canonical="mass"),
227
+ Alias(name="od_mm", canonical="outer_diameter", unit="mm"),
228
+ Alias(name="length_mm", canonical="axial_length", unit="mm"),
229
+ Alias(name="rotor_inertia_kg_m2", canonical="rotor_inertia"),
230
+ Alias(name="peak_current_a", canonical="max_phase_current"),
231
+ Alias(name="rated_current_a", canonical="rated_phase_current"),
232
+ Alias(name="encoder_counts", canonical="encoder_lines",
233
+ note="Counts per turn: 4 × lines on a quadrature encoder."),
234
+ # sim2real's motor card
235
+ Alias(name="motorconst", canonical="kt",
236
+ note=("sim2real's motor card: the scalar kt, rotor side (robotparts' dcmotor packs an array under this "
237
+ "name).")),
238
+ Alias(name="resistance", canonical="resistance_line_to_line", unit="Ω",
239
+ note=("sim2real's motor card, after robotparts' dcmotor: per phase or line to line is not stated; check it "
240
+ "before converting.")),
241
+ Alias(name="inductance", canonical="inductance_line_to_line", unit="H",
242
+ note="sim2real's motor card: the convention as for resistance."),
243
+ Alias(name="cogging", canonical="torque_ripple",
244
+ note="sim2real's motor card: one cogging amplitude; its harmonic is not stated."),
245
+ Alias(name="bearing_friction_nm", canonical="coulomb_friction",
246
+ note="A bare motor's Coulomb friction is its bearings'."),
247
+ Alias(name="bearing_friction_growth_nm_per_h", canonical="friction_growth"),
248
+ )
249
+
250
+ # --- names that pack several quantities -------------------------------------------------------------------------------
251
+
252
+ PACKED = (
253
+ Packed(name="thermal", holds=("thermal_resistance", "thermal_time_constant"), ordered=True,
254
+ note="sim2real's motor card: (K/W, s)."),
255
+ )
256
+
257
+ # WHY no deployment-only names (PEP 0004 §5.3): a bare motor has no drive, gains or mount; those belong to
258
+ # foc_controller and to the assembly that holds the motor.
259
+
260
+ LADDER = Ladder(
261
+ type="bldc_motor",
262
+ title="A brushless motor alone, at its shaft.",
263
+ vocabulary=VOCABULARY,
264
+ rungs=RUNGS,
265
+ aliases=ALIASES,
266
+ packed=PACKED,
267
+ datasheet=BldcMotor,
268
+ )
@@ -0,0 +1,127 @@
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
+ # foc_controller
4
+
5
+ A field-oriented-control motor drive board.
6
+
7
+ **6 rungs** · 7 parameters · 4 aliases · 1 packed names · 3 deployment-only names · folder `actuators/servo/foc_controller/`.
8
+
9
+ In code: `ladders()["foc_controller"]` 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: [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
+ from robot_models.actuators.servo.foc_controller.ladder import LADDER
17
+ LADDER.parameters("M2.ceiling_heat") # what the voltage-ceiling and heating rung needs, M1's names included
18
+
19
+ Rungs: M0 the commanded current as is, M1 the transport delay and first-order current loop, M2 the voltage ceiling and
20
+ the board's heating (and M2.wear, the board's cooling ageing with hours), M6 the grey-box residual, M7 the learned net.
21
+ A deployment's own settings (torque cap, host loop rate, modulation-limit setting) are not on a rung: see `deployment`.
22
+
23
+ Spec: PEP 0004 §5.5 and §6.4. Sources: sim2real's `driver` card (its rungs, parameters and equations).
24
+
25
+ ## The ladder
26
+
27
+ ```mermaid
28
+ flowchart BT
29
+ M0_ideal["M0.ideal<br/>An ideal drive: the<br/>commanded current"]
30
+ M1_delay_loop["M1.delay_loop<br/>Transport delay, a<br/>first-order current loop<br/>and its torque scale"]
31
+ M2_ceiling_heat["M2.ceiling_heat<br/>Voltage ceiling and<br/>board heating"]
32
+ M2_wear["M2.wear<br/>Board cooling that ages<br/>with hours"]
33
+ M6_residual{{"M6.residual<br/>Grey-box residual on<br/>M2.wear"}}
34
+ M7_learned(["M7.learned<br/>Black-box network"])
35
+ M0_ideal --> M1_delay_loop
36
+ M1_delay_loop --> M2_ceiling_heat
37
+ M2_ceiling_heat --> M2_wear
38
+ M2_wear --> M6_residual
39
+ M6_residual ~~~ M7_learned
40
+ classDef physics fill:#e8f1fb,stroke:#2f6aa3,color:#10243a
41
+ classDef wear fill:#e8f1fb,stroke:#2f6aa3,color:#10243a,stroke-dasharray:6 3
42
+ classDef residual fill:#fdf0dc,stroke:#b06a00,color:#3a2400
43
+ classDef learned fill:#f1e6fb,stroke:#7a3db3,color:#2a1040
44
+ class M0_ideal,M1_delay_loop,M2_ceiling_heat physics
45
+ class M2_wear wear
46
+ class M6_residual residual
47
+ class M7_learned learned
48
+ ```
49
+
50
+ 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.
51
+
52
+ ## Rungs
53
+
54
+ 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.
55
+
56
+ | rung | title | base | needs (adds) | reads when stated (optional) | code | equation | references |
57
+ | --- | --- | --- | --- | --- | --- | --- | --- |
58
+ | <a id="rung-m0-ideal"></a>`M0.ideal` | An ideal drive: the commanded current | — | — | — | — | `i_q = i_cmd (a deployment's torque cap clamps it)` | [KRISHNAN_2010](#ref-krishnan_2010) |
59
+ | <a id="rung-m1-delay_loop"></a>`M1.delay_loop` | Transport delay, a first-order current loop and its torque scale | [`M0.ideal`](#rung-m0-ideal) | `command_latency`, `current_loop_bandwidth`, `torque_scale` | — | — | `i_q = torque_scale·LPF(current_loop_bandwidth)[i_cmd(t − command_latency)]` | [KRISHNAN_2010](#ref-krishnan_2010) |
60
+ | <a id="rung-m2-ceiling_heat"></a>`M2.ceiling_heat` | Voltage ceiling and board heating | [`M1.delay_loop`](#rung-m1-delay_loop) | `voltage_available`, `board_thermal_resistance`, `board_thermal_time_constant` | — | — | `M1.delay_loop clamped to the voltage ceiling (voltage_available − ω·kt/1.5)/R of the motor it drives; board_thermal_time_constant·dΔT/dt = board_thermal_resistance·P_loss − ΔT, ΔT the board's rise over ambient` | [KRAUSE_2013](#ref-krause_2013), [KRISHNAN_2010](#ref-krishnan_2010) |
61
+ | <a id="rung-m2-wear"></a>`M2.wear` | Board cooling that ages with hours<br>wears `board_thermal_resistance`: see [Wear](#wear) | [`M2.ceiling_heat`](#rung-m2-ceiling_heat) | `board_thermal_growth` | — | — | `board_thermal_resistance(h) = board_thermal_resistance + board_thermal_growth·h` | [LU_MEEKER_1993](#ref-lu_meeker_1993), [MEEKER_1998](#ref-meeker_1998) |
62
+ | <a id="rung-m6-residual"></a>`M6.residual` | Grey-box residual on M2.wear | [`M2.wear`](#rung-m2-wear) | — | — | — | `M2.wear + an MLP residual q-current from 3 samples of current command, rotor speed and bus voltage` | [NGUYEN_TUONG_2010](#ref-nguyen_tuong_2010) |
63
+ | <a id="rung-m7-learned"></a>`M7.learned` | Black-box network | — | — | — | — | `an MLP over 3 samples of current command, rotor speed, bus voltage and board temperature → q-current` | [HWANGBO_2019](#ref-hwangbo_2019) |
64
+
65
+ ## Wear
66
+
67
+ Which parameter grows with use, with what, by which law, at which rate.
68
+
69
+ | rung | parameter that wears | grows with | law | rate |
70
+ | --- | --- | --- | --- | --- |
71
+ | [`M2.wear`](#rung-m2-wear) | [`board_thermal_resistance`](#param-board_thermal_resistance) | deployment hours (h) | linear: `p(u) = p0 + k·u` | [`board_thermal_growth`](#param-board_thermal_growth) |
72
+
73
+ ## Vocabulary
74
+
75
+ Every parameter the ladder holds, by the rung that first reads it. — as a unit: dimensionless (a ratio or a count).
76
+
77
+ | parameter | SI unit | shape | definition | first read on |
78
+ | --- | --- | --- | --- | --- |
79
+ | <a id="param-command_latency"></a>`command_latency` | s | scalar | Time from a command reaching the drive to its first response: the transport delay before the current loop. | [`M1.delay_loop`](#rung-m1-delay_loop) |
80
+ | <a id="param-current_loop_bandwidth"></a>`current_loop_bandwidth` | Hz | scalar | The drive's closed-loop current (torque) bandwidth: the corner of its first-order current loop. | [`M1.delay_loop`](#rung-m1-delay_loop) |
81
+ | <a id="param-torque_scale"></a>`torque_scale` | — | scalar | Torque the drive delivers over the torque it was commanded: its torque-constant calibration error. | [`M1.delay_loop`](#rung-m1-delay_loop) |
82
+ | <a id="param-voltage_available"></a>`voltage_available` | V | scalar | The largest phase voltage the drive can apply: its bus voltage times its modulation limit. | [`M2.ceiling_heat`](#rung-m2-ceiling_heat) |
83
+ | <a id="param-board_thermal_resistance"></a>`board_thermal_resistance` | K/W | scalar | The board's temperature rise per watt it dissipates. | [`M2.ceiling_heat`](#rung-m2-ceiling_heat) |
84
+ | <a id="param-board_thermal_time_constant"></a>`board_thermal_time_constant` | s | scalar | Time constant of the board temperature's first-order rise. | [`M2.ceiling_heat`](#rung-m2-ceiling_heat) |
85
+ | <a id="param-board_thermal_growth"></a>`board_thermal_growth` | K/W/h | scalar | How fast board_thermal_resistance grows per deployment hour (its cooling ageing). | [`M2.wear`](#rung-m2-wear) |
86
+
87
+ ## Aliases
88
+
89
+ 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.
90
+
91
+ | alias | canonical | unit | note |
92
+ | --- | --- | --- | --- |
93
+ | `board_thermal_growth_per_h` | [`board_thermal_growth`](#param-board_thermal_growth) | K/W/h *(canonical)* | |
94
+ | `command_delay_s` | [`command_latency`](#param-command_latency) | s *(canonical)* | The twin's transport delay; the registry's command_latency is measured host to first response over a named bus. |
95
+ | `current_loop_hz` | [`current_loop_bandwidth`](#param-current_loop_bandwidth) | Hz *(canonical)* | The twin's first-order loop corner, which is its −3 dB bandwidth. |
96
+ | `voltage_available_v` | [`voltage_available`](#param-voltage_available) | V *(canonical)* | |
97
+
98
+ ## Packed names
99
+
100
+ Names for one array that carries several of these parameters; never read as one parameter.
101
+
102
+ | packed name | carries | order | note |
103
+ | --- | --- | --- | --- |
104
+ | `board_thermal` | [`board_thermal_resistance`](#param-board_thermal_resistance), [`board_thermal_time_constant`](#param-board_thermal_time_constant) | its full entry order | sim2real's driver card: (K/W, s). |
105
+
106
+ ## Deployment-only names
107
+
108
+ Names some model reads that are not the type's own: a deployment sets them, or the mount gives them.
109
+
110
+ - *config*: a setting a deployment writes (a gain, a cap, a rate): read from its config, never fitted to the type.
111
+
112
+ | name | role | where it belongs |
113
+ | --- | --- | --- |
114
+ | `max_voltage_factor` | config | The firmware's modulation-limit setting: the deployment's config. |
115
+ | `telemetry_rate_hz` | config | The host loop's rate: the deployment's config. |
116
+ | `torque_cap_nm` | config | The runner's torque cap: the deployment's config. |
117
+
118
+ ## References
119
+
120
+ The works the rungs cite, by their names in [`robot_models.references`](../../../references.py).
121
+
122
+ - <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).
123
+ - <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 [`M2.ceiling_heat`](#rung-m2-ceiling_heat).
124
+ - <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 [`M0.ideal`](#rung-m0-ideal), [`M1.delay_loop`](#rung-m1-delay_loop), [`M2.ceiling_heat`](#rung-m2-ceiling_heat).
125
+ - <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 [`M2.wear`](#rung-m2-wear).
126
+ - <a id="ref-meeker_1998"></a>**MEEKER_1998**: Meeker, Escobar, Lu (1998). Accelerated degradation tests: modeling and analysis. Technometrics. [doi:10.1080/00401706.1998.10485191](https://doi.org/10.1080/00401706.1998.10485191). What the rung uses: degradation paths fitted and extrapolated to a threshold. Cited by [`M2.wear`](#rung-m2-wear).
127
+ - <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).
@@ -0,0 +1,3 @@
1
+ """Field-oriented-control (FOC) motor drive boards: the electronics between a torque command and the motor's phase
2
+ current. The type's model ladder (its delay, current loop, voltage ceiling and board heating) lives in `ladder.py`.
3
+ """