コンテンツにスキップ

設定

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 にあります.