한국어 | ENGLISH

Tutorial Robotics

An action-first bilingual course for readers who know basic Python and are new to robotics. Start with one lesson, inspect the actual state and images, explain the result, compare one variable, then finish it. English · 한국어

First start — no Python or pal assumed

For command explanations, fresh terminals, saved-result replay and feedback, use the English reader guide or 한국어 실행 안내. The redesign verification record separates local evidence from pending host checks.

During guided learning, Codex and Claude Code open the current GitHub lesson in your language and reuse that tutorial tab as you advance. Keep the conversation/terminal beside the theory page; simulation replay uses a separate viewer. Without browser control, the agent provides the exact link for manual opening. Start with 한국어 T00 or English T00.

The first lesson uses your conversation language. Each curriculum page has a top-right 한국어 | ENGLISH link to the same page in the other language. After you switch, both native Next lesson links and agent-guided continuation preserve that selection. The agent checks the current tutorial tab before navigating and remembers the last observed language for reopening.

git clone https://github.com/terryum/tutorial-robotics.git
cd tutorial-robotics
sh bootstrap.sh --plan

The plan checks OS, architecture, Python, uv and free disk without creating learner state. It prints exactly what would be installed, why, where and which commands would run. Supported Core hosts are macOS arm64 and Linux x86_64.

After reading that plan:

sh bootstrap.sh --apply
source .venv/bin/activate
pal host detect --json
pal setup verify --profile core --json
pal course init --through core --json
pal course next --json
pal lesson run T00 --headless --output-dir .local/runs/core-00/first --json
pal lesson check T00 --run-dir .local/runs/core-00/first --json

Read T00 or 한국어 T00 for the explanation, source inspection, review and finish steps. Stop after T00. An execution does not complete a lesson. course init preserves earlier completion records; use a fresh run directory for reruns.

Bootstrap reuses the Python 3.12 environment and existing lockfile. If needed, uv is installed into this checkout's .local/bin and managed Python into .local/python. It does not change system Python. ROS, GPU, learning frameworks, Isaac and large pretrained models are prepared only when their lesson needs them. System packages, drivers, firmware and physical actions retain separate approval requirements.

Four copyable prompts

Intent	한국어	English
First start	처음 시작할게. bootstrap 계획을 보여주고 필요한 Core 환경을 준비한 뒤 T00 하나를 실행·검사·설명해줘.	Show the bootstrap plan, prepare the necessary Core environment, then run, inspect and explain only T00.
Next lesson	다음 단계 실행해줘.	Run the next eligible lesson only.
Rerun	다시 실행해줘.	Rerun the current lesson with a fresh execution record.
Feedback	[개선점] 여기에 개선할 내용을 적습니다.	[개선점] Describe the improvement here.

“[개선점] 지금 바로 고쳐줘 …” stores urgent feedback, safely interrupts the software experiment, fixes/reverifies it and resumes the same lesson. Other feedback accumulates and is applied automatically after execution/explanation. Feedback received before starting another lesson belongs to the previous lesson.

Codex and Claude Code follow the same workflow. Both read the same local feedback queue. You can inspect it directly:

pal feedback list --json
pal feedback add "[개선점] Explain the plot units" --lesson T00 --json

Your local progress

Each clone starts with no completed lessons. Your completed lessons and completion times are saved in .local/progress.json, your last lesson and phase in .local/session.json, and your feedback in .local/feedback.json. Execution and review evidence stays in .local/runs/. Git ignores .local/; ordinary commits, pushes and pulls do not share or overwrite this state.

Return to the same checkout, activate .venv, and run:

pal course list --json    # All selected lessons, including completed ones
pal course status --json  # Remaining lessons and any needing review
pal course next --json    # Next eligible lesson

pal course init preserves completion records. A lesson becomes complete only after the run/check/review/finish workflow succeeds. Keep .local/ and its run artifacts to resume later; a fresh clone has its own progress. See the English reader guide or 한국어 실행 안내.

Evidence and course scope

