urml-edu-runtime 0.5.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.
- urml_edu_runtime-0.5.0/.gitignore +114 -0
- urml_edu_runtime-0.5.0/PKG-INFO +127 -0
- urml_edu_runtime-0.5.0/README.md +82 -0
- urml_edu_runtime-0.5.0/SPEC-GAPS.md +55 -0
- urml_edu_runtime-0.5.0/pyproject.toml +127 -0
- urml_edu_runtime-0.5.0/scripts/marty_validate.py +290 -0
- urml_edu_runtime-0.5.0/src/urml_edu_runtime/__init__.py +72 -0
- urml_edu_runtime-0.5.0/src/urml_edu_runtime/_version.py +3 -0
- urml_edu_runtime-0.5.0/src/urml_edu_runtime/adapter.py +1167 -0
- urml_edu_runtime-0.5.0/src/urml_edu_runtime/config.py +116 -0
- urml_edu_runtime-0.5.0/src/urml_edu_runtime/microduck.py +282 -0
- urml_edu_runtime-0.5.0/src/urml_edu_runtime/py.typed +0 -0
- urml_edu_runtime-0.5.0/src/urml_edu_runtime/reachy.py +206 -0
- urml_edu_runtime-0.5.0/tests/__init__.py +0 -0
- urml_edu_runtime-0.5.0/tests/integration/__init__.py +0 -0
- urml_edu_runtime-0.5.0/tests/integration/test_edu_adapter_live.py +42 -0
- urml_edu_runtime-0.5.0/tests/test_edu_adapters.py +740 -0
- urml_edu_runtime-0.5.0/tests/test_microduck_adapter.py +189 -0
- urml_edu_runtime-0.5.0/tests/test_reachy_adapter.py +108 -0
|
@@ -0,0 +1,114 @@
|
|
|
1
|
+
# --- Python ---
|
|
2
|
+
__pycache__/
|
|
3
|
+
*.py[cod]
|
|
4
|
+
*$py.class
|
|
5
|
+
*.so
|
|
6
|
+
.Python
|
|
7
|
+
build/
|
|
8
|
+
dist/
|
|
9
|
+
develop-eggs/
|
|
10
|
+
downloads/
|
|
11
|
+
eggs/
|
|
12
|
+
.eggs/
|
|
13
|
+
lib/
|
|
14
|
+
lib64/
|
|
15
|
+
parts/
|
|
16
|
+
sdist/
|
|
17
|
+
var/
|
|
18
|
+
wheels/
|
|
19
|
+
*.egg-info/
|
|
20
|
+
.installed.cfg
|
|
21
|
+
*.egg
|
|
22
|
+
MANIFEST
|
|
23
|
+
|
|
24
|
+
# Virtual envs
|
|
25
|
+
.venv/
|
|
26
|
+
venv/
|
|
27
|
+
env/
|
|
28
|
+
ENV/
|
|
29
|
+
.python-version
|
|
30
|
+
|
|
31
|
+
# Test / coverage / mypy / pyright
|
|
32
|
+
.coverage
|
|
33
|
+
.coverage.*
|
|
34
|
+
.cache
|
|
35
|
+
.pytest_cache/
|
|
36
|
+
.mypy_cache/
|
|
37
|
+
.dmypy.json
|
|
38
|
+
.pyre/
|
|
39
|
+
.pyright/
|
|
40
|
+
htmlcov/
|
|
41
|
+
nosetests.xml
|
|
42
|
+
coverage.xml
|
|
43
|
+
*.cover
|
|
44
|
+
.hypothesis/
|
|
45
|
+
.tox/
|
|
46
|
+
|
|
47
|
+
# --- Node / web tooling (kept out of core repo; here for safety) ---
|
|
48
|
+
node_modules/
|
|
49
|
+
.pnp.*
|
|
50
|
+
.yarn/cache/
|
|
51
|
+
.yarn/unplugged/
|
|
52
|
+
.yarn/build-state.yml
|
|
53
|
+
.yarn/install-state.gz
|
|
54
|
+
npm-debug.log*
|
|
55
|
+
yarn-debug.log*
|
|
56
|
+
yarn-error.log*
|
|
57
|
+
|
|
58
|
+
# --- C++ / Rust build artifacts (in case reference runtimes land here in early Phase 1) ---
|
|
59
|
+
target/
|
|
60
|
+
*.o
|
|
61
|
+
*.obj
|
|
62
|
+
*.a
|
|
63
|
+
*.lib
|
|
64
|
+
*.dll
|
|
65
|
+
*.dylib
|
|
66
|
+
*.exe
|
|
67
|
+
*.pdb
|
|
68
|
+
cmake-build-*/
|
|
69
|
+
CMakeCache.txt
|
|
70
|
+
CMakeFiles/
|
|
71
|
+
CMakeScripts/
|
|
72
|
+
Testing/
|
|
73
|
+
cmake_install.cmake
|
|
74
|
+
install_manifest.txt
|
|
75
|
+
compile_commands.json
|
|
76
|
+
|
|
77
|
+
# --- ROS 2 build dirs ---
|
|
78
|
+
build/
|
|
79
|
+
install/
|
|
80
|
+
log/
|
|
81
|
+
|
|
82
|
+
# --- Editor and OS junk ---
|
|
83
|
+
.vscode/
|
|
84
|
+
.idea/
|
|
85
|
+
*.swp
|
|
86
|
+
*.swo
|
|
87
|
+
*~
|
|
88
|
+
.DS_Store
|
|
89
|
+
Thumbs.db
|
|
90
|
+
desktop.ini
|
|
91
|
+
|
|
92
|
+
# --- Local-only artifacts ---
|
|
93
|
+
.env
|
|
94
|
+
.env.*
|
|
95
|
+
*.log
|
|
96
|
+
*.tmp
|
|
97
|
+
.local/
|
|
98
|
+
.scratch/
|
|
99
|
+
|
|
100
|
+
# --- Outreach campaign artifacts (operational, not part of the open standard) ---
|
|
101
|
+
# Target lists, message drafts, tracking data, and the launch-approval record
|
|
102
|
+
# stay local. They are private to the maintainer; committing them would
|
|
103
|
+
# telegraph the campaign before launch and could embarrass listed projects.
|
|
104
|
+
outreach/
|
|
105
|
+
|
|
106
|
+
# Outreach dashboard SQLite mirror (RFC-0275). Derived from
|
|
107
|
+
# examples/lighthouses/outreach*.yaml via tools/scripts/refresh_outreach_db.py.
|
|
108
|
+
# Regenerated on demand by `make outreach-refresh`.
|
|
109
|
+
tools/outreach.db
|
|
110
|
+
tools/.outreach.db
|
|
111
|
+
|
|
112
|
+
# Local Claude Code settings (per-machine; permission rules, etc.). Not committed.
|
|
113
|
+
.claude/settings.json
|
|
114
|
+
.claude/settings.local.json
|
|
@@ -0,0 +1,127 @@
|
|
|
1
|
+
Metadata-Version: 2.5
|
|
2
|
+
Name: urml-edu-runtime
|
|
3
|
+
Version: 0.5.0
|
|
4
|
+
Summary: Educational-platform reference runtime for URML — VEX V5, LEGO Mindstorms/SPIKE, Thymio, Robotical Marty, Petoi Bittle / Nybble, zero ROS.
|
|
5
|
+
Project-URL: Homepage, https://github.com/urml-dev/URML
|
|
6
|
+
Project-URL: Repository, https://github.com/urml-dev/URML
|
|
7
|
+
Project-URL: Issues, https://github.com/urml-dev/URML/issues
|
|
8
|
+
Author: URML Maintainers
|
|
9
|
+
License: BUSL-1.1
|
|
10
|
+
Keywords: bittle,education,gopigo,gopigo3,lego,marty,microduck,mindstorms,nybble,opencat,petoi,pollen,robotical,robotics,runtime,spike,thymio,urml,vex
|
|
11
|
+
Classifier: Development Status :: 3 - Alpha
|
|
12
|
+
Classifier: Intended Audience :: Developers
|
|
13
|
+
Classifier: Intended Audience :: Education
|
|
14
|
+
Classifier: License :: Other/Proprietary License
|
|
15
|
+
Classifier: Operating System :: OS Independent
|
|
16
|
+
Classifier: Programming Language :: Python :: 3 :: Only
|
|
17
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
18
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
19
|
+
Classifier: Topic :: Education
|
|
20
|
+
Requires-Python: >=3.11
|
|
21
|
+
Requires-Dist: pydantic<3,>=2.6
|
|
22
|
+
Requires-Dist: pyyaml<7,>=6.0
|
|
23
|
+
Requires-Dist: urml-ros2-runtime>=0.5.0
|
|
24
|
+
Requires-Dist: urml-validator>=0.5.0
|
|
25
|
+
Provides-Extra: circuitpython
|
|
26
|
+
Requires-Dist: pyserial>=3.5; extra == 'circuitpython'
|
|
27
|
+
Provides-Extra: dev
|
|
28
|
+
Requires-Dist: mypy>=1.10; extra == 'dev'
|
|
29
|
+
Requires-Dist: pytest-cov>=5; extra == 'dev'
|
|
30
|
+
Requires-Dist: pytest>=8; extra == 'dev'
|
|
31
|
+
Requires-Dist: ruff>=0.5; extra == 'dev'
|
|
32
|
+
Provides-Extra: gopigo
|
|
33
|
+
Requires-Dist: easygopigo3>=1.0; extra == 'gopigo'
|
|
34
|
+
Provides-Extra: lego
|
|
35
|
+
Requires-Dist: pybricksdev>=1.0; extra == 'lego'
|
|
36
|
+
Provides-Extra: marty
|
|
37
|
+
Requires-Dist: martypy>=3.6; extra == 'marty'
|
|
38
|
+
Provides-Extra: petoi
|
|
39
|
+
Requires-Dist: petoi-robot; extra == 'petoi'
|
|
40
|
+
Provides-Extra: thymio
|
|
41
|
+
Requires-Dist: tdmclient>=0.1.4; extra == 'thymio'
|
|
42
|
+
Provides-Extra: vex
|
|
43
|
+
Requires-Dist: pyvex>=0.5; extra == 'vex'
|
|
44
|
+
Description-Content-Type: text/markdown
|
|
45
|
+
|
|
46
|
+
<p align="center">
|
|
47
|
+
<a href="https://urml.dev"><img src="https://urml.dev/favicon.svg" alt="URML" width="72" height="72"></a>
|
|
48
|
+
</p>
|
|
49
|
+
|
|
50
|
+
<p align="center">
|
|
51
|
+
A small, opinionated, human-readable language for describing robot intent.
|
|
52
|
+
</p>
|
|
53
|
+
|
|
54
|
+
<p align="center">
|
|
55
|
+
<a href="https://urml.dev"><b>urml.dev</b></a>
|
|
56
|
+
</p>
|
|
57
|
+
|
|
58
|
+
---
|
|
59
|
+
|
|
60
|
+
# urml-edu-runtime
|
|
61
|
+
|
|
62
|
+
**Educational-platform reference runtime for URML** — `VexV5Adapter`, `LegoSpikeAdapter`, `ThymioAdapter`, `GoPiGo3Adapter`, `RoboticalMartyAdapter`, **zero ROS**.
|
|
63
|
+
|
|
64
|
+
The classroom/maker adoption flywheel (RFC-0011). VEX V5 brain (USB/serial via `pyvex`), LEGO SPIKE Prime / Mindstorms hub (BLE via `pybricksdev`), Thymio (Aseba TDM via `tdmclient`), Robotical Marty v1/v2 (USB-serial / socket via `martypy`, per maintainer engagement on [robotical/martypy#52](https://github.com/robotical/martypy/issues/52), 2026-05-25). Each platform's native SDK is imported lazily by its adapter. This module loads on every host without any `[vex]`/`[lego]`/`[thymio]`/`[marty]` extra. Built against the frozen substrate Protocol per [RFC-0014](../../docs/rfcs/0014-substrate-conformance.md). Mirrors `cobot-runtime`'s `_CobotBase` shape.
|
|
65
|
+
|
|
66
|
+
## Method coverage
|
|
67
|
+
|
|
68
|
+
| URML primitive | v0.1 |
|
|
69
|
+
|---|---|
|
|
70
|
+
| `move_to` / `hover` | write the configured firmware command (VEX `run_command` / LEGO `send_command` / Thymio `send_event`) |
|
|
71
|
+
| `drive` / `turn` (RFC-0630) | `GoPiGo3Adapter` only: odometric `drive_cm` / `turn_degrees` / `orbit` on a frameless buggy. The first substrate to implement the relative-motion surface |
|
|
72
|
+
| `grasp` / `release` | write the configured claw-servo command |
|
|
73
|
+
| `wait` | hold (success) |
|
|
74
|
+
| `measure` / `wait_for` | one telemetry read |
|
|
75
|
+
| `report` | structured record to a local sink (no cloud) |
|
|
76
|
+
| `scan` | documented not-supported result: no area-scan controller (a scan is waypoints plus a capture at each one) |
|
|
77
|
+
| `look_at` / `gesture` (RFC-0698) | `ReachyMiniAdapter` only: expressive gaze + gesture on the Hugging Face Reachy Mini (`ExpressionAdapter`, `social` profile). The first substrate to implement the expression surface |
|
|
78
|
+
|
|
79
|
+
`dock`, `detect`, `capture`, `speak`, `listen` return `not_supported_on_edu_platform`. The drone trio returns `not_applicable_edu`.
|
|
80
|
+
|
|
81
|
+
`ReachyMiniAdapter` is a standalone `ExpressionAdapter` (not an `_EduBase` nav robot): `look_at` orients the head/body (a 4x4 head matrix + body yaw through the SDK's `goto_target`), `gesture` plays a named move mapped in `ReachyConfig.gesture_moves`. The client surface is config-overridable and imported lazily; hardware validation pairs with a live Reachy Mini and is a follow-up.
|
|
82
|
+
|
|
83
|
+
## Spec gaps (RFC-0014 protocol)
|
|
84
|
+
|
|
85
|
+
Cross-references existing Drafts — **no new RFC**:
|
|
86
|
+
- LED/buzzer/button = digital-output → **RFC-0017** (already Draft from cobot-runtime).
|
|
87
|
+
- Non-mobile sensor/actuator-only node → **RFC-0018** (already Draft from embedded-runtime).
|
|
88
|
+
|
|
89
|
+
See [`SPEC-GAPS.md`](SPEC-GAPS.md).
|
|
90
|
+
|
|
91
|
+
## Install / use
|
|
92
|
+
|
|
93
|
+
```bash
|
|
94
|
+
pip install -e reference/edu-runtime[vex] # VEX V5 (pyvex)
|
|
95
|
+
pip install -e reference/edu-runtime[lego] # LEGO Pybricks (pybricksdev BLE)
|
|
96
|
+
pip install -e reference/edu-runtime[thymio] # Thymio (tdmclient)
|
|
97
|
+
pip install -e reference/edu-runtime[gopigo] # GoPiGo3 buggy (easygopigo3, relative drive/turn)
|
|
98
|
+
pip install -e reference/edu-runtime[marty] # Robotical Marty v1/v2 (martypy)
|
|
99
|
+
pip install -e reference/edu-runtime # Microduck (stdlib JSON-RPC, no extra)
|
|
100
|
+
```
|
|
101
|
+
|
|
102
|
+
```python
|
|
103
|
+
from urml_edu_runtime import VexV5Adapter, EduConfig
|
|
104
|
+
cfg = EduConfig(device="COM3",
|
|
105
|
+
location_to_command={"start_mat": "GO START", "home_mat": "GO HOME"})
|
|
106
|
+
with VexV5Adapter(cfg) as vex:
|
|
107
|
+
assert vex.send_navigation_goal(location="start_mat").success
|
|
108
|
+
```
|
|
109
|
+
|
|
110
|
+
## Status
|
|
111
|
+
|
|
112
|
+
**v0.1 (this release):**
|
|
113
|
+
- 4 adapters + `EduConfig` + `BRAND_ADAPTERS` registry. Hermetic suite green via fake-SDK injection (`pytest reference/edu-runtime/tests -q`).
|
|
114
|
+
- 4 manifest fixtures (VEX V5 clawbot, LEGO SPIKE driving base, Thymio classroom buggy, Robotical Marty v2) + 4 conformance fixtures under `conformance/fixtures/educational/`.
|
|
115
|
+
- Gated `.github/workflows/edu-integration.yml`: `edu-smoke` (real SDKs including `martypy`), `edu-arm64-build` (Jetson-class QEMU with SDKs absent), `edu-board-e2e` placeholder that `exit 1`s until a real board is wired (the marine/cobot HONESTY-NOTE precedent).
|
|
116
|
+
- The Marty adapter was added in direct response to the first engaged maintainer reply across URML's 31-thread Move #3–#6 outreach: NikTheGeek1 on [robotical/martypy#52](https://github.com/robotical/martypy/issues/52) (2026-05-25) confirmed URML should host the adapter externally, set v2 default transport to USB-serial / v1 to socket, and scoped BLE out as not supported by `martypy`.
|
|
117
|
+
|
|
118
|
+
## Core Commitment
|
|
119
|
+
|
|
120
|
+
Business Source License 1.1: free for non-production use, commercial license for production (see [`LICENSING.md`](../../LICENSING.md)). No vendor coupling, no cloud dependency. All vendor SDKs are optional extras imported lazily, never at module load.
|
|
121
|
+
|
|
122
|
+
## Related documents
|
|
123
|
+
|
|
124
|
+
- [`/reference/cobot-runtime/`](../cobot-runtime/) — the zero-ROS sibling whose `_CobotBase` shape this mirrors as `_EduBase`.
|
|
125
|
+
- [`/reference/embedded-runtime/`](../embedded-runtime/) — the micro:bit/Arduino serial-port sibling (different transport model).
|
|
126
|
+
- [`/spec/profiles/educational/`](../../spec/profiles/educational/) — the RFC-0011 profile this serves.
|
|
127
|
+
- [`/docs/rfcs/0017-digital-io-actuation.md`](../../docs/rfcs/0017-digital-io-actuation.md) · [`/docs/rfcs/0018-minimal-mcu-capability-subset.md`](../../docs/rfcs/0018-minimal-mcu-capability-subset.md) — the cross-referenced gaps.
|
|
@@ -0,0 +1,82 @@
|
|
|
1
|
+
<p align="center">
|
|
2
|
+
<a href="https://urml.dev"><img src="https://urml.dev/favicon.svg" alt="URML" width="72" height="72"></a>
|
|
3
|
+
</p>
|
|
4
|
+
|
|
5
|
+
<p align="center">
|
|
6
|
+
A small, opinionated, human-readable language for describing robot intent.
|
|
7
|
+
</p>
|
|
8
|
+
|
|
9
|
+
<p align="center">
|
|
10
|
+
<a href="https://urml.dev"><b>urml.dev</b></a>
|
|
11
|
+
</p>
|
|
12
|
+
|
|
13
|
+
---
|
|
14
|
+
|
|
15
|
+
# urml-edu-runtime
|
|
16
|
+
|
|
17
|
+
**Educational-platform reference runtime for URML** — `VexV5Adapter`, `LegoSpikeAdapter`, `ThymioAdapter`, `GoPiGo3Adapter`, `RoboticalMartyAdapter`, **zero ROS**.
|
|
18
|
+
|
|
19
|
+
The classroom/maker adoption flywheel (RFC-0011). VEX V5 brain (USB/serial via `pyvex`), LEGO SPIKE Prime / Mindstorms hub (BLE via `pybricksdev`), Thymio (Aseba TDM via `tdmclient`), Robotical Marty v1/v2 (USB-serial / socket via `martypy`, per maintainer engagement on [robotical/martypy#52](https://github.com/robotical/martypy/issues/52), 2026-05-25). Each platform's native SDK is imported lazily by its adapter. This module loads on every host without any `[vex]`/`[lego]`/`[thymio]`/`[marty]` extra. Built against the frozen substrate Protocol per [RFC-0014](../../docs/rfcs/0014-substrate-conformance.md). Mirrors `cobot-runtime`'s `_CobotBase` shape.
|
|
20
|
+
|
|
21
|
+
## Method coverage
|
|
22
|
+
|
|
23
|
+
| URML primitive | v0.1 |
|
|
24
|
+
|---|---|
|
|
25
|
+
| `move_to` / `hover` | write the configured firmware command (VEX `run_command` / LEGO `send_command` / Thymio `send_event`) |
|
|
26
|
+
| `drive` / `turn` (RFC-0630) | `GoPiGo3Adapter` only: odometric `drive_cm` / `turn_degrees` / `orbit` on a frameless buggy. The first substrate to implement the relative-motion surface |
|
|
27
|
+
| `grasp` / `release` | write the configured claw-servo command |
|
|
28
|
+
| `wait` | hold (success) |
|
|
29
|
+
| `measure` / `wait_for` | one telemetry read |
|
|
30
|
+
| `report` | structured record to a local sink (no cloud) |
|
|
31
|
+
| `scan` | documented not-supported result: no area-scan controller (a scan is waypoints plus a capture at each one) |
|
|
32
|
+
| `look_at` / `gesture` (RFC-0698) | `ReachyMiniAdapter` only: expressive gaze + gesture on the Hugging Face Reachy Mini (`ExpressionAdapter`, `social` profile). The first substrate to implement the expression surface |
|
|
33
|
+
|
|
34
|
+
`dock`, `detect`, `capture`, `speak`, `listen` return `not_supported_on_edu_platform`. The drone trio returns `not_applicable_edu`.
|
|
35
|
+
|
|
36
|
+
`ReachyMiniAdapter` is a standalone `ExpressionAdapter` (not an `_EduBase` nav robot): `look_at` orients the head/body (a 4x4 head matrix + body yaw through the SDK's `goto_target`), `gesture` plays a named move mapped in `ReachyConfig.gesture_moves`. The client surface is config-overridable and imported lazily; hardware validation pairs with a live Reachy Mini and is a follow-up.
|
|
37
|
+
|
|
38
|
+
## Spec gaps (RFC-0014 protocol)
|
|
39
|
+
|
|
40
|
+
Cross-references existing Drafts — **no new RFC**:
|
|
41
|
+
- LED/buzzer/button = digital-output → **RFC-0017** (already Draft from cobot-runtime).
|
|
42
|
+
- Non-mobile sensor/actuator-only node → **RFC-0018** (already Draft from embedded-runtime).
|
|
43
|
+
|
|
44
|
+
See [`SPEC-GAPS.md`](SPEC-GAPS.md).
|
|
45
|
+
|
|
46
|
+
## Install / use
|
|
47
|
+
|
|
48
|
+
```bash
|
|
49
|
+
pip install -e reference/edu-runtime[vex] # VEX V5 (pyvex)
|
|
50
|
+
pip install -e reference/edu-runtime[lego] # LEGO Pybricks (pybricksdev BLE)
|
|
51
|
+
pip install -e reference/edu-runtime[thymio] # Thymio (tdmclient)
|
|
52
|
+
pip install -e reference/edu-runtime[gopigo] # GoPiGo3 buggy (easygopigo3, relative drive/turn)
|
|
53
|
+
pip install -e reference/edu-runtime[marty] # Robotical Marty v1/v2 (martypy)
|
|
54
|
+
pip install -e reference/edu-runtime # Microduck (stdlib JSON-RPC, no extra)
|
|
55
|
+
```
|
|
56
|
+
|
|
57
|
+
```python
|
|
58
|
+
from urml_edu_runtime import VexV5Adapter, EduConfig
|
|
59
|
+
cfg = EduConfig(device="COM3",
|
|
60
|
+
location_to_command={"start_mat": "GO START", "home_mat": "GO HOME"})
|
|
61
|
+
with VexV5Adapter(cfg) as vex:
|
|
62
|
+
assert vex.send_navigation_goal(location="start_mat").success
|
|
63
|
+
```
|
|
64
|
+
|
|
65
|
+
## Status
|
|
66
|
+
|
|
67
|
+
**v0.1 (this release):**
|
|
68
|
+
- 4 adapters + `EduConfig` + `BRAND_ADAPTERS` registry. Hermetic suite green via fake-SDK injection (`pytest reference/edu-runtime/tests -q`).
|
|
69
|
+
- 4 manifest fixtures (VEX V5 clawbot, LEGO SPIKE driving base, Thymio classroom buggy, Robotical Marty v2) + 4 conformance fixtures under `conformance/fixtures/educational/`.
|
|
70
|
+
- Gated `.github/workflows/edu-integration.yml`: `edu-smoke` (real SDKs including `martypy`), `edu-arm64-build` (Jetson-class QEMU with SDKs absent), `edu-board-e2e` placeholder that `exit 1`s until a real board is wired (the marine/cobot HONESTY-NOTE precedent).
|
|
71
|
+
- The Marty adapter was added in direct response to the first engaged maintainer reply across URML's 31-thread Move #3–#6 outreach: NikTheGeek1 on [robotical/martypy#52](https://github.com/robotical/martypy/issues/52) (2026-05-25) confirmed URML should host the adapter externally, set v2 default transport to USB-serial / v1 to socket, and scoped BLE out as not supported by `martypy`.
|
|
72
|
+
|
|
73
|
+
## Core Commitment
|
|
74
|
+
|
|
75
|
+
Business Source License 1.1: free for non-production use, commercial license for production (see [`LICENSING.md`](../../LICENSING.md)). No vendor coupling, no cloud dependency. All vendor SDKs are optional extras imported lazily, never at module load.
|
|
76
|
+
|
|
77
|
+
## Related documents
|
|
78
|
+
|
|
79
|
+
- [`/reference/cobot-runtime/`](../cobot-runtime/) — the zero-ROS sibling whose `_CobotBase` shape this mirrors as `_EduBase`.
|
|
80
|
+
- [`/reference/embedded-runtime/`](../embedded-runtime/) — the micro:bit/Arduino serial-port sibling (different transport model).
|
|
81
|
+
- [`/spec/profiles/educational/`](../../spec/profiles/educational/) — the RFC-0011 profile this serves.
|
|
82
|
+
- [`/docs/rfcs/0017-digital-io-actuation.md`](../../docs/rfcs/0017-digital-io-actuation.md) · [`/docs/rfcs/0018-minimal-mcu-capability-subset.md`](../../docs/rfcs/0018-minimal-mcu-capability-subset.md) — the cross-referenced gaps.
|
|
@@ -0,0 +1,55 @@
|
|
|
1
|
+
<p align="center">
|
|
2
|
+
<a href="https://urml.dev"><img src="https://urml.dev/favicon.svg" alt="URML" width="72" height="72"></a>
|
|
3
|
+
</p>
|
|
4
|
+
|
|
5
|
+
<p align="center">
|
|
6
|
+
A small, opinionated, human-readable language for describing robot intent.
|
|
7
|
+
</p>
|
|
8
|
+
|
|
9
|
+
<p align="center">
|
|
10
|
+
<a href="https://urml.dev"><b>urml.dev</b></a>
|
|
11
|
+
</p>
|
|
12
|
+
|
|
13
|
+
---
|
|
14
|
+
|
|
15
|
+
# SPEC-GAPS — urml-edu-runtime
|
|
16
|
+
|
|
17
|
+
Per the spec-gap protocol (RFC-0014): built strictly against the
|
|
18
|
+
frozen substrate Protocol. Anything an educational platform needs that
|
|
19
|
+
URML cannot express is recorded here and cross-referenced — never a
|
|
20
|
+
silent primitive/schema change.
|
|
21
|
+
|
|
22
|
+
## Cross-references to existing Draft RFCs (no NEW RFC)
|
|
23
|
+
|
|
24
|
+
The three educational platforms surface only gaps that prior runtimes
|
|
25
|
+
already filed:
|
|
26
|
+
|
|
27
|
+
- **RFC-0017 — digital-I/O actuation** (already Draft from
|
|
28
|
+
cobot-runtime). The VEX V5 brain LED, the LEGO hub status light + the
|
|
29
|
+
LEGO speaker beep, the Thymio LED ring + buzzer + buttons are all
|
|
30
|
+
the same "write a named declared digital line" gap. Cross-referenced
|
|
31
|
+
here; not duplicated.
|
|
32
|
+
|
|
33
|
+
- **RFC-0018 — minimal-MCU capability subset** (already Draft from
|
|
34
|
+
embedded-runtime). A VEX V5 brain on its own (no motors), a LEGO
|
|
35
|
+
hub used only for sensor reads, a fixed Thymio used as a
|
|
36
|
+
push-button stand are all the same "non-mobile sensor/actuator
|
|
37
|
+
node, no honest mobility/perception block" gap. Cross-referenced;
|
|
38
|
+
not duplicated.
|
|
39
|
+
|
|
40
|
+
## Composable (no gap, documented)
|
|
41
|
+
|
|
42
|
+
- A two-motor VEX clawbot / a LEGO driving base / a moving Thymio is
|
|
43
|
+
honestly `differential` drive (RFC-0009's enum value). `move_to`
|
|
44
|
+
resolves via config-side `EduConfig.location_to_command` (the
|
|
45
|
+
`cobot_adapter.yaml` precedent) — no URML surface change.
|
|
46
|
+
- `grasp`/`release` for the VEX claw / LEGO claw / Thymio gripper map
|
|
47
|
+
through `EduConfig.manipulation_commands` to a single firmware
|
|
48
|
+
command. Honest for a buggy-with-claw; absent ⇒ an unsuccessful
|
|
49
|
+
result with a clear reason, not a gap.
|
|
50
|
+
|
|
51
|
+
## Scope note
|
|
52
|
+
|
|
53
|
+
Serves the RFC-0011 educational profile. `program.profile` is an
|
|
54
|
+
open `Identifier`, so `educational` validates with **no** schema
|
|
55
|
+
change, and RFC-0011 is documented-not-enforced in v0.1.
|
|
@@ -0,0 +1,127 @@
|
|
|
1
|
+
[build-system]
|
|
2
|
+
requires = ["hatchling>=1.27"]
|
|
3
|
+
build-backend = "hatchling.build"
|
|
4
|
+
|
|
5
|
+
[project]
|
|
6
|
+
name = "urml-edu-runtime"
|
|
7
|
+
version = "0.5.0"
|
|
8
|
+
description = "Educational-platform reference runtime for URML — VEX V5, LEGO Mindstorms/SPIKE, Thymio, Robotical Marty, Petoi Bittle / Nybble, zero ROS."
|
|
9
|
+
readme = "README.md"
|
|
10
|
+
license = { text = "BUSL-1.1" }
|
|
11
|
+
requires-python = ">=3.11"
|
|
12
|
+
authors = [{ name = "URML Maintainers" }]
|
|
13
|
+
keywords = ["robotics", "education", "vex", "lego", "mindstorms", "spike", "thymio", "gopigo", "gopigo3", "marty", "robotical", "petoi", "bittle", "nybble", "opencat", "microduck", "pollen", "urml", "runtime"]
|
|
14
|
+
classifiers = [
|
|
15
|
+
"Development Status :: 3 - Alpha",
|
|
16
|
+
"Intended Audience :: Developers",
|
|
17
|
+
"Intended Audience :: Education",
|
|
18
|
+
"License :: Other/Proprietary License",
|
|
19
|
+
"Operating System :: OS Independent",
|
|
20
|
+
"Programming Language :: Python :: 3 :: Only",
|
|
21
|
+
"Programming Language :: Python :: 3.11",
|
|
22
|
+
"Programming Language :: Python :: 3.12",
|
|
23
|
+
"Topic :: Education",
|
|
24
|
+
]
|
|
25
|
+
dependencies = [
|
|
26
|
+
"pydantic>=2.6,<3",
|
|
27
|
+
"PyYAML>=6.0,<7",
|
|
28
|
+
"urml-validator>=0.5.0",
|
|
29
|
+
"urml-ros2-runtime>=0.5.0",
|
|
30
|
+
]
|
|
31
|
+
|
|
32
|
+
[project.optional-dependencies]
|
|
33
|
+
# Each educational platform has its own native host-side Python SDK:
|
|
34
|
+
# VEX V5 (the `vex` module / pyvex community wrappers), LEGO Pybricks
|
|
35
|
+
# (the `pybricksdev` BLE host-side client), and Thymio (the Aseba
|
|
36
|
+
# `tdmclient` Thymio Device Manager Python client). All zero-ROS, all
|
|
37
|
+
# imported lazily by their respective adapter so this module loads on
|
|
38
|
+
# every host without any extra. Serves RFC-0011 educational (the
|
|
39
|
+
# adoption flywheel for the classroom/maker community).
|
|
40
|
+
vex = [
|
|
41
|
+
"pyvex>=0.5",
|
|
42
|
+
]
|
|
43
|
+
lego = [
|
|
44
|
+
"pybricksdev>=1.0",
|
|
45
|
+
]
|
|
46
|
+
thymio = [
|
|
47
|
+
"tdmclient>=0.1.4",
|
|
48
|
+
]
|
|
49
|
+
# Robotical Marty (Edinburgh, UK) via the host-side martypy SDK. v3.6.6
|
|
50
|
+
# is the last published release at time of writing per robotical/martypy
|
|
51
|
+
# (Apache-2.0). Maintainer engagement on robotical/martypy#52 (2026-05-25)
|
|
52
|
+
# confirmed v2 default transport is USB-serial, v1 is socket; BLE is not
|
|
53
|
+
# supported by martypy and is out of scope for this adapter.
|
|
54
|
+
marty = [
|
|
55
|
+
"martypy>=3.6",
|
|
56
|
+
]
|
|
57
|
+
# Petoi Bittle X / Bittle / Nybble Q (Shenzhen, CN) via the OpenCat
|
|
58
|
+
# skill-library command surface. The canonical Python package was
|
|
59
|
+
# confirmed by the OpenCat maintainer Dr. Rongzhong Li on
|
|
60
|
+
# PetoiCamp/OpenCat-Quadruped-Robot#113 (2026-07-15): Petoi unified the
|
|
61
|
+
# Mind+ and desktop-app libraries into PetoiRobot
|
|
62
|
+
# (https://github.com/PetoiCamp/DesktopAppRelease/tree/main/pyUI/PetoiRobot,
|
|
63
|
+
# pip name 'petoi-robot'). Its command surface is functional
|
|
64
|
+
# (sendCmdStr / sendSkillStr) and its raw sensor reads are readAnalogValue /
|
|
65
|
+
# readDigitalValue / readUltrasonicDistance; the adapter is wrapper-agnostic,
|
|
66
|
+
# so a URML-side unified wrapper over those is also fine (maintainer-blessed).
|
|
67
|
+
petoi = [
|
|
68
|
+
"petoi-robot",
|
|
69
|
+
]
|
|
70
|
+
# Adafruit CircuitPython (New York, US) via a host-side comms bridge. Per
|
|
71
|
+
# @dhalbert on adafruit/circuitpython#11035 (engaged 2026-05-28): the
|
|
72
|
+
# device-side helper library's home is the Adafruit CircuitPython
|
|
73
|
+
# Community Bundle (not core), and the integration is a host-side comms
|
|
74
|
+
# program over serial / REPL (not USB-MSC drag-drop, which is not
|
|
75
|
+
# universal). 'circuitpython_host' is a placeholder for that host-side
|
|
76
|
+
# wrapper, pending hardware validation; pyserial is the realistic serial
|
|
77
|
+
# transport. The adapter only requires *some* Python object exposing
|
|
78
|
+
# CircuitPython skill methods or a generic send_command(token, *args).
|
|
79
|
+
circuitpython = [
|
|
80
|
+
"pyserial>=3.5",
|
|
81
|
+
]
|
|
82
|
+
# Dexter Industries / Modular Robotics GoPiGo3 (Boulder, CO, US), the
|
|
83
|
+
# canonical frameless classroom buggy. `easygopigo3` is the official
|
|
84
|
+
# Raspberry-Pi-side Python API (`drive_cm` / `turn_degrees` / `orbit`),
|
|
85
|
+
# talking to the GoPiGo3 hat over SPI. It is the first substrate to
|
|
86
|
+
# implement URML's relative-motion surface (RFC-0630).
|
|
87
|
+
gopigo = [
|
|
88
|
+
"easygopigo3>=1.0",
|
|
89
|
+
]
|
|
90
|
+
dev = [
|
|
91
|
+
"pytest>=8",
|
|
92
|
+
"pytest-cov>=5",
|
|
93
|
+
"ruff>=0.5",
|
|
94
|
+
"mypy>=1.10",
|
|
95
|
+
]
|
|
96
|
+
|
|
97
|
+
[project.urls]
|
|
98
|
+
Homepage = "https://github.com/urml-dev/URML"
|
|
99
|
+
Repository = "https://github.com/urml-dev/URML"
|
|
100
|
+
Issues = "https://github.com/urml-dev/URML/issues"
|
|
101
|
+
|
|
102
|
+
[tool.hatch.build.targets.wheel]
|
|
103
|
+
packages = ["src/urml_edu_runtime"]
|
|
104
|
+
|
|
105
|
+
[tool.ruff]
|
|
106
|
+
line-length = 120
|
|
107
|
+
target-version = "py311"
|
|
108
|
+
src = ["src", "tests"]
|
|
109
|
+
|
|
110
|
+
[tool.ruff.lint]
|
|
111
|
+
select = ["E", "F", "W", "I", "B", "UP", "N", "ANN", "RUF"]
|
|
112
|
+
ignore = ["ANN401"]
|
|
113
|
+
|
|
114
|
+
[tool.ruff.lint.per-file-ignores]
|
|
115
|
+
"tests/*" = ["ANN"]
|
|
116
|
+
|
|
117
|
+
[tool.mypy]
|
|
118
|
+
strict = true
|
|
119
|
+
python_version = "3.11"
|
|
120
|
+
plugins = ["pydantic.mypy"]
|
|
121
|
+
mypy_path = "src"
|
|
122
|
+
packages = ["urml_edu_runtime"]
|
|
123
|
+
|
|
124
|
+
[tool.pytest.ini_options]
|
|
125
|
+
minversion = "8.0"
|
|
126
|
+
testpaths = ["tests"]
|
|
127
|
+
addopts = ["-q", "--strict-markers"]
|