robot-model-ladders 0.2.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- robot_model_ladders-0.2.0/.gitattributes +3 -0
- robot_model_ladders-0.2.0/.github/workflows/publish.yml +34 -0
- robot_model_ladders-0.2.0/.github/workflows/test.yml +41 -0
- robot_model_ladders-0.2.0/.gitignore +5 -0
- robot_model_ladders-0.2.0/LICENSE +21 -0
- robot_model_ladders-0.2.0/PKG-INFO +143 -0
- robot_model_ladders-0.2.0/README.md +108 -0
- robot_model_ladders-0.2.0/docs/TYPES.md +65 -0
- robot_model_ladders-0.2.0/docs/peps/0001-homing-stop-core.md +41 -0
- robot_model_ladders-0.2.0/docs/peps/0002-homing-bench.md +30 -0
- robot_model_ladders-0.2.0/docs/peps/0003-typed-datasheets-from-sources.md +252 -0
- robot_model_ladders-0.2.0/docs/peps/0004-model-ladders-by-type.md +1092 -0
- robot_model_ladders-0.2.0/docs/proposals/api-2026-11-17/README.md +91 -0
- robot_model_ladders-0.2.0/docs/proposals/api-2026-11-17/ROUND2.md +51 -0
- robot_model_ladders-0.2.0/docs/proposals/api-2026-11-17/_truth.py +17 -0
- robot_model_ladders-0.2.0/docs/proposals/api-2026-11-17/build_gallery.py +247 -0
- robot_model_ladders-0.2.0/docs/proposals/api-2026-11-17/capture_gallery.py +105 -0
- robot_model_ladders-0.2.0/docs/proposals/api-2026-11-17/check_scenario.py +136 -0
- robot_model_ladders-0.2.0/docs/proposals/api-2026-11-17/decision.json +4 -0
- robot_model_ladders-0.2.0/docs/proposals/api-2026-11-17/fixture.py +65 -0
- robot_model_ladders-0.2.0/docs/proposals/api-2026-11-17/gallery-spec.json +847 -0
- robot_model_ladders-0.2.0/docs/proposals/api-2026-11-17/round.json +1374 -0
- robot_model_ladders-0.2.0/docs/proposals/api-2026-11-17/v1_subclass/README.md +206 -0
- robot_model_ladders-0.2.0/docs/proposals/api-2026-11-17/v1_subclass/scenario.out.txt +81 -0
- robot_model_ladders-0.2.0/docs/proposals/api-2026-11-17/v1_subclass/scenario.py +115 -0
- robot_model_ladders-0.2.0/docs/proposals/api-2026-11-17/v1_subclass/subclass_ladder/__init__.py +5 -0
- robot_model_ladders-0.2.0/docs/proposals/api-2026-11-17/v1_subclass/subclass_ladder/model.py +402 -0
- robot_model_ladders-0.2.0/docs/proposals/api-2026-11-17/v1_subclass/subclass_ladder/servo.py +111 -0
- robot_model_ladders-0.2.0/docs/proposals/api-2026-11-17/v2_records/README.md +159 -0
- robot_model_ladders-0.2.0/docs/proposals/api-2026-11-17/v2_records/family_records.py +371 -0
- robot_model_ladders-0.2.0/docs/proposals/api-2026-11-17/v2_records/scenario.out.txt +102 -0
- robot_model_ladders-0.2.0/docs/proposals/api-2026-11-17/v2_records/scenario.py +108 -0
- robot_model_ladders-0.2.0/docs/proposals/api-2026-11-17/v3_terms/README.md +159 -0
- robot_model_ladders-0.2.0/docs/proposals/api-2026-11-17/v3_terms/composed_terms.py +419 -0
- robot_model_ladders-0.2.0/docs/proposals/api-2026-11-17/v3_terms/scenario.out.txt +111 -0
- robot_model_ladders-0.2.0/docs/proposals/api-2026-11-17/v3_terms/scenario.py +111 -0
- robot_model_ladders-0.2.0/docs/proposals/api-2026-11-17/v3_terms/servo_slots.py +31 -0
- robot_model_ladders-0.2.0/docs/proposals/api-2026-11-17/v4_estimators/README.md +178 -0
- robot_model_ladders-0.2.0/docs/proposals/api-2026-11-17/v4_estimators/estimators.py +374 -0
- robot_model_ladders-0.2.0/docs/proposals/api-2026-11-17/v4_estimators/scenario.out.txt +88 -0
- robot_model_ladders-0.2.0/docs/proposals/api-2026-11-17/v4_estimators/scenario.py +98 -0
- robot_model_ladders-0.2.0/docs/proposals/api-2026-11-17/v5_kit/README.md +143 -0
- robot_model_ladders-0.2.0/docs/proposals/api-2026-11-17/v5_kit/scenario.out.txt +106 -0
- robot_model_ladders-0.2.0/docs/proposals/api-2026-11-17/v5_kit/scenario.py +120 -0
- robot_model_ladders-0.2.0/docs/proposals/api-2026-11-17/v5_kit/type_kit.py +423 -0
- robot_model_ladders-0.2.0/docs/report/api_session.py +33 -0
- robot_model_ladders-0.2.0/docs/report/build_report_v1.py +1144 -0
- robot_model_ladders-0.2.0/docs/report/capture_v1.py +392 -0
- robot_model_ladders-0.2.0/pyproject.toml +74 -0
- robot_model_ladders-0.2.0/reports/robot-models-api-proposals-2026-11-17.html +4218 -0
- robot_model_ladders-0.2.0/src/robot_models/__init__.py +18 -0
- robot_model_ladders-0.2.0/src/robot_models/actuators/__init__.py +1 -0
- robot_model_ladders-0.2.0/src/robot_models/actuators/rungs/README.md +24 -0
- robot_model_ladders-0.2.0/src/robot_models/actuators/rungs/coulomb_viscous/README.md +61 -0
- robot_model_ladders-0.2.0/src/robot_models/actuators/rungs/coulomb_viscous/model.js +14 -0
- robot_model_ladders-0.2.0/src/robot_models/actuators/rungs/coulomb_viscous/model.json +102 -0
- robot_model_ladders-0.2.0/src/robot_models/actuators/rungs/coulomb_viscous/model.py +24 -0
- robot_model_ladders-0.2.0/src/robot_models/actuators/rungs/datasheet/README.md +65 -0
- robot_model_ladders-0.2.0/src/robot_models/actuators/rungs/datasheet/model.js +14 -0
- robot_model_ladders-0.2.0/src/robot_models/actuators/rungs/datasheet/model.json +138 -0
- robot_model_ladders-0.2.0/src/robot_models/actuators/rungs/datasheet/model.py +24 -0
- robot_model_ladders-0.2.0/src/robot_models/actuators/rungs/dcmotor/README.md +63 -0
- robot_model_ladders-0.2.0/src/robot_models/actuators/rungs/dcmotor/model.json +163 -0
- robot_model_ladders-0.2.0/src/robot_models/actuators/rungs/ideal/README.md +60 -0
- robot_model_ladders-0.2.0/src/robot_models/actuators/rungs/ideal/model.js +6 -0
- robot_model_ladders-0.2.0/src/robot_models/actuators/rungs/ideal/model.json +90 -0
- robot_model_ladders-0.2.0/src/robot_models/actuators/rungs/ideal/model.py +13 -0
- robot_model_ladders-0.2.0/src/robot_models/actuators/rungs/load/README.md +65 -0
- robot_model_ladders-0.2.0/src/robot_models/actuators/rungs/load/model.js +15 -0
- robot_model_ladders-0.2.0/src/robot_models/actuators/rungs/load/model.json +117 -0
- robot_model_ladders-0.2.0/src/robot_models/actuators/rungs/load/model.py +25 -0
- robot_model_ladders-0.2.0/src/robot_models/actuators/rungs/lugre/README.md +72 -0
- robot_model_ladders-0.2.0/src/robot_models/actuators/rungs/lugre/model.js +24 -0
- robot_model_ladders-0.2.0/src/robot_models/actuators/rungs/lugre/model.json +164 -0
- robot_model_ladders-0.2.0/src/robot_models/actuators/rungs/lugre/model.py +30 -0
- robot_model_ladders-0.2.0/src/robot_models/actuators/rungs/ripple/README.md +64 -0
- robot_model_ladders-0.2.0/src/robot_models/actuators/rungs/ripple/model.js +17 -0
- robot_model_ladders-0.2.0/src/robot_models/actuators/rungs/ripple/model.json +119 -0
- robot_model_ladders-0.2.0/src/robot_models/actuators/rungs/ripple/model.py +27 -0
- robot_model_ladders-0.2.0/src/robot_models/actuators/rungs/stribeck/README.md +65 -0
- robot_model_ladders-0.2.0/src/robot_models/actuators/rungs/stribeck/model.js +17 -0
- robot_model_ladders-0.2.0/src/robot_models/actuators/rungs/stribeck/model.json +126 -0
- robot_model_ladders-0.2.0/src/robot_models/actuators/rungs/stribeck/model.py +28 -0
- robot_model_ladders-0.2.0/src/robot_models/actuators/servo/README.md +278 -0
- robot_model_ladders-0.2.0/src/robot_models/actuators/servo/__init__.py +7 -0
- robot_model_ladders-0.2.0/src/robot_models/actuators/servo/bldc/README.md +186 -0
- robot_model_ladders-0.2.0/src/robot_models/actuators/servo/bldc/__init__.py +5 -0
- robot_model_ladders-0.2.0/src/robot_models/actuators/servo/bldc/bldc_motor.py +93 -0
- robot_model_ladders-0.2.0/src/robot_models/actuators/servo/bldc/ladder.py +268 -0
- robot_model_ladders-0.2.0/src/robot_models/actuators/servo/foc_controller/README.md +127 -0
- robot_model_ladders-0.2.0/src/robot_models/actuators/servo/foc_controller/__init__.py +3 -0
- robot_model_ladders-0.2.0/src/robot_models/actuators/servo/foc_controller/ladder.py +207 -0
- robot_model_ladders-0.2.0/src/robot_models/actuators/servo/gearbox/README.md +148 -0
- robot_model_ladders-0.2.0/src/robot_models/actuators/servo/gearbox/__init__.py +5 -0
- robot_model_ladders-0.2.0/src/robot_models/actuators/servo/gearbox/gearbox.py +36 -0
- robot_model_ladders-0.2.0/src/robot_models/actuators/servo/gearbox/ladder.py +214 -0
- robot_model_ladders-0.2.0/src/robot_models/actuators/servo/integrated_servo.py +33 -0
- robot_model_ladders-0.2.0/src/robot_models/actuators/servo/ladder.py +593 -0
- robot_model_ladders-0.2.0/src/robot_models/arms/__init__.py +1 -0
- robot_model_ladders-0.2.0/src/robot_models/arms/rigid_body_chain/README.md +151 -0
- robot_model_ladders-0.2.0/src/robot_models/arms/rigid_body_chain/__init__.py +3 -0
- robot_model_ladders-0.2.0/src/robot_models/arms/rigid_body_chain/ladder.py +228 -0
- robot_model_ladders-0.2.0/src/robot_models/conveyors/__init__.py +1 -0
- robot_model_ladders-0.2.0/src/robot_models/conveyors/conveyor/README.md +140 -0
- robot_model_ladders-0.2.0/src/robot_models/conveyors/conveyor/__init__.py +1 -0
- robot_model_ladders-0.2.0/src/robot_models/conveyors/conveyor/ladder.py +203 -0
- robot_model_ladders-0.2.0/src/robot_models/datasheet/__init__.py +56 -0
- robot_model_ladders-0.2.0/src/robot_models/datasheet/datasheet.py +355 -0
- robot_model_ladders-0.2.0/src/robot_models/datasheet/literal.py +144 -0
- robot_model_ladders-0.2.0/src/robot_models/datasheet/source.py +328 -0
- robot_model_ladders-0.2.0/src/robot_models/datasheet/stated.py +135 -0
- robot_model_ladders-0.2.0/src/robot_models/datasheet/units.py +57 -0
- robot_model_ladders-0.2.0/src/robot_models/end_effectors/__init__.py +1 -0
- robot_model_ladders-0.2.0/src/robot_models/end_effectors/gripper/README.md +112 -0
- robot_model_ladders-0.2.0/src/robot_models/end_effectors/gripper/__init__.py +3 -0
- robot_model_ladders-0.2.0/src/robot_models/end_effectors/gripper/ladder.py +150 -0
- robot_model_ladders-0.2.0/src/robot_models/homing/__init__.py +38 -0
- robot_model_ladders-0.2.0/src/robot_models/homing/cad_bundle.py +206 -0
- robot_model_ladders-0.2.0/src/robot_models/homing/contact.py +201 -0
- robot_model_ladders-0.2.0/src/robot_models/homing/fit.py +126 -0
- robot_model_ladders-0.2.0/src/robot_models/homing/metrics.py +237 -0
- robot_model_ladders-0.2.0/src/robot_models/homing/protocols.py +72 -0
- robot_model_ladders-0.2.0/src/robot_models/homing/types.py +256 -0
- robot_model_ladders-0.2.0/src/robot_models/ladder.py +645 -0
- robot_model_ladders-0.2.0/src/robot_models/markers/__init__.py +1 -0
- robot_model_ladders-0.2.0/src/robot_models/markers/aruco_marker/README.md +92 -0
- robot_model_ladders-0.2.0/src/robot_models/markers/aruco_marker/__init__.py +2 -0
- robot_model_ladders-0.2.0/src/robot_models/markers/aruco_marker/ladder.py +142 -0
- robot_model_ladders-0.2.0/src/robot_models/references.py +429 -0
- robot_model_ladders-0.2.0/src/robot_models/sensors/__init__.py +1 -0
- robot_model_ladders-0.2.0/src/robot_models/sensors/camera/README.md +118 -0
- robot_model_ladders-0.2.0/src/robot_models/sensors/camera/__init__.py +3 -0
- robot_model_ladders-0.2.0/src/robot_models/sensors/camera/ladder.py +108 -0
- robot_model_ladders-0.2.0/src/robot_models/sensors/encoder/README.md +103 -0
- robot_model_ladders-0.2.0/src/robot_models/sensors/encoder/__init__.py +5 -0
- robot_model_ladders-0.2.0/src/robot_models/sensors/encoder/ladder.py +133 -0
- robot_model_ladders-0.2.0/src/robot_models/sensors/hyperspectral_camera/README.md +107 -0
- robot_model_ladders-0.2.0/src/robot_models/sensors/hyperspectral_camera/__init__.py +1 -0
- robot_model_ladders-0.2.0/src/robot_models/sensors/hyperspectral_camera/ladder.py +151 -0
- robot_model_ladders-0.2.0/src/robot_models/sensors/rgbd/README.md +113 -0
- robot_model_ladders-0.2.0/src/robot_models/sensors/rgbd/__init__.py +5 -0
- robot_model_ladders-0.2.0/src/robot_models/sensors/rgbd/ladder.py +113 -0
- robot_model_ladders-0.2.0/tests/test_datasheet.py +324 -0
- robot_model_ladders-0.2.0/tests/test_fit_ruler.py +190 -0
- robot_model_ladders-0.2.0/tests/test_import_direction.py +77 -0
- robot_model_ladders-0.2.0/tests/test_ladder.py +426 -0
- robot_model_ladders-0.2.0/tests/test_ladders_acceptance.py +1240 -0
- robot_model_ladders-0.2.0/tests/test_metrics_ruler.py +135 -0
- robot_model_ladders-0.2.0/tests/test_stop_ruler.py +177 -0
- robot_model_ladders-0.2.0/tests/test_type_docs.py +122 -0
- robot_model_ladders-0.2.0/tests/test_types.py +79 -0
- robot_model_ladders-0.2.0/tools/make_type_docs.py +749 -0
- robot_model_ladders-0.2.0/uv.lock +451 -0
|
@@ -0,0 +1,34 @@
|
|
|
1
|
+
# Publishes to PyPI when a version tag (v*) is pushed, through PyPI trusted publishing: no API token is stored
|
|
2
|
+
# anywhere (robot_msgs' pattern). One-time setup on pypi.org: a "pending publisher" for project robot-model-ladders, owner
|
|
3
|
+
# zacharyyamaoka, repository robot_models, workflow publish.yml, environment pypi.
|
|
4
|
+
name: publish
|
|
5
|
+
on:
|
|
6
|
+
push:
|
|
7
|
+
tags: ["v*"]
|
|
8
|
+
workflow_dispatch:
|
|
9
|
+
jobs:
|
|
10
|
+
test:
|
|
11
|
+
runs-on: ubuntu-latest
|
|
12
|
+
timeout-minutes: 20
|
|
13
|
+
env:
|
|
14
|
+
PYTHONDONTWRITEBYTECODE: "1"
|
|
15
|
+
MPLBACKEND: Agg
|
|
16
|
+
steps:
|
|
17
|
+
- uses: actions/checkout@v4
|
|
18
|
+
- uses: astral-sh/setup-uv@v6
|
|
19
|
+
# WHY the two ruler files are left out: they read CAD bundles from a local, unpublished cache (see test.yml).
|
|
20
|
+
- run: >-
|
|
21
|
+
uv run --isolated --no-sources --extra test python -m pytest -q -p no:cacheprovider
|
|
22
|
+
--ignore=tests/test_fit_ruler.py --ignore=tests/test_stop_ruler.py
|
|
23
|
+
publish:
|
|
24
|
+
needs: test
|
|
25
|
+
runs-on: ubuntu-latest
|
|
26
|
+
timeout-minutes: 20
|
|
27
|
+
environment: pypi
|
|
28
|
+
permissions:
|
|
29
|
+
id-token: write
|
|
30
|
+
steps:
|
|
31
|
+
- uses: actions/checkout@v4
|
|
32
|
+
- uses: astral-sh/setup-uv@v6
|
|
33
|
+
- run: uv build
|
|
34
|
+
- run: uv publish --trusted-publishing always
|
|
@@ -0,0 +1,41 @@
|
|
|
1
|
+
name: test
|
|
2
|
+
on:
|
|
3
|
+
push:
|
|
4
|
+
branches: [main]
|
|
5
|
+
pull_request:
|
|
6
|
+
branches: [main]
|
|
7
|
+
jobs:
|
|
8
|
+
test:
|
|
9
|
+
runs-on: ubuntu-latest
|
|
10
|
+
timeout-minutes: 20
|
|
11
|
+
env:
|
|
12
|
+
# WHY no bytecode: it keeps __pycache__/ out of the rung folders robotparts vendors byte for byte (PEP 0004 §8.1).
|
|
13
|
+
PYTHONDONTWRITEBYTECODE: "1"
|
|
14
|
+
MPLBACKEND: Agg
|
|
15
|
+
strategy:
|
|
16
|
+
fail-fast: false
|
|
17
|
+
matrix:
|
|
18
|
+
# WHY 3.14 too: coal 3.0.2 (the test extra's pin) ships manylinux x86_64 wheels for cp311-cp314.
|
|
19
|
+
python: ["3.11", "3.12", "3.13", "3.14"]
|
|
20
|
+
steps:
|
|
21
|
+
- uses: actions/checkout@v4
|
|
22
|
+
- uses: astral-sh/setup-uv@v6
|
|
23
|
+
# WHY --no-sources: [tool.uv.sources] names a local robot_msgs checkout on purpose (a consumer's lock, see
|
|
24
|
+
# pyproject.toml), which a runner does not have; robot-msgs then comes from PyPI, as a user gets it.
|
|
25
|
+
# WHY the two homing ruler files are left out: every test in them reads a CAD bundle from the local cad2robot
|
|
26
|
+
# build cache (~/.cache/cad2robot-build/bundles, ROBOT_MODELS_CAD_BUNDLES), which is not published. Everything
|
|
27
|
+
# else runs: the ladder contract and ruler, datasheets, types, import direction and the homing metrics ruler.
|
|
28
|
+
- name: pytest
|
|
29
|
+
run: >-
|
|
30
|
+
uv run --isolated --no-sources --python ${{ matrix.python }}
|
|
31
|
+
--extra test
|
|
32
|
+
python -m pytest -q -p no:cacheprovider
|
|
33
|
+
--ignore=tests/test_fit_ruler.py --ignore=tests/test_stop_ruler.py
|
|
34
|
+
# WHY: robot_models.__version__ is a literal (no importlib.metadata cost on import); this keeps it equal to
|
|
35
|
+
# pyproject.toml's version, read back from the freshly built metadata.
|
|
36
|
+
- name: __version__ matches pyproject
|
|
37
|
+
run: >-
|
|
38
|
+
uv run --isolated --no-sources --python ${{ matrix.python }}
|
|
39
|
+
python -c "import importlib.metadata, robot_models;
|
|
40
|
+
installed = importlib.metadata.version('robot-model-ladders');
|
|
41
|
+
assert robot_models.__version__ == installed, (robot_models.__version__, installed)"
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Zach Yamaoka
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
|
@@ -0,0 +1,143 @@
|
|
|
1
|
+
Metadata-Version: 2.5
|
|
2
|
+
Name: robot-model-ladders
|
|
3
|
+
Version: 0.2.0
|
|
4
|
+
Summary: Generic physical models of robot part types (no maker, no SKU): each type a ladder of models from ideal to learned, every rung with its parameters, equation and references.
|
|
5
|
+
Project-URL: Homepage, https://github.com/zacharyyamaoka/robot_models
|
|
6
|
+
Project-URL: Repository, https://github.com/zacharyyamaoka/robot_models
|
|
7
|
+
Project-URL: Issues, https://github.com/zacharyyamaoka/robot_models/issues
|
|
8
|
+
Author: Zach Yamaoka
|
|
9
|
+
License-Expression: MIT
|
|
10
|
+
License-File: LICENSE
|
|
11
|
+
Keywords: actuators,digital-twin,friction,physical-models,robotics,sensors,sim2real,system-identification
|
|
12
|
+
Classifier: Development Status :: 3 - Alpha
|
|
13
|
+
Classifier: Intended Audience :: Developers
|
|
14
|
+
Classifier: Intended Audience :: Science/Research
|
|
15
|
+
Classifier: Operating System :: OS Independent
|
|
16
|
+
Classifier: Programming Language :: Python :: 3
|
|
17
|
+
Classifier: Programming Language :: Python :: 3 :: Only
|
|
18
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
19
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
20
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
21
|
+
Classifier: Programming Language :: Python :: 3.14
|
|
22
|
+
Classifier: Topic :: Scientific/Engineering
|
|
23
|
+
Classifier: Topic :: Scientific/Engineering :: Physics
|
|
24
|
+
Requires-Python: >=3.11
|
|
25
|
+
Requires-Dist: numpy>=1.26
|
|
26
|
+
Requires-Dist: robot-msgs>=0.3.0
|
|
27
|
+
Provides-Extra: contact
|
|
28
|
+
Requires-Dist: coal<3.1,>=3.0.2; extra == 'contact'
|
|
29
|
+
Requires-Dist: trimesh>=4.0; extra == 'contact'
|
|
30
|
+
Provides-Extra: test
|
|
31
|
+
Requires-Dist: coal==3.0.2; extra == 'test'
|
|
32
|
+
Requires-Dist: pytest>=8; extra == 'test'
|
|
33
|
+
Requires-Dist: trimesh>=4.0; extra == 'test'
|
|
34
|
+
Description-Content-Type: text/markdown
|
|
35
|
+
|
|
36
|
+
# robot_models
|
|
37
|
+
|
|
38
|
+
Generic physical models of robot part **types** (no maker, no SKU): each type is a ladder of models from ideal to
|
|
39
|
+
learned, and every rung states its parameters, its equation and its references.
|
|
40
|
+
|
|
41
|
+
```
|
|
42
|
+
robot_msgs ← robot_models ← robot_parts ← robot_descriptions, with sim2real on top
|
|
43
|
+
```
|
|
44
|
+
|
|
45
|
+
- [robot_msgs](https://github.com/zacharyyamaoka/robot_msgs): the message types this package builds on.
|
|
46
|
+
- [sim2real](https://github.com/zacharyyamaoka/sim2real): the outer API (twins, calibration) over the stack.
|
|
47
|
+
- robot_parts (robotparts, private): the part catalogue, whose parts point at these types and rungs.
|
|
48
|
+
- Type data only: parameter names, SI units, definitions, equations. Never a value measured on one unit.
|
|
49
|
+
|
|
50
|
+
## Usage
|
|
51
|
+
|
|
52
|
+
```python
|
|
53
|
+
from robot_models.ladder import ladders, needs
|
|
54
|
+
|
|
55
|
+
servo = ladders()["integrated_servo"]
|
|
56
|
+
servo.parameters("M3.stribeck") # what the rung needs, inherited names included:
|
|
57
|
+
# ('output_inertia', 'gear_ratio', 'coulomb_friction', 'viscous_friction', 'breakaway_torque', 'stribeck_velocity')
|
|
58
|
+
servo.holds("M3.stribeck") # ... plus what it reads when a source states it
|
|
59
|
+
servo.fallback("M3.lugre") # the chain it falls back down:
|
|
60
|
+
# ('M3.lugre', 'M3.stribeck', 'M2.coulomb_viscous', 'M1.datasheet', 'M0.ideal')
|
|
61
|
+
servo.canonical("frictionloss_nm") # 'coulomb_friction': any other name resolves to the type's own
|
|
62
|
+
servo.unpack("thermal_r_c") # ('thermal_resistance', 'thermal_time_constant'): a packed array
|
|
63
|
+
servo.rung("M3.stribeck").equation # 'tau_r = (coulomb_friction + (breakaway_torque − coulomb_friction)·exp(...)'
|
|
64
|
+
needs(ladders(), "integrated_servo", "M4.drivetrain") # {type: names}, the composed driver's included
|
|
65
|
+
```
|
|
66
|
+
|
|
67
|
+
- A rung key is `M{level}.{name}`: M0 ideal, M1 datasheet, M2 Coulomb + viscous, M3 state-dependent friction,
|
|
68
|
+
M4 drivetrain, M5 electrics and heat, M6 grey-box residual, M7 learned net; `.wear` variants grow a parameter with use.
|
|
69
|
+
- Each ladder is a tree of explicit bases; a rung needs everything its base needs.
|
|
70
|
+
- Every other name for a quantity is an `Alias` (with a note when it is not the same quantity one for one) or a
|
|
71
|
+
`Packed` array; what a deployment sets (gains, caps) is `DeploymentOnly`, never on a rung.
|
|
72
|
+
- Spec: [PEP 0004](docs/peps/0004-model-ladders-by-type.md).
|
|
73
|
+
|
|
74
|
+
## The 12 types (84 rungs)
|
|
75
|
+
|
|
76
|
+
| type | folder (`src/robot_models/…`) | rungs | what it is |
|
|
77
|
+
|---|---|---:|---|
|
|
78
|
+
| `integrated_servo` | `actuators/servo/` | 14 | A joint in one housing: motor, drive, reducer or none, encoder |
|
|
79
|
+
| `bldc_motor` | `actuators/servo/bldc/` | 9 | A brushless motor alone, at its shaft |
|
|
80
|
+
| `gearbox` | `actuators/servo/gearbox/` | 8 | A gear stage between a motor and its load |
|
|
81
|
+
| `foc_controller` | `actuators/servo/foc_controller/` | 6 | A field-oriented-control motor drive board |
|
|
82
|
+
| `encoder` | `sensors/encoder/` | 4 | An angle sensor on a shaft |
|
|
83
|
+
| `camera` | `sensors/camera/` | 6 | A frame camera's colour image: projection, distortion, exposure |
|
|
84
|
+
| `depth_camera` | `sensors/rgbd/` | 5 | A stereo depth camera: depth on top of a colour stream |
|
|
85
|
+
| `hyperspectral_camera` | `sensors/hyperspectral_camera/` | 5 | A line-scan spectral camera over a belt |
|
|
86
|
+
| `rigid_body_chain` | `arms/rigid_body_chain/` | 10 | A chain of rigid links and joints, open or closed: an arm, a wrist, a five-bar |
|
|
87
|
+
| `gripper` | `end_effectors/gripper/` | 6 | An end effector that grasps, on a chain's flange |
|
|
88
|
+
| `conveyor` | `conveyors/conveyor/` | 7 | A belt driven through a drum |
|
|
89
|
+
| `aruco_marker` | `markers/aruco_marker/` | 4 | A printed sheet carrying ArUco markers rigidly |
|
|
90
|
+
|
|
91
|
+
Each folder holds one `ladder.py`; `ladders()` finds them by walking the package (no registry). The integrated servo's
|
|
92
|
+
eight rung folders (`actuators/rungs/<rung>/`: `model.json`, a README, and Python + JavaScript code where the rung has
|
|
93
|
+
its own) are byte-pinned, so a downstream copy can be checked against them.
|
|
94
|
+
|
|
95
|
+
## Other modules
|
|
96
|
+
|
|
97
|
+
- `robot_models.datasheet`: typed part fields, and a part's values resolved from one Python file per raw source
|
|
98
|
+
([PEP 0003](docs/peps/0003-typed-datasheets-from-sources.md)). Stdlib only.
|
|
99
|
+
- `robot_models.actuators.servo`: the servo type tree (`IntegratedServo`, `BldcMotor`, `Gearbox`), the typed fields
|
|
100
|
+
each ladder's M1 states.
|
|
101
|
+
- `robot_models.homing`: the homing stop core: stops, the backlash ladder, stall evidence, the pure fit, the bench's
|
|
102
|
+
five metrics ([PEP 0001](docs/peps/0001-homing-stop-core.md), [PEP 0002](docs/peps/0002-homing-bench.md)).
|
|
103
|
+
numpy + robot_msgs only; exact mesh contact (`homing.contact`, `homing.cad_bundle`) is the `contact` extra.
|
|
104
|
+
- The ladder core (`robot_models.ladder`) and the citable works (`robot_models.references`) are stdlib only.
|
|
105
|
+
|
|
106
|
+
## Install
|
|
107
|
+
|
|
108
|
+
```bash
|
|
109
|
+
pip install robot-model-ladders
|
|
110
|
+
uv add robot-model-ladders
|
|
111
|
+
```
|
|
112
|
+
|
|
113
|
+
- The PyPI name is robot-model-ladders (robot-models is taken by a near-identical name); you still `import robot_models`.
|
|
114
|
+
- robot-msgs 0.3.0 or later comes with it. The ladders and the datasheets import neither robot_msgs nor numpy.
|
|
115
|
+
- Mesh contact for homing: add the extra, `robot-model-ladders[contact]`.
|
|
116
|
+
- Python 3.11 to 3.14.
|
|
117
|
+
|
|
118
|
+
## Tests
|
|
119
|
+
|
|
120
|
+
From a clone (`--no-sources` because `[tool.uv.sources]` names the author's local robot_msgs checkout):
|
|
121
|
+
|
|
122
|
+
```bash
|
|
123
|
+
uv run --isolated --no-sources --extra test python -m pytest -q --ignore=tests/test_fit_ruler.py --ignore=tests/test_stop_ruler.py
|
|
124
|
+
```
|
|
125
|
+
|
|
126
|
+
- That is what CI runs (`.github/workflows/test.yml`, Python 3.11–3.14).
|
|
127
|
+
- `tests/test_fit_ruler.py` and `tests/test_stop_ruler.py` read CAD bundles from a local, unpublished cache
|
|
128
|
+
(`ROBOT_MODELS_CAD_BUNDLES`, default `~/.cache/cad2robot-build/bundles`); with that cache, drop the two `--ignore`s.
|
|
129
|
+
- `PYTHONDONTWRITEBYTECODE=1` keeps `__pycache__/` out of the rung folders, which robotparts vendors byte for byte.
|
|
130
|
+
|
|
131
|
+
## Design records
|
|
132
|
+
|
|
133
|
+
[docs/peps/](docs/peps/), each a decision with its undo:
|
|
134
|
+
|
|
135
|
+
- [0001](docs/peps/0001-homing-stop-core.md): the homing stop core lives in robot_models
|
|
136
|
+
- [0002](docs/peps/0002-homing-bench.md): the homing bench's pure parts: five metrics, two seams
|
|
137
|
+
- [0003](docs/peps/0003-typed-datasheets-from-sources.md): typed datasheets, resolved from one Python file per source
|
|
138
|
+
- [0004](docs/peps/0004-model-ladders-by-type.md): model ladders by type: one vocabulary per type, rungs as a tree of
|
|
139
|
+
bases
|
|
140
|
+
|
|
141
|
+
## License
|
|
142
|
+
|
|
143
|
+
MIT, see [LICENSE](LICENSE).
|
|
@@ -0,0 +1,108 @@
|
|
|
1
|
+
# robot_models
|
|
2
|
+
|
|
3
|
+
Generic physical models of robot part **types** (no maker, no SKU): each type is a ladder of models from ideal to
|
|
4
|
+
learned, and every rung states its parameters, its equation and its references.
|
|
5
|
+
|
|
6
|
+
```
|
|
7
|
+
robot_msgs ← robot_models ← robot_parts ← robot_descriptions, with sim2real on top
|
|
8
|
+
```
|
|
9
|
+
|
|
10
|
+
- [robot_msgs](https://github.com/zacharyyamaoka/robot_msgs): the message types this package builds on.
|
|
11
|
+
- [sim2real](https://github.com/zacharyyamaoka/sim2real): the outer API (twins, calibration) over the stack.
|
|
12
|
+
- robot_parts (robotparts, private): the part catalogue, whose parts point at these types and rungs.
|
|
13
|
+
- Type data only: parameter names, SI units, definitions, equations. Never a value measured on one unit.
|
|
14
|
+
|
|
15
|
+
## Usage
|
|
16
|
+
|
|
17
|
+
```python
|
|
18
|
+
from robot_models.ladder import ladders, needs
|
|
19
|
+
|
|
20
|
+
servo = ladders()["integrated_servo"]
|
|
21
|
+
servo.parameters("M3.stribeck") # what the rung needs, inherited names included:
|
|
22
|
+
# ('output_inertia', 'gear_ratio', 'coulomb_friction', 'viscous_friction', 'breakaway_torque', 'stribeck_velocity')
|
|
23
|
+
servo.holds("M3.stribeck") # ... plus what it reads when a source states it
|
|
24
|
+
servo.fallback("M3.lugre") # the chain it falls back down:
|
|
25
|
+
# ('M3.lugre', 'M3.stribeck', 'M2.coulomb_viscous', 'M1.datasheet', 'M0.ideal')
|
|
26
|
+
servo.canonical("frictionloss_nm") # 'coulomb_friction': any other name resolves to the type's own
|
|
27
|
+
servo.unpack("thermal_r_c") # ('thermal_resistance', 'thermal_time_constant'): a packed array
|
|
28
|
+
servo.rung("M3.stribeck").equation # 'tau_r = (coulomb_friction + (breakaway_torque − coulomb_friction)·exp(...)'
|
|
29
|
+
needs(ladders(), "integrated_servo", "M4.drivetrain") # {type: names}, the composed driver's included
|
|
30
|
+
```
|
|
31
|
+
|
|
32
|
+
- A rung key is `M{level}.{name}`: M0 ideal, M1 datasheet, M2 Coulomb + viscous, M3 state-dependent friction,
|
|
33
|
+
M4 drivetrain, M5 electrics and heat, M6 grey-box residual, M7 learned net; `.wear` variants grow a parameter with use.
|
|
34
|
+
- Each ladder is a tree of explicit bases; a rung needs everything its base needs.
|
|
35
|
+
- Every other name for a quantity is an `Alias` (with a note when it is not the same quantity one for one) or a
|
|
36
|
+
`Packed` array; what a deployment sets (gains, caps) is `DeploymentOnly`, never on a rung.
|
|
37
|
+
- Spec: [PEP 0004](docs/peps/0004-model-ladders-by-type.md).
|
|
38
|
+
|
|
39
|
+
## The 12 types (84 rungs)
|
|
40
|
+
|
|
41
|
+
| type | folder (`src/robot_models/…`) | rungs | what it is |
|
|
42
|
+
|---|---|---:|---|
|
|
43
|
+
| `integrated_servo` | `actuators/servo/` | 14 | A joint in one housing: motor, drive, reducer or none, encoder |
|
|
44
|
+
| `bldc_motor` | `actuators/servo/bldc/` | 9 | A brushless motor alone, at its shaft |
|
|
45
|
+
| `gearbox` | `actuators/servo/gearbox/` | 8 | A gear stage between a motor and its load |
|
|
46
|
+
| `foc_controller` | `actuators/servo/foc_controller/` | 6 | A field-oriented-control motor drive board |
|
|
47
|
+
| `encoder` | `sensors/encoder/` | 4 | An angle sensor on a shaft |
|
|
48
|
+
| `camera` | `sensors/camera/` | 6 | A frame camera's colour image: projection, distortion, exposure |
|
|
49
|
+
| `depth_camera` | `sensors/rgbd/` | 5 | A stereo depth camera: depth on top of a colour stream |
|
|
50
|
+
| `hyperspectral_camera` | `sensors/hyperspectral_camera/` | 5 | A line-scan spectral camera over a belt |
|
|
51
|
+
| `rigid_body_chain` | `arms/rigid_body_chain/` | 10 | A chain of rigid links and joints, open or closed: an arm, a wrist, a five-bar |
|
|
52
|
+
| `gripper` | `end_effectors/gripper/` | 6 | An end effector that grasps, on a chain's flange |
|
|
53
|
+
| `conveyor` | `conveyors/conveyor/` | 7 | A belt driven through a drum |
|
|
54
|
+
| `aruco_marker` | `markers/aruco_marker/` | 4 | A printed sheet carrying ArUco markers rigidly |
|
|
55
|
+
|
|
56
|
+
Each folder holds one `ladder.py`; `ladders()` finds them by walking the package (no registry). The integrated servo's
|
|
57
|
+
eight rung folders (`actuators/rungs/<rung>/`: `model.json`, a README, and Python + JavaScript code where the rung has
|
|
58
|
+
its own) are byte-pinned, so a downstream copy can be checked against them.
|
|
59
|
+
|
|
60
|
+
## Other modules
|
|
61
|
+
|
|
62
|
+
- `robot_models.datasheet`: typed part fields, and a part's values resolved from one Python file per raw source
|
|
63
|
+
([PEP 0003](docs/peps/0003-typed-datasheets-from-sources.md)). Stdlib only.
|
|
64
|
+
- `robot_models.actuators.servo`: the servo type tree (`IntegratedServo`, `BldcMotor`, `Gearbox`), the typed fields
|
|
65
|
+
each ladder's M1 states.
|
|
66
|
+
- `robot_models.homing`: the homing stop core: stops, the backlash ladder, stall evidence, the pure fit, the bench's
|
|
67
|
+
five metrics ([PEP 0001](docs/peps/0001-homing-stop-core.md), [PEP 0002](docs/peps/0002-homing-bench.md)).
|
|
68
|
+
numpy + robot_msgs only; exact mesh contact (`homing.contact`, `homing.cad_bundle`) is the `contact` extra.
|
|
69
|
+
- The ladder core (`robot_models.ladder`) and the citable works (`robot_models.references`) are stdlib only.
|
|
70
|
+
|
|
71
|
+
## Install
|
|
72
|
+
|
|
73
|
+
```bash
|
|
74
|
+
pip install robot-model-ladders
|
|
75
|
+
uv add robot-model-ladders
|
|
76
|
+
```
|
|
77
|
+
|
|
78
|
+
- The PyPI name is robot-model-ladders (robot-models is taken by a near-identical name); you still `import robot_models`.
|
|
79
|
+
- robot-msgs 0.3.0 or later comes with it. The ladders and the datasheets import neither robot_msgs nor numpy.
|
|
80
|
+
- Mesh contact for homing: add the extra, `robot-model-ladders[contact]`.
|
|
81
|
+
- Python 3.11 to 3.14.
|
|
82
|
+
|
|
83
|
+
## Tests
|
|
84
|
+
|
|
85
|
+
From a clone (`--no-sources` because `[tool.uv.sources]` names the author's local robot_msgs checkout):
|
|
86
|
+
|
|
87
|
+
```bash
|
|
88
|
+
uv run --isolated --no-sources --extra test python -m pytest -q --ignore=tests/test_fit_ruler.py --ignore=tests/test_stop_ruler.py
|
|
89
|
+
```
|
|
90
|
+
|
|
91
|
+
- That is what CI runs (`.github/workflows/test.yml`, Python 3.11–3.14).
|
|
92
|
+
- `tests/test_fit_ruler.py` and `tests/test_stop_ruler.py` read CAD bundles from a local, unpublished cache
|
|
93
|
+
(`ROBOT_MODELS_CAD_BUNDLES`, default `~/.cache/cad2robot-build/bundles`); with that cache, drop the two `--ignore`s.
|
|
94
|
+
- `PYTHONDONTWRITEBYTECODE=1` keeps `__pycache__/` out of the rung folders, which robotparts vendors byte for byte.
|
|
95
|
+
|
|
96
|
+
## Design records
|
|
97
|
+
|
|
98
|
+
[docs/peps/](docs/peps/), each a decision with its undo:
|
|
99
|
+
|
|
100
|
+
- [0001](docs/peps/0001-homing-stop-core.md): the homing stop core lives in robot_models
|
|
101
|
+
- [0002](docs/peps/0002-homing-bench.md): the homing bench's pure parts: five metrics, two seams
|
|
102
|
+
- [0003](docs/peps/0003-typed-datasheets-from-sources.md): typed datasheets, resolved from one Python file per source
|
|
103
|
+
- [0004](docs/peps/0004-model-ladders-by-type.md): model ladders by type: one vocabulary per type, rungs as a tree of
|
|
104
|
+
bases
|
|
105
|
+
|
|
106
|
+
## License
|
|
107
|
+
|
|
108
|
+
MIT, see [LICENSE](LICENSE).
|
|
@@ -0,0 +1,65 @@
|
|
|
1
|
+
> **Generated file.** Written by [`tools/make_type_docs.py`](../tools/make_type_docs.py) from each type folder's `ladder.py`: edit the ladders, not this file, then run `python tools/make_type_docs.py` from the repository root.
|
|
2
|
+
|
|
3
|
+
# The 12 types
|
|
4
|
+
|
|
5
|
+
Every part type robot_models models, 84 rungs in all. Each type is a ladder of models in a folder of its own under [`src/robot_models/`](../src/robot_models), and each folder's README.md shows its rung tree, its rungs with their equations and references, its vocabulary, aliases and the names that belong to a deployment instead.
|
|
6
|
+
|
|
7
|
+
```text
|
|
8
|
+
robot_msgs ← robot_models ← robot_parts ← robot_descriptions, with sim2real on top
|
|
9
|
+
```
|
|
10
|
+
|
|
11
|
+
| type | what it is | folder | rungs | top physics rung(s) | residual, learned | datasheet class |
|
|
12
|
+
| --- | --- | --- | ---: | --- | --- | --- |
|
|
13
|
+
| [`integrated_servo`](../src/robot_models/actuators/servo/README.md) | A joint in one housing: a motor, its drive, a reducer or none, and an encoder. | [`actuators/servo/`](../src/robot_models/actuators/servo) | 14 | [`M5.dcmotor`](../src/robot_models/actuators/servo/README.md#rung-m5-dcmotor), [`M5.envelope`](../src/robot_models/actuators/servo/README.md#rung-m5-envelope), [`M5.wear`](../src/robot_models/actuators/servo/README.md#rung-m5-wear) | [`M6.residual`](../src/robot_models/actuators/servo/README.md#rung-m6-residual), [`M7.learned`](../src/robot_models/actuators/servo/README.md#rung-m7-learned) | [`IntegratedServo`](../src/robot_models/actuators/servo/integrated_servo.py) |
|
|
14
|
+
| [`bldc_motor`](../src/robot_models/actuators/servo/bldc/README.md) | A brushless motor alone, at its shaft. | [`actuators/servo/bldc/`](../src/robot_models/actuators/servo/bldc) | 9 | [`M5.dcmotor`](../src/robot_models/actuators/servo/bldc/README.md#rung-m5-dcmotor), [`M5.wear`](../src/robot_models/actuators/servo/bldc/README.md#rung-m5-wear) | [`M6.residual`](../src/robot_models/actuators/servo/bldc/README.md#rung-m6-residual), [`M7.learned`](../src/robot_models/actuators/servo/bldc/README.md#rung-m7-learned) | [`BldcMotor`](../src/robot_models/actuators/servo/bldc/bldc_motor.py) |
|
|
15
|
+
| [`foc_controller`](../src/robot_models/actuators/servo/foc_controller/README.md) | A field-oriented-control motor drive board. | [`actuators/servo/foc_controller/`](../src/robot_models/actuators/servo/foc_controller) | 6 | [`M2.ceiling_heat`](../src/robot_models/actuators/servo/foc_controller/README.md#rung-m2-ceiling_heat), [`M2.wear`](../src/robot_models/actuators/servo/foc_controller/README.md#rung-m2-wear) | [`M6.residual`](../src/robot_models/actuators/servo/foc_controller/README.md#rung-m6-residual), [`M7.learned`](../src/robot_models/actuators/servo/foc_controller/README.md#rung-m7-learned) | — |
|
|
16
|
+
| [`gearbox`](../src/robot_models/actuators/servo/gearbox/README.md) | A gear stage between a motor and its load. | [`actuators/servo/gearbox/`](../src/robot_models/actuators/servo/gearbox) | 8 | [`M4.drivetrain`](../src/robot_models/actuators/servo/gearbox/README.md#rung-m4-drivetrain), [`M4.wear`](../src/robot_models/actuators/servo/gearbox/README.md#rung-m4-wear) | [`M6.residual`](../src/robot_models/actuators/servo/gearbox/README.md#rung-m6-residual), [`M7.learned`](../src/robot_models/actuators/servo/gearbox/README.md#rung-m7-learned) | [`Gearbox`](../src/robot_models/actuators/servo/gearbox/gearbox.py) |
|
|
17
|
+
| [`rigid_body_chain`](../src/robot_models/arms/rigid_body_chain/README.md) | A chain of rigid links and joints, open or closed: a whole arm, a sub-assembly, a wrist, a five-bar. | [`arms/rigid_body_chain/`](../src/robot_models/arms/rigid_body_chain) | 10 | [`M3.compliance`](../src/robot_models/arms/rigid_body_chain/README.md#rung-m3-compliance), [`M3.wear`](../src/robot_models/arms/rigid_body_chain/README.md#rung-m3-wear) | [`M6.residual`](../src/robot_models/arms/rigid_body_chain/README.md#rung-m6-residual), [`M6.inertial_residual`](../src/robot_models/arms/rigid_body_chain/README.md#rung-m6-inertial_residual), [`M7.learned`](../src/robot_models/arms/rigid_body_chain/README.md#rung-m7-learned) | — |
|
|
18
|
+
| [`conveyor`](../src/robot_models/conveyors/conveyor/README.md) | A belt driven through a drum. | [`conveyors/conveyor/`](../src/robot_models/conveyors/conveyor) | 7 | [`M4.stretch`](../src/robot_models/conveyors/conveyor/README.md#rung-m4-stretch), [`M4.wear`](../src/robot_models/conveyors/conveyor/README.md#rung-m4-wear) | [`M6.residual`](../src/robot_models/conveyors/conveyor/README.md#rung-m6-residual), [`M7.learned`](../src/robot_models/conveyors/conveyor/README.md#rung-m7-learned) | — |
|
|
19
|
+
| [`gripper`](../src/robot_models/end_effectors/gripper/README.md) | An end effector that grasps, on a chain's flange. | [`end_effectors/gripper/`](../src/robot_models/end_effectors/gripper) | 6 | [`M2.contact`](../src/robot_models/end_effectors/gripper/README.md#rung-m2-contact), [`M2.wear`](../src/robot_models/end_effectors/gripper/README.md#rung-m2-wear) | [`M6.residual`](../src/robot_models/end_effectors/gripper/README.md#rung-m6-residual), [`M7.learned`](../src/robot_models/end_effectors/gripper/README.md#rung-m7-learned) | — |
|
|
20
|
+
| [`aruco_marker`](../src/robot_models/markers/aruco_marker/README.md) | A printed sheet carrying one or more ArUco markers rigidly. | [`markers/aruco_marker/`](../src/robot_models/markers/aruco_marker) | 4 | [`M3.curl`](../src/robot_models/markers/aruco_marker/README.md#rung-m3-curl) | — | — |
|
|
21
|
+
| [`camera`](../src/robot_models/sensors/camera/README.md) | A frame camera's colour image: projection, distortion, exposure. | [`sensors/camera/`](../src/robot_models/sensors/camera) | 6 | [`M3.rolling_shutter`](../src/robot_models/sensors/camera/README.md#rung-m3-rolling_shutter), [`M3.wear`](../src/robot_models/sensors/camera/README.md#rung-m3-wear) | [`M6.residual`](../src/robot_models/sensors/camera/README.md#rung-m6-residual) | — |
|
|
22
|
+
| [`encoder`](../src/robot_models/sensors/encoder/README.md) | An angle sensor on a shaft, such as a drive's rotor encoder. | [`sensors/encoder/`](../src/robot_models/sensors/encoder) | 4 | [`M2.eccentricity`](../src/robot_models/sensors/encoder/README.md#rung-m2-eccentricity), [`M2.wear`](../src/robot_models/sensors/encoder/README.md#rung-m2-wear) | — | — |
|
|
23
|
+
| [`hyperspectral_camera`](../src/robot_models/sensors/hyperspectral_camera/README.md) | A line-scan spectral camera over a belt. | [`sensors/hyperspectral_camera/`](../src/robot_models/sensors/hyperspectral_camera) | 5 | [`M3.pushbroom`](../src/robot_models/sensors/hyperspectral_camera/README.md#rung-m3-pushbroom), [`M3.wear`](../src/robot_models/sensors/hyperspectral_camera/README.md#rung-m3-wear) | — | — |
|
|
24
|
+
| [`depth_camera`](../src/robot_models/sensors/rgbd/README.md) | A stereo depth camera: depth on top of a colour stream. | [`sensors/rgbd/`](../src/robot_models/sensors/rgbd) | 5 | [`M2.depth_bias`](../src/robot_models/sensors/rgbd/README.md#rung-m2-depth_bias), [`M2.wear`](../src/robot_models/sensors/rgbd/README.md#rung-m2-wear) | [`M6.residual`](../src/robot_models/sensors/rgbd/README.md#rung-m6-residual) | — |
|
|
25
|
+
| **12 types** | | | **84** | | | |
|
|
26
|
+
|
|
27
|
+
## The folder tree
|
|
28
|
+
|
|
29
|
+
- `actuators/`
|
|
30
|
+
- [`servo/`](../src/robot_models/actuators/servo/README.md): `integrated_servo`
|
|
31
|
+
- [`bldc/`](../src/robot_models/actuators/servo/bldc/README.md): `bldc_motor`
|
|
32
|
+
- [`foc_controller/`](../src/robot_models/actuators/servo/foc_controller/README.md): `foc_controller`
|
|
33
|
+
- [`gearbox/`](../src/robot_models/actuators/servo/gearbox/README.md): `gearbox`
|
|
34
|
+
- `arms/`
|
|
35
|
+
- [`rigid_body_chain/`](../src/robot_models/arms/rigid_body_chain/README.md): `rigid_body_chain`
|
|
36
|
+
- `conveyors/`
|
|
37
|
+
- [`conveyor/`](../src/robot_models/conveyors/conveyor/README.md): `conveyor`
|
|
38
|
+
- `end_effectors/`
|
|
39
|
+
- [`gripper/`](../src/robot_models/end_effectors/gripper/README.md): `gripper`
|
|
40
|
+
- `markers/`
|
|
41
|
+
- [`aruco_marker/`](../src/robot_models/markers/aruco_marker/README.md): `aruco_marker`
|
|
42
|
+
- `sensors/`
|
|
43
|
+
- [`camera/`](../src/robot_models/sensors/camera/README.md): `camera`
|
|
44
|
+
- [`encoder/`](../src/robot_models/sensors/encoder/README.md): `encoder`
|
|
45
|
+
- [`hyperspectral_camera/`](../src/robot_models/sensors/hyperspectral_camera/README.md): `hyperspectral_camera`
|
|
46
|
+
- [`rgbd/`](../src/robot_models/sensors/rgbd/README.md): `depth_camera`
|
|
47
|
+
|
|
48
|
+
## Across types
|
|
49
|
+
|
|
50
|
+
- [`integrated_servo` `M4.drivetrain`](../src/robot_models/actuators/servo/README.md#rung-m4-drivetrain) composes [`foc_controller` `M1.delay_loop`](../src/robot_models/actuators/servo/foc_controller/README.md#rung-m1-delay_loop)
|
|
51
|
+
- [`integrated_servo` `M5.envelope`](../src/robot_models/actuators/servo/README.md#rung-m5-envelope) composes [`foc_controller` `M2.ceiling_heat`](../src/robot_models/actuators/servo/foc_controller/README.md#rung-m2-ceiling_heat)
|
|
52
|
+
|
|
53
|
+
## Reading a rung key
|
|
54
|
+
|
|
55
|
+
A rung key is `M{level}.{name}`. The physics levels M0 to M5 are the actuator layers of [robotparts](#name-robotparts), where the numbering started: M0 the ideal model, M1 the datasheet, M2 Coulomb and viscous friction, M3 state-dependent friction, M4 the drivetrain, M5 electrics and heat. Every other type climbs its own physics over the same levels, from its simplest model at M0 (the ideal or nominal one). M6 is always the grey-box residual and M7 always the learned net; a rung named `wear` grows a parameter with use. Each rung extends one base and needs everything its base needs. Spec: [PEP 0004](peps/0004-model-ladders-by-type.md).
|
|
56
|
+
|
|
57
|
+
## Projects the notes name
|
|
58
|
+
|
|
59
|
+
The ladders' notes say where a rung or a name came from. These are the projects they name.
|
|
60
|
+
|
|
61
|
+
- <a id="name-cad2robot"></a>**Cad2Robot** ([cad2robot.com](https://cad2robot.com)): a pipeline from a robot's CAD to a MuJoCo simulation. Its exporter's motor and servo fields are aliases here.
|
|
62
|
+
- <a id="name-mujoco"></a>**MuJoCo** ([mujoco.org](https://mujoco.org)): the physics engine. Some rungs use its models as written (the servo's M5.dcmotor is its DC motor), and most packed names are that model's parameter arrays.
|
|
63
|
+
- <a id="name-robotparts"></a>**robotparts** ([robotparts.dev](https://robotparts.dev)): an open catalogue of robot parts. Its actuator models' layers are the physics levels M0 to M5 here, its eight actuator rungs moved here as the servo's code (actuators/rungs/), and its registry keys ("the registry") and old user-part keys are canonical names or aliases.
|
|
64
|
+
- <a id="name-sim2real"></a>**sim2real** ([github.com/zacharyyamaoka/sim2real](https://github.com/zacharyyamaoka/sim2real)): the outer API on top of this stack: twins and their calibration. Its type cards were the first source of most ladders here, and its twin names are aliases.
|
|
65
|
+
- <a id="name-the-rack-twin"></a>**the rack twin**: a fitted model of one lab test rack, kept with robotparts' lab tools and never published. Only its structure is used here: its terms and equations, never its fitted values.
|
|
@@ -0,0 +1,41 @@
|
|
|
1
|
+
# PEP 0001: The homing stop core lives in robot_models
|
|
2
|
+
|
|
3
|
+
- **Status:** accepted, 2026-11-12
|
|
4
|
+
- **Decision report:** `/home/bam/bam_ws/reports/homing-subassembly-proposals-2026-11-12.html` (builder `bam_ws/docs/homing/build_proposals.py`). It recommends B, "two verbs, one stop core": `home()` on every boot with a stored backlash table, `identify_backlash()` at calibration, both on one pure stop core, built on C's homing bench, with A's one-routine procedure as a rival leaderboard row.
|
|
5
|
+
- **Layering:** the Robot Models Layering decision (vault, `Projects/robot_msgs/Robot Models Layering — Decision (2026-11-12).md`), in the order PEP 0004 corrected it to (2026-11-16): `robot_msgs ← robot_models ← robot_parts ← robot_descriptions`, with sim2real on top.
|
|
6
|
+
|
|
7
|
+
## Decision
|
|
8
|
+
|
|
9
|
+
1. **Home.** The pure stop core goes in a new local repo, `/home/bam/robot_models` (package `robot_models`, PyPI name `robot-models`). On 2026-11-12 no peer owned it: the path did not exist, no sim2real or bam_ws worktree or branch named it, and nothing imported it. It is local only, with no remote. The first public push is Zach's call.
|
|
10
|
+
2. **Scope.** Only `robot_models.homing` lives here so far. The decision note's move plan (metrics, fits, type cards) is separate and still gated on its step 0.
|
|
11
|
+
3. **Dependencies.** The core is `robot-msgs` + numpy. The `contact` extra adds coal 3.0.2 (the version bam_pick_worlds already locks through pin 3.8.0) and trimesh. `tests/test_import_direction.py` enforces this with an AST scan, three planted violations held red, and a runtime check that importing the core loads no contact library. `uv run --isolated` without the extra imports the core.
|
|
12
|
+
|
|
13
|
+
## What is here
|
|
14
|
+
|
|
15
|
+
| Name | What it is |
|
|
16
|
+
|---|---|
|
|
17
|
+
| `StopSide`, `StopMap` | One joint side's stop angle (`None` = never stops, never a silent 0), with basis `cad`, `typed` or `measured` |
|
|
18
|
+
| `BacklashModel` | The ladder. B0: none. B1: `gear_backlash` dead zone (`method="deadzone"`, `zero="center"`) in its rigid limit. B2: B1 plus a lumped series compliance (mesh + stop + structure; only the sum is identifiable without an output sensor) |
|
|
19
|
+
| `JointBacklash`, `BacklashTable` | Per-joint model plus observable flags; `home()` reads it on boot, `identify_backlash()` writes it |
|
|
20
|
+
| `StallEvidence` | One settled stall: joint, side, torque magnitude, raw motor-side encoder |
|
|
21
|
+
| `JointZero`, `HomingResult` | Zero per joint (`q = raw + offset`) with its repeat spread; `corrected(table)` re-fits the stored stalls without moving |
|
|
22
|
+
| `fit()` | Pure, numpy: stalls in, zero + backlash out. Compliance comes from two torque levels, the gap from both sides minus the CAD span (sim only: on real a CAD span error aliases into the gap) |
|
|
23
|
+
| `contact.first_contact()` | Extra: the exporter's algorithm 2 (`cad2robot/hardstops.py`, python-fcl) ported to coal. Conservative advancement capped at 1°, then bisection to 0.05°/8. It returns the last angle verified clear |
|
|
24
|
+
| `cad_bundle` | Extra: reads a cad2robot bundle's `hardstops.json` and places the named visual meshes from the exporter URDF |
|
|
25
|
+
|
|
26
|
+
**Sign convention** (as `gear_backlash`): `twist = q_link - q_motor`. Pressing into the `side` stop with torque `T` leaves the motor past the link by `side * (gap/2 + compliance*T)`. So `raw = q_stop + side*(gap/2 + c*T) - offset`.
|
|
27
|
+
|
|
28
|
+
**Touching criterion.** A stop whose `hardstops.json` entry has a `distance_mm` uses the exporter's proximity `contact_mm` (0.05 mm). The loop-joint sweeps (revolute_6 and revolute_7, `kind` `own_frame` / `interference`, `distance_mm: null`) used overlap. A 0.05 mm proximity there lands early by exactly 0.05 mm / lever: 0.073° on revolute_6 (lever 39 mm), and 0.037° to 0.043° on revolute_7 (lever 79 mm). That is how the prototype found it.
|
|
29
|
+
|
|
30
|
+
## The ruler (committed before the code it judges)
|
|
31
|
+
|
|
32
|
+
`tests/test_stop_ruler.py` and `tests/test_fit_ruler.py`, marked `ruler`:
|
|
33
|
+
|
|
34
|
+
- coal `first_contact` on the visual meshes `hardstops.json` names reproduces the v11 five-bar bundle 8957130: revolute_3 ±89.975°, revolute_6 −90.03° / +125.00°, revolute_7 −112.69° / +197.77°, revolute_8 and revolute_34 null. It also reproduces the wrist bundle 583ee39 (revolute_11 ±169.85°, revolute_14 and revolute_17 ±169.849°). The tolerance is 0.05°.
|
|
35
|
+
- A strict xfail at 0.01° on the exporter's `stop_mesh` channel: it flips once the exporter emits `stops.json` and the stop meshes (exporter change request in the report).
|
|
36
|
+
- Mutations that must go red: delete a stop mesh, shift a stop by 0.1°, double the hidden gap.
|
|
37
|
+
- `hardstops.json` sha256 is pinned, so a re-export cannot quietly move the ruler.
|
|
38
|
+
|
|
39
|
+
## Not here (later steps)
|
|
40
|
+
|
|
41
|
+
The kinematic `HomingPlant`, procedures as `plan()`/`observe()` black boxes emitting a robot_msgs `JointCommandSequence` (run by the `JointCommandSequenceController`), the bench, the leaderboard, the MuJoCo rung and the real rung.
|
|
@@ -0,0 +1,30 @@
|
|
|
1
|
+
# PEP 0002: The homing bench's pure parts — the five metrics and the two seams
|
|
2
|
+
|
|
3
|
+
- **Status:** accepted, 2026-11-12
|
|
4
|
+
- **Follows:** PEP 0001 (the stop core). Decision report `/home/bam/bam_ws/reports/homing-subassembly-proposals-2026-11-12.html`, steps 3–4 of "What the default does next".
|
|
5
|
+
- **Layering:** pure parts here (`robot_msgs <- robot_models`). The kinematic plant, the procedures, the bench loop and the W&B leaderboard need a controller and a rig, so they live in sim2real (`sim2real.sim.homing`, branch `claude/homing-bench`), on top.
|
|
6
|
+
|
|
7
|
+
## Decision
|
|
8
|
+
|
|
9
|
+
1. **Seams (`robot_models.homing.protocols`).** `HomingPlant`: `reset(start)`, `tick(command, dt, defines)`, `truth()`. `HomingProcedure`: `plan(prior, so_far) -> JointCommandSequence | None` (collect) and `observe(prior, phases) -> HomingResult` (fit). `Prior` is what a procedure may know before it moves (stop map, stored backlash table, seek side, caps). `Phase` is one sequence as it ran. Typing only.
|
|
10
|
+
2. **Metrics (`robot_models.homing.metrics`).** Computed from outputs and truth only, never a procedure's code:
|
|
11
|
+
|
|
12
|
+
| Metric | Definition |
|
|
13
|
+
|---|---|
|
|
14
|
+
| `time_to_home_s` | tick clock, first command to done; median and p95 (nearest rank) over finished episodes |
|
|
15
|
+
| `reliability_pct` | done with no abort/timeout/refusal AND every stall it used truly on the CAD stop it meant (within 1.0°, `stall_proof`'s tolerance); every episode in the denominator |
|
|
16
|
+
| `any_start_pct` | reliable AND every joint's zero inside the rung gate |
|
|
17
|
+
| `backlash_error_deg` | per drive \|identified gap − hidden gap\|, worst drive per episode, p95 over reliable episodes; unidentified = `None` (shown '—'), never 0; `observable_pct` beside it; gate per drive max(1′, 25 % of truth) |
|
|
18
|
+
| `joint_angle_error_deg` | per joint \|identified zero − true zero\|, worst joint per episode, p95 over reliable episodes; an unzeroed joint is `missing`, never perfect |
|
|
19
|
+
|
|
20
|
+
No weighted sum: sort by reliability, then zero error, then time.
|
|
21
|
+
|
|
22
|
+
3. **Ruler first.** `tests/test_metrics_ruler.py` was committed against a deliberately wrong `metrics.py` (unfinished episodes dropped from the denominator, stalls not checked against their stop, mean for p95, unidentified gaps read as 0) and recorded red before the real one went in.
|
|
23
|
+
|
|
24
|
+
## Addendum 1 (2026-11-12): assembly-mode starts are judged on the MuJoCo rung
|
|
25
|
+
|
|
26
|
+
**Ruling (the coordinator, per the decision report's "kinematic proves geometry, MuJoCo proves dynamics").** A start on the mirrored assembly - the flipped crank, and any start whose branch is the mirror grid of `loops.json` - is an *assembly-mode start*. Its reliability is judged on the MuJoCo rung. The kinematic rung's reliability gate is **100 % over working-assembly starts**; its assembly-mode cards are still computed and shown, labelled "judged on MuJoCo", with no verdict of their own. The strict xfail `test_recover_first_homes_from_the_flipped_crank` (sim2real) stays as the kinematic record: it is not removed, and it is expected to keep failing there.
|
|
27
|
+
|
|
28
|
+
**WHY.** The kinematic plant has no gravity and no inertia, so nothing can carry the loop through the toggle between its two assemblies: from the flipped crank, recover_first's stalls land on mirror contacts and its step 7 times out (re-score 2026-11-12: 98.6 %, flipped_crank 0/15, every other start 100 %). That number measures the plant, not the procedure. On the MuJoCo rung gravity can swing the loop across (or fail to), which is exactly what an assembly-mode start asks.
|
|
29
|
+
|
|
30
|
+
**Scorecard split.** Every bench result now carries `scorecards_by_scope = {working_assembly, assembly_mode}` beside the all-starts `scorecards` (sim2real `bench.split_scorecards`); each card names where its verdict is taken (`judged_on`). The metrics themselves are unchanged: the split is a choice of denominator per rung, made in the bench, not in `metrics.py`.
|