Skip to content

reference(digital-twin): Digital Twin handbook with a CI-checked quick start - #95

Draft
BotshareAI wants to merge 3 commits into
docs/grocery-demonstratorfrom
docs/digital-twin-handbook
Draft

BotshareAI wants to merge 3 commits into
docs/grocery-demonstratorfrom
docs/digital-twin-handbook

Conversation

@BotshareAI

@BotshareAI BotshareAI commented Nov 20, 2026 •

Copy link
Copy Markdown
Contributor

Digital Twin handbook for OpenAMRobot 2.0 (Digital Twin release candidate, gate RC-F). Stacked on #93 (base docs/grocery-demonstrator 0d6596e, which carries #91). Primary audience: developers and integrators, including engineers who are not robotics specialists.

Work package

DT-RC worker S6: Digital Twin handbook in openamrobot-docs (gate RC-F, criteria F1, F6, F7, F8 and the documentation verification).

What changes

No BOM, interface definition or configuration register is copied; pages link the owning files at commits. The direct /cmd_vel use of the #106 benchmark is stated as isolated physics benchmarking only; whole-robot acceptance uses the approved command chain. The Gazebo lift benchmark row is marked under investigation.

Integration Gate

Tests

  • python3 -m unittest scripts/tests/test_digital_twin_quickstart.py: 10 tests OK. They fail on revert: dropping pipefail or -e in the generated header fails test_failure_inside_a_pipeline_fails_the_script / test_failing_command_fails_the_script; removing the markers fails test_install_page_has_the_quick_start.
  • Quick start in CI (the page text, executed):
    • run 44798734068 on 3f9c879: FAIL in block 3, gz: command not found (ROS sourced before the vendor packages were installed). Fixed in the page.
    • run 44800007695 on 34bc4ae: blocks 1 to 5 PASS (108 tests, 0 failures), block 6 reached the running twin (/sil/drive/status, /clock, all /sil/* device topics), then hung: a background job ignores SIGINT. Cancelled at the 180 min limit. Fixed (SIGTERM and a bounded wait).
    • run 44837107117 on ed34b86: success, all 7 blocks passed: ROS 2 Jazzy, pinned workspace (six commits), Gazebo 8.15.0, colcon build of 17 packages, 8 static scene tests (108 test cases, 0 failures), five vcan buses (MTU 16 and 72), headless firmware_sil twin with device topics, scn14_drive_fast PASS.
  • Documentation workflow (strict build with the social plugin, lychee): run 44837107187 success. Repository quality: 44837107768 success.
  • Local (Python 3.13, pinned requirements, social plugin disabled because the sandbox blocks fonts.google.com): mkdocs build --strict rc 0; internal link and anchor check of the twin pages and the three redirected pages: 2271 links, 0 broken; scripts/check_docs.sh passed; scripts/check_roadmap.py passed; python3 -m unittest discover -s scripts/tests OK; tests/test_live_site.py OK.
  • openAMRobot/.github 87c8486: check_public_extract.py --changed-files 0 findings; check_decisions.py --changed-files 0 contradictions.

Evidence

Base SHA: 0d6596e (docs/grocery-demonstrator)
Head SHA: ed34b86

Commands:

python3 -m unittest scripts/tests/test_digital_twin_quickstart.py
python3 scripts/digital_twin_quickstart.py --write quickstart.sh && bash quickstart.sh   # what the CI job runs
mkdocs build --strict
bash scripts/check_docs.sh
python3 scripts/check_roadmap.py
python3 -m unittest discover -s scripts/tests
python3 <.github>/tools/check_public_extract.py --root . --repository openamrobot-docs --changed-files changed.txt
python3 <.github>/tools/check_decisions.py --decisions <.github>/decisions.yaml --maintainers <.github>/maintainers.yaml --root . --repository openamrobot-docs --changed-files changed.txt
  • Twin pin of the quick start: openamr-upperbody-sw integration/baseline1 196dd3fe64900ba4a12124c9ee20e0cfaafa1651; platform-sw fb25be1, interfaces 50ed777, openarm pins read from that commit.

Not verified

  • Desktop and GUI commands (RViz launch, run_scenario.py, Control Room, operator UI views, Isaac kit, MuJoCo viewer): need a desktop or a GPU; covered by the desktop acceptance checklist on the install page, not run.
  • The Baseline 1 mission command and the gh workflow run reproduction command: taken from baseline1-acceptance.yml; not run for this page (the mission runs in that workflow).
  • The benchmark reproduction commands: as sim-benchmark.yml runs them; not run for this page.
  • The dev container: not checked.
  • The quick start pins 196dd3f, not the final Digital Twin RC pins; UB_SHA moves to the strict run's commit once that verdict exists. No strict acceptance run exists yet.
  • Figures quoted from other records (fidelity, register, benchmark, UI run, diagnostic leg) were read from those records and run summaries, not re-measured.

AI disclosure

Claude Code (Claude Opus 5.5) wrote the pages, the extractor, its tests, the workflow and the STATE/CHANGELOG lines, and checked the cited runs, PRs and files through the GitHub API. Safety path: none touched.

Publication check

No private person, customer or partner named; the application name is Use_Case_1 where needed; no internal document links, prices, contact data or credentials. Every page carries a simulation-not-hardware warning. No em dashes.

Intellectual property and provenance

  • Every commit is signed off under the OpenAMRobot DCO.
  • Contributor Agreement and authorizations: maintainer to confirm.
  • Third-party and material AI-assisted content is identified.
  • No unauthorized confidential, personal, proprietary, credential, or export-controlled information is included.

Draft until the docs owner writes adopt, adapt or reject. Desktop acceptance: one reviewer runs steps 1 to 6 of the checklist, a second repeats them on another machine, a third runs steps 7 and 8 on an NVIDIA GPU machine.

https://claude.ai/code/session_01DZnPEMPDB6f8AohTTfGWkF


Generated by Claude Code

BotshareAI and others added 3 commits November 20, 2026 19:04
…ess quick start

The digital-twin-quickstart workflow extracts every bash block marked
quickstart:headless from install-and-run.md and runs them in page order
with set -eo pipefail; a page with no marked block fails.

Signed-off-by: Alex Reznichenko <[email protected]>
Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_01DZnPEMPDB6f8AohTTfGWkF
…o the published sources

Landing page as the single entry point; new pages for architecture and
data flow, physics model, electronics and CAN, firmware, ROS 2 graph,
simulators, operator UI and Control Room, scenarios, faults, evidence
and limits with release and versioning. Status and architecture brought
to 20 Nov 2026; obsolete #70 commands and pending demo-document notes
replaced by links; simulation framework pages point to the handbook.
Mermaid fences enabled. Quick start: source ROS 2 after the installs so
gz is on the path (found by the quick-start job, run 44798734068).

Signed-off-by: Alex Reznichenko <[email protected]>
Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_01DZnPEMPDB6f8AohTTfGWkF
…rk, Isaac kit, UI twin run

Simulators: lock update #104, parity 2922 checks with 0 failures, the 21
declared deviations of upperbody-sw #96, the #106 benchmark (12 of 21
metrics within tolerance, causes, Gazebo lift row under investigation),
reproduction commands, and that direct /cmd_vel is for the isolated
physics benchmark only; Isaac GPU run kit #107. Operator UI: #62 twin
run 44806541459 (browser 8/8, probe 11/11). Evidence: diagnostic leg
44808492353; strict acceptance not run yet. Quick start: stop the
background launch with SIGTERM and a bounded wait (SIGINT is ignored by
a background job; run 44800007695 hung there after blocks 1 to 5 passed).

Signed-off-by: Alex Reznichenko <[email protected]>
Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_01DZnPEMPDB6f8AohTTfGWkF
@cla-assistant

cla-assistant Bot commented Nov 22, 2026 •

Copy link
Copy Markdown

CLA assistant check
All committers have signed the CLA.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant