Config string refactor

.claude/settings.local.json

@@ -1,7 +1,8 @@
 {
   "permissions": {
     "allow": [
-      "Read(//home/wcompton/repos/IsaacLab/source/isaaclab/isaaclab/sensors/ray_caster/patterns/**)"
+      "Read(//home/wcompton/repos/IsaacLab/source/isaaclab/isaaclab/sensors/ray_caster/patterns/**)",
+      "Bash(git *)"
     ]
   }
 }

.gitignore

@@ -246,3 +246,9 @@ MUJOCO_LOG.TXT
 obk_logs/
 docker/user_setup.sh
 docker/install_sys_deps.sh
+
+# ###### #
+# CLAUDE #
+# ###### #
+CLAUDE.md
+.claude/

README.md

@@ -4,10 +4,9 @@ This repository hosts generic interfaces for controlling robots with ROS2.
 [Docs](https://caltech-amber.github.io/obelisk/)
 
 ## Setup
-Obelisk should be used as a dependency for external robot control code that is written in other downstream projects. There are a few options:
+Obelisk should be used as a dependency for external robot control code that is written in other downstream projects. There are two options:
 1. Use Obelisk in Docker (this is mainly for developing in Obelisk).
 2. Use Obelisk on your local filesystem.
-3. Use Obelisk in a project that uses `pixi`.
 
 ### Initial Setup
 Initial setup proceeds by running the `setup.sh` script in the repository root. This script has the ability to make changes to your local dependencies - all such changes are opt-in. **It is very important that you run `setup.sh` using the `source` command, and not `bash`, because there are environment variables that will be sourced!**
@@ -23,38 +22,22 @@ The options are as follows:
 source setup.sh [OPTIONS]
 
 Options:
-  --recommended                Apply recommended system-level changes
-                               (cyclone performance optimizations, pixi, obelisk aliases)
+  --dev-setup                  Setup for development of Obelisk (Docker-based).
+  --downstream-setup           Setup for downstream use of Obelisk (local install).
 
-  --basic                      Enables basic dependencies necessary for Obelisk locally
-  --cyclone-perf               Enables cyclone performance optimizations
-  --leap                       Enables LEAP hand dependencies
-  --zed                        Enables ZED SDK
+  Hardware:
+  --zed                        Enable ZED SDK
+  --unitree                    Enable Unitree interfaces
 
-  --docker-install             Install Docker and nvidia-container-toolkit
-  --install-sys-deps-docker    Installs system dependencies in Docker
-
-  --config-groups              Configures user groups associated with hardware
-
-  --install-sys-deps           Installs system dependencies
-  --source-ros                 Sources base ROS in ~/.bashrc (only used if --install-sys-deps)
-
-  --pixi                       Install pixi
-  --obk-aliases                Add obelisk aliases to the ~/.bash_aliases file
+  Simulation:
+  --mujoco                     Enable Mujoco simulation
 
   --help                       Display this help message and exit
 ```
 
-Some guidance/recommendations on choosing flags:
-* If you don't have Docker on your machine, use the `--docker-install` flag
-* If you are not using Docker, then you should use `--install-sys-deps`
-* If you are using Docker, but not pixi, you should also use `--install-sys-deps`
-* If you are using Docker, use `--install-sys-deps-docker` if and only if you are **not** using pixi within the container.
-* If you are using pixi, regardless of whether you are using Docker, you should **not** use the `--basic` flag (note: you may have to manually install `mesa-common-dev`)
-* If you are not using pixi or conda, you should probably use `--source-ros` along with `--install-sys-deps`
-* We believe using `--pixi` will make your life easier, but you don't have to use it
-* We strongly recommend using `--obk-aliases` and `--cyclone-perf`
-* If you are using the LEAP Hand, use `--leap`
+Guidance:
+* For developing Obelisk inside the dev container: `source setup.sh --dev-setup` (plus any hardware flags you need).
+* For consuming Obelisk in a downstream project on your local machine: `source setup.sh --downstream-setup`.
 * If you are using ZED cameras, use `--zed`. Additionally, you will need to adjust the `udev` permissions on your host machine if you want to use the ZED cameras in a Docker container with a non-root user (if you are acting as root in your container, you probably don't need to do this next step):
 * You should run `--config-groups` only if your local user isn't set up to interface with hardware of interest. If you are going to develop in a Docker container, the group settings will be set for you **without** setting this flag. If you are cloning this repo in a Docker container and running the setup script, setup will **only be complete if you do set this flag**.
     ```
@@ -79,28 +62,15 @@ newgrp docker
 ```
 
 ### Building Obelisk ROS Packages
-Next, since Obelisk acts as a dependency for a downstream ROS2 project, you have to build it. You can either build it on your local filesystem or in a virtual environment that we manage using `pixi`.
+Once dependencies are in place, build the Obelisk ROS2 packages with `obk-build` (a colcon wrapper installed by `--dev-setup` / `--downstream-setup`). The recommended workflow is to develop inside the dev container:
 
-* If you are building it on your local filesystem, you need some minimal set of local dependencies. These should have been installed in the previous step.
-
-    If you have run the initial setup script with the `--obk-aliases` flag, then running
-    ```
-    obk-build
-    ```
-    will build the Obelisk ROS2 libraries on your local filesystem.
-* If you are building it using `pixi`, we recommend using the Docker containers we provide:
-    ```
-    # enter the docker container
-    cd docker
-    docker compose -f [docker-compose.yml | docker-compose-no-gpu.yml] run --build obelisk
-
-    # build and enter the pixi shell
-    pixi shell -e [dev | dev-no-gpu]
+```
+cd docker
+docker compose -f docker-compose.yml run --build obelisk            # GPU
+docker compose -f docker-compose-no-gpu.yml run --build obelisk     # no GPU
+```
 
-    # build in the pixi shell
-    pixi run ros-clean
-    obk-build
-    ```
+Inside the container, `obk` builds (first time) and sources the workspace; `obk-build` rebuilds after edits; `obk-clean` nukes `build/install/log` if you need a clean slate.
 
 ### Using Obelisk
 Once Obelisk has been built, you can use it. If you have set up Obelisk using the `--obk-aliases` flag, we provide a very useful command:

docker/config_groups.sh

@@ -1,7 +1,6 @@
 #!/bin/bash
 
 # --- script flags --- #
-leap=false
 zed=false
 
 for arg in "$@"; do

docker/docker-compose-ci.yml

@@ -8,7 +8,6 @@ services:
         UID: $UID
         GID: $UID
         OBELISK_ROOT: $OBELISK_ROOT
-        OBELISK_DOCKER_PIXI: true
       dockerfile: Dockerfile
     network_mode: host
     ipc: host
@@ -18,7 +17,6 @@ services:
       UID: $UID
       GID: $UID
       OBELISK_ROOT: $OBELISK_ROOT
-      OBELISK_DOCKER_PIXI: true
       QT_X11_NO_MITSHM: 1
     security_opt:
       - seccomp=unconfined

docker/docker-compose-no-gpu.yml

@@ -10,9 +10,6 @@ services:
         OBELISK_ROOT: $OBELISK_ROOT
         OBELISK_DOCKER_BASIC: $OBELISK_DOCKER_BASIC
         OBELISK_DOCKER_CYCLONE_PERF: $OBELISK_DOCKER_CYCLONE_PERF
-        OBELISK_DOCKER_LEAP: $OBELISK_DOCKER_LEAP
-        OBELISK_DOCKER_PIXI: $OBELISK_DOCKER_PIXI
-        OBELISK_DOCKER_GROUP_LEAP: $OBELISK_DOCKER_GROUP_LEAP
       dockerfile: Dockerfile
     network_mode: host
     ipc: host
@@ -24,9 +21,6 @@ services:
       OBELISK_ROOT: $OBELISK_ROOT
       OBELISK_DOCKER_BASIC: $OBELISK_DOCKER_BASIC
       OBELISK_DOCKER_CYCLONE_PERF: $OBELISK_DOCKER_CYCLONE_PERF
-      OBELISK_DOCKER_LEAP: $OBELISK_DOCKER_LEAP
-      OBELISK_DOCKER_PIXI: $OBELISK_DOCKER_PIXI
-      OBELISK_DOCKER_GROUP_LEAP: $OBELISK_DOCKER_GROUP_LEAP
       QT_X11_NO_MITSHM: 1
     security_opt:
       - seccomp=unconfined

docker/docker-compose.yml

@@ -10,7 +10,6 @@ services:
         OBELISK_ROOT: $OBELISK_ROOT
         OBELISK_DOCKER_BASIC: $OBELISK_DOCKER_BASIC
         OBELISK_DOCKER_CYCLONE_PERF: $OBELISK_DOCKER_CYCLONE_PERF
-        OBELISK_DOCKER_LEAP: $OBELISK_DOCKER_LEAP
         OBELISK_DOCKER_ZED: $OBELISK_DOCKER_ZED
         OBELISK_DOCKER_GROUP_ZED: $OBELISK_DOCKER_GROUP_ZED
         OBELISK_DOCKER_MUJOCO: $OBELISK_DOCKER_MUJOCO
@@ -26,7 +25,6 @@ services:
       OBELISK_ROOT: $OBELISK_ROOT
       OBELISK_DOCKER_BASIC: $OBELISK_DOCKER_BASIC
       OBELISK_DOCKER_CYCLONE_PERF: $OBELISK_DOCKER_CYCLONE_PERF
-      OBELISK_DOCKER_LEAP: $OBELISK_DOCKER_LEAP
       OBELISK_DOCKER_ZED: $OBELISK_DOCKER_ZED
       OBELISK_DOCKER_GROUP_ZED: $OBELISK_DOCKER_GROUP_ZED
       OBELISK_DOCKER_MUJOCO: $OBELISK_DOCKER_MUJOCO

docs/source/development.md

@@ -83,12 +83,12 @@ To launch a ROS stack we can use the following commands.
 
 In a seperate terminal, we can run a ROS stack with:
 ```
-obk-launch config=<config file> device=<device>
+obk-launch config=<config file>
 ```
 
 Specifically, for the dummy examples this looks like:
 ```
-obk-launch config=dummy_cpp.yaml device=onboard
+obk-launch config=dummy_cpp.yaml
 ```
 
 All the documentation for the Obelisk terminal aliases can be found [here](obelisk_terminal_aliases.md).

docs/source/getting_started.md

@@ -233,7 +233,7 @@ If you are using a stable version of Obelisk, you should only need to run this o
 
 Once Obelisk is activated and built we can run a basic example to make sure everything is working as expected.
 ```
-obk-launch config=dummy_cpp.yaml device=onboard
+obk-launch config=dummy_cpp.yaml
 ```
 At this point you should see a Mujoco simulation running.
 

docs/source/obelisk_terminal_aliases.md

@@ -5,11 +5,11 @@ Launches the `obelisk_bringup.launch.py` with specified arguments.
 
 Usage:
 ```
-obk-launch config=<path> device=<name> auto_start=<True|False>
+obk-launch config=<path> [auto_start=<True|False>] [bag=<True|False>]
 ```
 Example:
 ```
-obk-launch config=example.yaml device=onboard auto_start=True
+obk-launch config=example.yaml auto_start=True
 ```
 
 ## `obk-build`

docs/source/unitree_interfaces.md

@@ -28,29 +28,49 @@ To avoid having the default FSM conflict with any user-specified FSM operating o
 
 where L1 refers to Layer 1, i.e. the layer button must be held down. Additionally, all buttons not passed to the fsm are passed through on a separate joystick node (`/obelisk/g1/joy_passthrough` by default). It is recommended that the user subscribe to this topic to use the controller, rather than the joystick topic (default `/obelisk/g1/joy`), to avoid interference with the fsm. 
 
-All of these buttons can be remapped as desired in the setup yaml. Here is a complete yaml, with all available options (omitted options will take default values): 
+All of these buttons can be remapped as desired in the setup yaml. The relevant pieces live in two
+places:
 
-```
+1. The **top-level `joystick:` block** configures the raw ROS `joy_node` that reads hardware joystick
+   events and publishes them on `/obelisk/g1/joy`. Only `on`, `pub_topic`, `sub_topic`, and standard
+   `joy_node` parameters (`device_id`, `device_name`, `deadzone`, `autorepeat_rate`,
+   `sticky_buttons`, `coalesce_interval_ms`) live here.
+2. The **`obelisk_unitree_joystick` control entry** (under `control:`) translates raw button events
+   into FSM transitions and velocity commands. Its remap settings — button bindings and scale factors
+   — go in its own `params:` block.
+
+A complete config showing all available options (omitted options take defaults):
+
+```yaml
+# 1. ROS joy_node — raw joystick → /obelisk/g1/joy
 joystick:
     on: True
     pub_topic: /obelisk/g1/joy
     sub_topic: /obelisk/g1/joy_feedback
-    ros_parameters:
-        v_x_scale: 0.5
-        v_y_scale: 0.5
-        w_z_scale: 0.5
-        unitree_home_button:    116  // DL1
-        user_pose_button:       127  // DR1
-        low_level_ctrl_button:  128  // DD1
-        high_level_ctrl_button: 117  // DU1
-        damping_button:          12  // LT
-        estop:                   15  // RT     
-        vel_cmd_x:               11  // LY
-        vel_cmd_y:               10  // LX
-        vel_cmd_yaw:             14  // RY
-        layer:                    4  // LB
+
+# 2. Obelisk unitree-joystick controller — buttons → FSM/vel commands
+control:
+    - pkg: obelisk_unitree_cpp
+      executable: obelisk_unitree_joystick
+      params:
+          v_x_scale: 0.5
+          v_y_scale: 0.5
+          w_z_scale: 0.5
+          axis_threshold: -0.1
+          menu_button:              7  # MENU
+          unitree_home_button:    116  # DL1
+          user_pose_button:       127  # DR1
+          low_level_ctrl_button:  128  # DD1
+          high_level_ctrl_button: 117  # DU1
+          damping_button:          12  # LT
+          estop:                   15  # RT
+          vel_cmd_x:               11  # LY
+          vel_cmd_y:               10  # LX
+          vel_cmd_yaw:             14  # RY
+          layer_button:             4  # LB
+      # publishers/subscribers/timers as in the example configs
 ```
-`scale` parameters refer to the multiplicative factor under which joystick inputs are scaled when passed to the unitree controller (or if the user controller is subscribed to the same message). 
+`scale` parameters refer to the multiplicative factor under which joystick inputs are scaled when passed to the unitree controller (or if the user controller is subscribed to the same message).
 Buttons are passed as integers, under the following map:
 ```
 LT = 12     // 2 + AXIS_OFFSET,
@@ -102,5 +122,5 @@ Note that to avoid conflicts between `button` indices and `axis` indices (and is
 ## Debugging
 You can also check what the default button mappings are by running:
 ```
-obk-launch config=unitree_fsm_debug.yaml device=onboard
+obk-launch config=unitree_fsm_debug.yaml
 ```