The catalog retains 49 IDs and legacy aliases: 25 Core lessons, 15 Simulation lessons, one offline runtime lesson and eight device lessons. Real MuJoCo models, measured contact/control, NumPy PPO and BC replace the earlier generic numerical fixtures. ACT and the VLA mock remain explicitly contract lessons.

Mac verification covers Core plus the generated deployment candidate and offline sink. The other 14 software lessons require actual Ubuntu/ROS/GPU/Isaac environments and remain reader_test_required until run there. The eight device lessons remain scaffolded; no simulation result authorizes physical motion. See WS1 preparation and verification.

Read the measured verification report and reviewed figures for exact results, source revision and remaining external checks.

lesson check --run-dir verifies artifact identity/hashes, finite numerical traces and nonblank required images. lesson review records a separate one-variable comparison and explanation. lesson finish rechecks readiness, evidence and unresolved feedback before recording completion. Short training verification never claims a solved policy.

All learner progress, feedback, datasets, checkpoints and private run details stay in ignored .local/. state/PUBLISHING.md holds only shared publication evidence. A separate PAL_LOCAL_DIR keeps developer verification independent of the user's learning state.

Development verification

uv sync --locked --python 3.12
source .venv/bin/activate
pytest
ruff check .
mypy src
python scripts/validate_repository.py
python scripts/validate_release.py
python scripts/verify_course.py --profile core --local-dir .local/development/course

Fetch the public model bundles listed in T02 before full Core integration. Unit tests check state preservation, corrupt evidence rejection and unavailable capabilities; integration commands exercise real models and policies. Missing capabilities never become completed lessons.

The metadata generator preserves authored lesson bodies, entrypoints and tests. Refresh with python scripts/generate_curriculum.py. The course is Apache-2.0; public vendor assets retain their individual licenses and exact file hashes in assets/model-lock.json. Never edit vendor checkouts.

Complete lesson contents

