設定
roboloomの設定は,機体ごとの設定file config.yaml と,そこから参照するnode YAMLでできています.このページはfileの配置,最上位のkey,単位,継承,起動option,実験fileをまとめます.nodeの種類ごとのkeyは次のページにあります.機能の状態label(実機検証済み,模擬のみ,開発中,設計のみ)は 状態label を参照してください.
| ページ | 中身 |
|---|---|
| follower | followers: の共通のkey,機種ごとのkey,脱力したときの性質,制御周期 |
| 入力 | inputs:(leader arm,Pika Sense)と trackers: |
| controller | controllers: の joint,parts,pose_ik,policy,力の逆送と推定器 |
| 方策のcontroller | type: policy のkey |
| sensor | sensors: のkey,画像の保存形式,sensorの選択 |
| recorder と session | recorder:,品質の警告,動画のcodec,session: |
| 制御則 | control: の制御則ごとのkey,limits,home |
fileの配置
roboloom init rakuda2 が .roboloom/rakuda2/ に設定・node・calibration YAMLを作ります.既存のdirectoryは上書きしません.新しい版のtemplateに追いつかせるときは roboloom init rakuda2 --update を使います(projectにないfileを足し,触っていないfileを置き換え,編集したfileにはtemplateだけにあるkeyとoptionを一覧にします.CLI).
.roboloom/
.gitignore # 生data・log・datasetを除外する(生成)
rakuda2/
config.yaml # 設定(機体ごとに1つ)
mock.yaml # SET_ の代用値(模擬のdeviceのときだけ使う)
README.md # 測定の手順
nodes/ # node YAML(機能ごとに分ける)
calibration/ # 校正,重力model,可動域,調整値
poses/<follower>/ # 保存した姿勢(roboloom capture-pose)
logs/ # log(Gitの外)
datasets/ # 既定の保存先(Gitの外)
configs/roboloom/<name>.yaml # 実験file(projectのroot)
設定は機体ごとに1つ(config.yaml)で,機能の組み合わせは 起動option で選びます.機体名 rakuda2 は .roboloom/rakuda2/config.yaml を指します..roboloom/ の下に機体が1台だけなら省略でき,file pathでも指定できます.
設定YAML
repo_id: local/rakuda2
output: datasets/rakuda2
dataset_fps: 15
inputs:
leader: nodes/leader.yaml
controllers:
controller: nodes/controller.yaml
followers:
follower: nodes/follower.yaml
sensors:
audio: {file: nodes/audio.yaml, default: false}
camera: nodes/camera.yaml
recorder: nodes/recorder.yaml
session: nodes/session.yaml
options:
# 次の節を参照
node YAMLのpathと output は設定fileのdirectoryが基準です.optionを有効にしない場合,上の保存先は .roboloom/rakuda2/datasets/rakuda2 です.robotの名前は設定のdirectory名(.roboloom/rakuda2/ なら rakuda2)で,datasetの robot_type にも使います.
最上位のkey
最上位に書けるkeyは次の表だけです.それ以外のkeyは読み込み時に拒否します.
| key | 型 | 既定値 | 単位 | 説明 |
|---|---|---|---|---|
repo_id |
文字列 | 必須 | — | datasetの namespace/name.有効なoptionの dataset が末尾に付く |
output |
path | 必須 | — | datasetの保存先.optionの dataset が末尾に付く |
dataset_fps |
数値 | 必須 | Hz | datasetの行の周期.各followerの control_hz 以下 |
mode |
文字列 | hardware |
— | hardware か mock.CLIの --mock とPython APIの mock= が優先する |
trackers |
{name: path} |
{} |
— | 追跡system(入力) |
inputs |
{name: path} |
{} |
— | 入力機器(入力) |
controllers |
{name: path} |
{} |
— | controller(controller) |
followers |
{name: path} |
{} |
— | follower(follower) |
sensors |
{name: path or {file, default}} |
{} |
— | sensor.{file, default: false} は既定で起動しない(sensorの選択) |
estimators |
{name: path} |
{} |
— | 推定器(controller) 模擬のみ |
recorder |
path | 必須 | — | recorder のnode YAML |
session |
path | 必須 | — | session のnode YAML |
options |
mapping | {} |
— | 起動option |
followers には,指令を受けて動く装置(腕,gripperなど)を並べます.1つの設定に複数のfollowerを置けます.各followerには,それを動かすcontrollerがちょうど1つ必要です(followerとcontroller).followers: {} としてfollowerを置かない構成は,入力とsensorを記録するだけで,action を記録しません.このときcontrollerは置けず,入力とsensorは自分の周期(poll_hz,fps)を持つ必要があります(Pika Senseを手に持った収集,開発中).
node名
node名はdoraのIDとdatasetのfeature名に使われます.役割をまたいで重複できません.英数字,-,_ だけを使います.recorder,session,action,tick と,action_ で始まる名前,_status で終わる名前は,dataflowが使うので付けられません.
typeと未知のkey
各nodeの type が実装を選びます.roboloomの型の名前(rakuda2_follower など)か,自分のclassへの参照 module:Class を書きます(自分のpackageから足す).nodeが読まないkeyは,読み込みのときに拒否します(綴りを誤ったkeyが黙って無視され,既定値が使われるのを防ぎます.例:followers.follower: unknown keys torqe (did you mean torque?)).control のgroupも,その制御則が読むkeyだけを受け付けます.
未設定の値(SET_)と模擬
SET_... は機体固有の未設定値で,参照する設定に残っていると実行が拒否されます.--mock を付けると,SET_... を埋める前でも検証と実行ができます(模擬deviceのときだけ,projectの mock.yaml にある代用値を使います.fileの SET_... はそのままで,実機では今までどおり拒否します).validate は設定とdataflowの整合性を調べ,deviceは開きません.EEPROMの実機との一致,画像取得,停止挙動までは確認しません.
単位
関節の位置の単位は,followerとleader(inputs)がそれぞれ宣言します.既定値はありません.Rakuda2は dynamixel_count です.controllerの unit は,書くならleaderとfollowerの単位と一致させます(joint controllerは,全関節に scale があれば入力の単位が違ってよい.関節の対応).指令にも単位が入り,followerは自分の単位と違う指令を受け取りません.
速度の上限 max_speed は次の場所にあり,どれもfollowerの単位/sです.
| 場所 | 役割 |
|---|---|
followerの limits の max_speed(関節ごと) |
followerの安全の検査.これを超える目標は削られる.最後の砦なので,controllerの値より大きくする(limits) |
joint controllerの max_speed |
遠隔操作の目標を1周期に動かせる幅 |
policy controllerと pose_ik controllerの max_speed |
目標を1周期に動かせる幅.followerごとに {follower: value} で書く(単位がfollowerごとに違うため) |
controllerの home.max_speed |
保存した姿勢へ動くときの速さ.controllerの max_speed 以下(home) |
home.tolerance(到着とみなす差)も,followerの単位で必ず書きます.
node fileの継承(extends)
機能の組み合わせごとにnode fileを写すと,portや測定値を直すたびに全部を直すことになります.土台のfileを1つ決め,ほかのfileは extends で土台を指して,違うところだけを書きます.
# nodes/leader_gravity.yaml
extends: leader.yaml # 土台.同じdirectoryのnode file
without: [registers.operating_mode] # 土台から外すkey(点区切り).任意
registers:
current_limit: {r_arm_sh_pitch1: 150} # 足す・上書きするものだけ
control:
- group: right_arm # 土台の同じ名前のgroupに重ねる
law: gravity_comp
gravity_model: ../calibration/gravity_right.yaml
bus_watchdog_ms: 500
| 値の種類 | 重ね方 |
|---|---|
| mapping | keyごとに重ねる(入れ子も同じ) |
group か name で名前が付いたmappingのリスト(control,limits) |
同じ名前の要素に重ねる.新しい名前の要素は末尾に足す |
| それ以外(数値,文字列,ふつうのリスト) | 置き換える |
- 土台は同じdirectoryのfileに限ります.fileの中の相対path(
../calibration/...)の基準が変わらないようにするためです. - 土台がさらに
extendsを持てます.循環は拒否します. - 土台の要素を消す・並べ替えるときは,
without: [control]でリストごと外して書き直します.withoutに書いたkeyが土台になければ拒否します. - 未知のkeyの検査は,重ねたあとの内容に対して行います.
- 保存したdatasetの
meta/roboloom.jsonには,重ねたあとの値と,土台のfile名(extends)が残ります. check-holdが書くunattendedは,そのkeyが書いてあるfileに書きます.どこにもなければ,そのnodeのfileに書きます.
Rakuda2のtemplateでは,leader_gravity.yaml が leader.yaml を,policy_teleop.yaml が policy.yaml を土台にしています.
起動option
options: は,起動時に選ぶ機能(重力補償,追加のsensorなど)を名前で定義します.各optionはnode fileを置き換え・追加・削除します.nodes/ の下のnode fileは機能ごとに分かれたままで,optionはどれを使うかを選ぶだけです.optionの名前は英数字,-,_ です.
| key | 型 | 既定値 | 単位 | 説明 |
|---|---|---|---|---|
help |
文字列 | "" |
— | launcherに表示する説明 |
default |
真偽値 | false |
— | true なら,指定がないときに有効 |
requires |
文字列のリスト | [] |
— | 一緒に有効にするoption |
conflicts |
文字列のリスト | [] |
— | 同時に使えないoption |
set |
{<role>.<node>: path or null} |
{} |
— | roleは trackers,inputs,controllers,followers,sensors,estimators のどれか.null はそのnodeを削除する |
dataset |
文字列 | "" |
— | 有効なときにdataset名へ付ける短い名前(英数字,.,-,_) |
規則は次のとおりです.
- optionを有効にすると,
requiresのoptionも有効になり,conflictsのoptionは無効になります.無効にすると,それを必要とするoptionも無効になります. - 有効な2つのoptionが同じnodeを違うfileにするとerrorです.ただし,片方がもう片方を
requiresに持つ場合は,必要とする側(依存する側)が優先します.templateでは,bilateralのleaderがgravityのleaderを,policy_teleopのleaderと方策がpolicyのものを置き換えます. - 未知のoption名はerrorです.
- 有効なoptionの
datasetを,宣言順に-でつないでrepo_idとoutputの末尾に付けます.形の違うepisodeが同じdatasetに混ざらないようにするためです. datasetを持たないoptionが記録するfeatureを変える場合,読み込みを拒否します.roboloom inferは,policyという名前のoptionがあれば有効にします.
template(src/roboloom/robots/rakuda2/template/config.yaml)のoptionです.bilateral は 模擬のみ,pika は 開発中 です.
options:
digit:
help: record the left/right DIGIT tactile sensors
set:
sensors.digit_left: nodes/digit_left.yaml
sensors.digit_right: nodes/digit_right.yaml
dataset: digit
gravity:
help: gravity-compensated leader arms (after the measurement steps of README.md)
set:
inputs.leader: nodes/leader_gravity.yaml
bilateral:
help: force feedback from the follower to the leader (NOT verified on hardware)
requires: [gravity]
set:
inputs.leader: nodes/leader_bilateral.yaml
controllers.controller: nodes/controller_bilateral.yaml
followers.follower: nodes/follower_bilateral.yaml
estimators.effort: nodes/effort.yaml
dataset: bilateral
policy:
help: a learned policy drives the follower (`roboloom infer` turns this on)
conflicts: [gravity]
set:
inputs.leader: null
controllers.controller: null
controllers.policy: nodes/policy.yaml
dataset: eval
pika:
help: a Pika Sense per arm through inverse kinematics (in development, mock only)
conflicts: [gravity, policy]
set:
trackers.lighthouse: nodes/lighthouse.yaml
inputs.leader: null
inputs.right_sense: nodes/right_sense.yaml
inputs.left_sense: nodes/left_sense.yaml
controllers.controller: nodes/controller_pika.yaml
dataset: pika
policy_teleop:
help: with policy, the leader can drive before and during an episode (Teleop / Policy)
requires: [policy]
set:
inputs.leader: nodes/leader.yaml
controllers.policy: nodes/policy_teleop.yaml
dataset: teleop
| 有効なoption | repo_id |
|---|---|
| なし | local/rakuda2 |
digit |
local/rakuda2-digit |
policy |
local/rakuda2-eval |
digit,policy |
local/rakuda2-digit-eval |
policy,policy_teleop |
local/rakuda2-eval-teleop |
gravity,bilateral |
local/rakuda2-bilateral |
pika |
local/rakuda2-pika |
output にも同じ名前が付きます(例:datasets/rakuda2-digit).どのoptionが有効か,dataset名が何になるかは roboloom validate --with digit のように確かめられます.optionの選び方は CLI を,Rakuda2で使える組み合わせと制約は Rakuda2 を参照してください.
実験file
.roboloom/<robot>/ には実機と制御の設定(port,測定値,制限,姿勢)を置きます.実験ごとに変わるもの(方策とcheckpoint,有効にするoption,保存先,task,長さ)は,projectの configs/roboloom/<名前>.yaml に書きます.roboloom infer --experiment <名前> と roboloom record --experiment <名前> が,このfileのとおりに走ります.
# configs/roboloom/drawer.yaml
help: 引き出しを開ける方策の評価
robot: rakuda2 # .roboloom/rakuda2 を使う.commandの robot が優先
options: [policy, digit] # 有効にする起動option
dataset: # 保存先.省略すると robot の設定どおり
root: data/roboloom/drawer
repo_id: local/rakuda2-drawer
nodes: # nodeの設定への上書き
controllers.policy: # mapping:そのnodeの設定に重ねる
factory: my_lab.policies:load
kwargs: {checkpoint: /path/to/project/outputs/drawer/last.ckpt}
rate_hz: 10
action_horizon: 8
inputs.leader: nodes/leader_fixed_head.yaml # 文字列:robot のdirectoryの別のnode fileにする
task: open the drawer
steps: 200 # または seconds: 40
episodes: 10
home: true
uv run roboloom infer --experiment drawer # configs/roboloom/drawer.yaml
uv run roboloom infer --experiment path/to/file.yaml
| key | 型 | 既定値 | 単位 | 説明 |
|---|---|---|---|---|
help |
文字列 | — | — | 説明 |
robot |
文字列 | — | — | robotの名前(.roboloom/<名前>/).commandに書いた robot が優先 |
options |
文字列のリスト | — | — | 有効にする起動option.--with・--without で足し引きできる |
dataset |
{root, repo_id} |
robotの設定どおり | — | root(保存先のdirectory)と repo_id.書いた場所がそのまま保存先になり,optionの名前(-digit-eval)は付かない |
nodes |
{<role>.<node>: mapping or path} |
{} |
— | nodeごとの上書き.mappingは,そのnodeの設定に extends と同じ規則で重ねる.文字列は,robot のdirectoryから見た別のnode fileに差し替える |
task |
文字列 | — | — | --task の値 |
seconds |
数値 | — | s | --seconds の値 |
episodes |
整数 | — | — | --episodes の値 |
home |
真偽値 | — | — | --home の値 |
steps |
整数 | — | 手 | infer --steps の値.episodeを,方策が実行した行動の数で終える.seconds とは同時に書けない |
- 名前とpath:
--experiment drawerは,commandを実行したdirectoryのconfigs/roboloom/drawer.yamlです./を含むか.yamlで終わるものはpathとして読みます. - 相対path:
dataset.rootはcommandを実行したdirectory(projectのroot)から,nodesの文字列は robot のdirectoryから見ます. nodesで指せるnode:optionを適用したあとに存在するnodeだけです.followers.*は上書きできません(followerの範囲・速度・飛びの制限は,すべての指令を検査する最後の層です).- 書かなかった設定は,robot のnode fileの値のままです(方策の
max_speed,command_deadline_msなど). - command lineに書いた値が優先します(
--experiment drawer --seconds 10).secondsもstepsもどちらにもなければ拒否します. stepsのepisodeは,方策が指定の手数を実行した時点で終わります.推論待ちで遅れる場合に備えて,上限時間(steps / rate_hz × 1.5 + 5秒)でも終わり,そのときは何手で終わったかを表示します.- 未知のkeyは拒否します.
validate,check-dataset,labelも--experimentを受けます(その実験の構成と保存先を指します).- 保存したdatasetの
meta/roboloom.jsonには,実験の名前と,重ねたあとの設定が残ります. backend: serverの方策は,同じfileからserverを起動できます(roboloom serve-policy --experiment <file>).
Pythonでは Session.launch(experiment=...) に,名前,path,同じkeyのmappingのどれかを渡します.Hydraで実験を合成するprojectは,合成した結果を渡します.roboloom自身はHydraに依存しません.
from omegaconf import OmegaConf
from roboloom import Session
experiment = OmegaConf.to_container(cfg.roboloom, resolve=True) # Hydraで合成したもの
with Session.launch(experiment=experiment) as session:
session.wait_ready(60)
session.record(experiment["task"], 155.0, steps=experiment["steps"])
logと設定の管理
logは設定fileの隣の logs/<dataset name>-<time>/ に置きます(例:logs/rakuda2-digit-20261102-101500/).dataset名から,有効だったoptionが分かります.leaderの電流制御は <leader名>_trace.npz に,followerは毎周期の状態(位置・速度・電流・目標・mode)を <follower name>_trace.npz に,nodeの終了時に書きます.YAMLの設定・重力model・可動域・調整値・保存した初期姿勢(poses/<follower>/)はGitで管理し,生data *.npz・log・dataset・FIFO(config.fifo)は生成した .roboloom/.gitignore で除外します.
APIの詳細は Python API,commandは CLI にあります.