#	ID / alias	English	한국어
1	core-00 / T00	Repository bootstrap and host audit	저장소 시작과 호스트 점검
2	core-01 / T01	Deterministic pendulum state and timestep	결정론적 진자 상태와 시간 간격
3	core-02 / T02	Pinned public robot sources	공개 로봇 소스 고정과 자산 매니페스트
4	core-03 / T03	Multi-model inspection and asset validation	다중 모델 검사와 자산 검증
5	core-04 / T04	Unified viewer and deterministic rendering	통합 뷰어와 결정론적 렌더링
6	core-fr3-01 / T05	FR3 model anatomy	FR3 모델 구조
7	core-fr3-02 / T06	FR3 joint-space PD control	FR3 관절 공간 PD 제어
8	core-fr3-03 / T07	FR3 gravity compensation and feedforward	FR3 중력 보상과 피드포워드
9	core-fr3-04 / T08	FR3 kinematics, Jacobian, and inverse kinematics	FR3 기구학, 자코비안과 역기구학
10	core-fr3-05 / T09	FR3 operational-space control	FR3 작업 공간 제어
11	core-fr3-06 / T10	FR3 contact and friction laboratory	FR3 접촉과 마찰 실험실
12	core-rl-01 / T23	Minimal continuous-action PPO	최소 연속 행동 PPO
13	core-fr3-07 / T22	FR3 reach environment without ROS	ROS 없는 FR3 도달 환경
14	core-fr3-08 / T24	PPO on FR3 reach	FR3 도달 과제 PPO
15	core-enlight-01 / T08A	Enlight description, frames, and kinematics	Enlight 모델, 좌표계와 기구학
16	core-enlight-02 / T10A	Enlight MuJoCo draft and cross-format validation	Enlight MuJoCo 초안과 형식 간 검증
17	core-wuji-01 / T14	Wuji Hand 2 Beta 2 joints, poses, and synergies	Wuji Hand 2 Beta 2 관절, 자세와 시너지
18	core-wuji-02 / T15	Wuji virtual tactile observation	Wuji 가상 촉각 관측
19	core-dexterity-01 / T16	Wuji and Sharpa model comparison	Wuji와 Sharpa 모델 비교
20	core-data-01 / T28	Episode dataset from MuJoCo	MuJoCo 에피소드 데이터셋
21	core-dexterity-02 / T16A	Hand retargeting and demonstration recording	손 리타게팅과 시연 기록
22	core-g1-01 / T25	Unitree G1 playback and motion data	Unitree G1 재생과 모션 데이터
23	core-il-01 / T29	Behavioral cloning baseline	행동 복제 기준선
24	core-aloha-01 / T30	ALOHA simulation and ACT contract	ALOHA 시뮬레이션과 ACT 계약
25	core-vla-01 / T32A	VLA protocol and mock policy client	VLA 프로토콜과 모의 정책 클라이언트
26	sim-ros-01 / T17	ROS 2 topics, QoS, services, actions, and TF	ROS 2 토픽, QoS, 서비스, 액션과 TF
27	sim-ros-02 / T19	MuJoCo to ROS 2 bridge	MuJoCo–ROS 2 브리지
28	sim-ros-03 / T20	Rosbag episode recording and deterministic replay	rosbag 에피소드 기록과 결정론적 재생
29	sim-ros-04 / T21	Common embodiment API for simulation and ROS 2	시뮬레이션과 ROS 2 공통 embodiment API
30	sim-g1-01 / T26	Unitree G1 GPU PPO and motion imitation	Unitree G1 GPU PPO와 모션 모방
31	sim-wuji-01 / T27	Wuji in-hand PPO on GPU	Wuji GPU 손안 조작 PPO
32	sim-vla-01 / T32C	SmolVLA fine-tuning and policy server	SmolVLA 미세조정과 정책 서버
33	sim-vla-02 / T32D	Optional remote VLA inference	선택형 원격 VLA 추론
34	sim-isaac-01 / T33	Import public robot assets into Isaac Sim	Isaac Sim 공개 로봇 자산 가져오기
35	sim-isaac-02 / T34	Isaac camera, lighting, and synthetic data	Isaac 카메라, 조명과 합성 데이터
36	sim-cross-01 / T35	MuJoCo to Isaac sim-to-sim validation	MuJoCo–Isaac sim-to-sim 검증
37	sim-deploy-01 / T35A	Candidate deployment bundle and promotion gate	후보 배포 번들과 승격 게이트
38	sim-enlight-01 / T18	Enlight ROS 2 fake hardware	Enlight ROS 2 가상 하드웨어
39	sim-enlight-02 / T41A	Enlight contact-task simulation and candidate bundle	Enlight 접촉 과제 시뮬레이션과 후보 번들
40	sim-wuji-02 / T42A	Wuji dexterity candidate bundle	Wuji 정교 조작 후보 번들
41	hw-common-01 / T35B	Runtime bootstrap, offline replay, and command sink	런타임 시작, 오프라인 재생과 명령 차단
42	hw-common-02 / T36	Real-hardware read-only integration gate	실물 하드웨어 읽기 전용 통합 게이트
43	hw-fr3-01 /	FR3 read-only state, shadow, and approved low-risk motion	FR3 읽기 전용 상태, 섀도와 승인된 저위험 동작
44	hw-wuji-01 / T38	Wuji Beta 2 read-only adapter and tactile calibration	Wuji Beta 2 읽기 전용 어댑터와 촉각 보정
45	hw-wuji-02 / T42B	Wuji shadow and gated real evaluation	Wuji 섀도와 승인 기반 실물 평가
46	hw-enlight-01 / T37	Enlight read-only adapter and low-risk validation	Enlight 읽기 전용 어댑터와 저위험 검증
47	hw-enlight-02 / T37A	Enlight system identification and MuJoCo calibration	Enlight 시스템 식별과 MuJoCo 보정
48	hw-enlight-03 / T41B	Enlight contact-task shadow and gated evaluation	Enlight 접촉 과제 섀도와 승인 기반 평가
49	hw-enlight-wuji-01 / T38A	Enlight and Wuji integrated read-only validation	Enlight와 Wuji 통합 읽기 전용 검증