Fixi pixi.toml

.clang-format

@@ -9,7 +9,7 @@ PointerAlignment: Left
 # AlignAfterOpenBracket: DontAlign
 AlignConsecutiveAssignments:
   Enabled: true
-  AcrossEmptyLines: true
+  AcrossEmptyLines: false
   AcrossComments: false
 AlignConsecutiveMacros:
   Enabled: true

.devcontainer/gpu/devcontainer.json

@@ -17,8 +17,4 @@
             ]
         }
     },
-    "initializeCommand": "export OBELISK_ROOT=${localWorkspaceFolder}",
-    "remoteEnv": {
-        "OBELISK_ROOT": "${localEnv: OBELISK_ROOT}"
-    }
 }

.devcontainer/no_gpu/devcontainer.json

@@ -17,8 +17,4 @@
             ]
         }
     },
-    "initializeCommand": "export OBELISK_ROOT=${localWorkspaceFolder}",
-    "remoteEnv": {
-        "OBELISK_ROOT": "${localEnv: OBELISK_ROOT}"
-    }
 }

.github/workflows/code_checks.yml

@@ -30,23 +30,23 @@ jobs:
           key: ${{ env.pythonLocation }}-${{ hashFiles('pixi.toml') }}
       - name: Set Up Development Environment
         run: |
-          source dev_setup.sh
-          docker compose -f $GITHUB_WORKSPACE/docker/docker-compose-no-gpu.yml up -d
+          source setup.sh
+          docker compose -f $GITHUB_WORKSPACE/docker/docker-compose-ci.yml up -d
       - name: Build ROS2 Messages
         run: |
-          docker compose -f $GITHUB_WORKSPACE/docker/docker-compose-no-gpu.yml exec -T obelisk bash -c "$HOME/.pixi/bin/pixi run --environment dev-no-gpu messages-build"
+          docker compose -f $GITHUB_WORKSPACE/docker/docker-compose-ci.yml exec -T obelisk bash -c "$HOME/.pixi/bin/pixi run --environment dev-no-gpu messages-build"
       - name: Build and Source ROS2
         run: |
-          docker compose -f $GITHUB_WORKSPACE/docker/docker-compose-no-gpu.yml exec -T obelisk bash -c "$HOME/.pixi/bin/pixi run --environment dev-no-gpu source-obelisk"
+          docker compose -f $GITHUB_WORKSPACE/docker/docker-compose-ci.yml exec -T obelisk bash -c "$HOME/.pixi/bin/pixi run --environment dev-no-gpu ros-build"
       - name: Run Ruff Linter
         run: |
-          docker compose -f $GITHUB_WORKSPACE/docker/docker-compose-no-gpu.yml exec -T obelisk bash -c "$HOME/.pixi/bin/pixi run --environment dev-no-gpu ruff check docs/ obelisk/ tests/ --output-format=github"
+          docker compose -f $GITHUB_WORKSPACE/docker/docker-compose-ci.yml exec -T obelisk bash -c "$HOME/.pixi/bin/pixi run --environment dev-no-gpu ruff check docs/ obelisk/ tests/ --output-format=github"
       - name: Run Ruff Formatter
         run: |
-          docker compose -f $GITHUB_WORKSPACE/docker/docker-compose-no-gpu.yml exec -T obelisk bash -c "$HOME/.pixi/bin/pixi run --environment dev-no-gpu ruff format docs/ obelisk/ tests/ --diff"
+          docker compose -f $GITHUB_WORKSPACE/docker/docker-compose-ci.yml exec -T obelisk bash -c "$HOME/.pixi/bin/pixi run --environment dev-no-gpu ruff format docs/ obelisk/ tests/ --diff"
       - name: Run Pyright
         run: |
-          docker compose -f $GITHUB_WORKSPACE/docker/docker-compose-no-gpu.yml exec -T obelisk bash -c "$HOME/.pixi/bin/pixi run --environment dev-no-gpu pyright"
+          docker compose -f $GITHUB_WORKSPACE/docker/docker-compose-ci.yml exec -T obelisk bash -c "$HOME/.pixi/bin/pixi run --environment dev-no-gpu pyright"
       - name: Test with pytest and ctest
         run: |
-          docker compose -f $GITHUB_WORKSPACE/docker/docker-compose-no-gpu.yml exec -T obelisk bash -c "$HOME/.pixi/bin/pixi run --environment dev-no-gpu all-tests"
+          docker compose -f $GITHUB_WORKSPACE/docker/docker-compose-ci.yml exec -T obelisk bash -c "$HOME/.pixi/bin/pixi run --environment dev-no-gpu all-tests"

README.md

@@ -1,35 +1,74 @@
 # Obelisk: A Stable Robot Control Interface
-This repository hosts generic interfaces for controlling the lab's robots with ROS2.
+This repository hosts generic interfaces for controlling robots with ROS2.
 
 [Docs](https://caltech-amber.github.io/obelisk/)
 
-## Development
-We recommend developing using `pixi` for dependency management. First, install required system-level dependencies for development and set environment variables by running the following script:
+## 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:
+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. The available options are:
 ```
-source dev_setup.sh
-newgrp docker
+source setup.sh [--no-skip-docker] [--pixi] [--cyclone-perf] [--bash-aliases] [--obk-aliases]
 ```
-This will do the following:
-1. install `docker`
-2. install `nvidia-container-toolkit`
-3. install `pixi`
-4. install `uv`
-5. install `nvm` (required for `pyright`)
-6. set the `OBELISK_ROOT` environment variable to the repo root
-
-### Docker
-We recommend developing on `obelisk` using a Docker container (we provide `.devcontainer` support if you use an IDE supporting it). You can also bring up a container using docker-compose as follows from the repository root:
+* The `--no-skip-docker` flag installs `docker` and `nvidia-container-toolkit` on your local filesystem. You should only specify this if you want to develop in a containerized setting.
+* The `--pixi` flag installs `pixi` on your local filesystem.
+* The `--cyclone-perf` flag adds [performance optimizations for Cyclone DDS](https://github.com/ros2/rmw_cyclonedds?tab=readme-ov-file#performance-recommendations) in the `/etc/sysctl.d/60-cyclonedds.conf` file on your local filesystem. You should  specify this if you plan to use Obelisk in a non-containerized environment.
+* The `--bash-aliases` flag will check if `~/.bash_aliases` is sourced in the `~/.bashrc` file (and will add it if not already in there), and will create the `~/.bash_aliases` file if it doesn't already exist. This is a very benign flag, so we recommend using it.
+* The `--obk-aliases` flag will add useful Obelisk aliases to the `~/.bash_aliases` file. **We highly recommend using this flag.**
+* If you trust us, you can use the `--all` flag to just opt-in to all of these dependencies.
+If you're more cautious, we recommend running
 ```
-docker compose -f docker/docker-compose.yml run --build obelisk
+source setup.sh --pixi --bash-aliases --obk-aliases
 ```
-To enter the container without rebuilding or to join from a different terminal window, run
+If you're installing `docker` for the first time using this script, you also need to run afterwards
 ```
-docker compose -f docker/docker-compose.yml run obelisk
+newgrp docker
 ```
-If you are running on a machine with no Nvidia GPUs, you can instead run
+
+### Building Obelisk
+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`.
+
+* If you are building it on your local filesystem, you need some minimal set of local dependencies. You can install these by running
+    ```
+    bash scripts/install_sys_deps.sh
+    ```
+    This will prompt you to confirm changes to your local filesystem. To auto-accept the installations, use the `-y` flag. To source the base ROS installation in the `~/.bashrc` without prompting, use the `--source-ros` flag. To not source it without prompting, use the `--no-source-ros` flag.
+
+    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]
+
+    # build in the pixi shell
+    pixi run ros-clean
+    obk-build
+    ```
+
+### 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:
+```
+obk
+```
+You should run `obk` in any terminal where you need to run Obelisk. It will set up important environment variables to configure the Obelisk stack while also sourcing the built Obelisk packages in that shell. `obk` also runs `obk-build` if it is detected that there is no `install` directory in the Obelisk workspace, so you can use it to first-time build Obelisk. You only need to run `obk-build` if you are developing and changing Obelisk's source code.
+
+To clean Obelisk directories, run
 ```
-docker compose -f docker/docker-compose-no-gpu.yml run --build obelisk
+obk-clean
 ```
+This will delete cached build files associated with Obelisk. If you have tried building the Obelisk source code multiple times or from different environments/local filesystems, it may be corrupted, and cleaning the installation can help fix issues.
 
-### Building Docs
+## Building Docs
 In the repository root, to build the docs locally, run `sphinx-build -M html docs/source/ docs/build/`.

docker/Dockerfile

@@ -13,29 +13,17 @@ ENV USER=$USER
 ENV UID=$UID
 ENV GID=$GID
 ENV OBELISK_ROOT=$OBELISK_ROOT
+ENV XDG_RUNTIME_DIR=/run/user/${UID}
 
 # set timezone
 ENV TZ=America/Los_Angeles
 RUN ln -snf /usr/share/zoneinfo/$TZ /etc/localtime && echo $TZ > /etc/timezone
 
-# basic dependencies from docker_setup.sh (up until sudo and below)
+# basic dependencies that are not handled by pixi
 RUN apt-get update && apt-get install -y \
     curl \
-    build-essential \
-    cmake \
-    clang-tools-12 \
-    nano \
-    vim \
     git \
-    python3-dev \
-    python-is-python3 \
-    python3-pip \
-    python3-argcomplete \
-    mesa-utils \
-    x11-apps \
-    libyaml-dev \
     mesa-common-dev \
-    libglfw3-dev \
     locales \
     sudo && \
     rm -rf /var/lib/apt/lists/* && \
@@ -49,17 +37,14 @@ RUN groupadd --gid $GID $USER && \
     echo "%${USER} ALL=(ALL) NOPASSWD:ALL" >> /etc/sudoers
 
 # add user to dialout group to enable serial port access from the container
-RUN sudo usermod -a -G dialout ${USER}
+RUN usermod -a -G dialout ${USER}
 
 # switch to new user and workdir
 USER ${UID}
 
 # run docker setup script in Dockerfile
 COPY docker_setup.sh /tmp/docker_setup.sh
-RUN source /tmp/docker_setup.sh --skip-docker && \
+RUN source /tmp/docker_setup.sh --pixi --cyclone-perf && \
     sudo rm /tmp/docker_setup.sh
 
-# add local user binary folder to PATH variable
-ENV PATH="${PATH}:/home/${USER}/.local/bin"
-ENV XDG_RUNTIME_DIR=/run/user/${UID}
 WORKDIR /home/${USER}

docker/docker-compose-ci.yml

@@ -0,0 +1,37 @@
+services:
+  obelisk:
+    shm_size: '12gb'
+    build:
+      context: .
+      args:
+        USER: $USER
+        UID: $UID
+        GID: $UID
+        OBELISK_ROOT: $OBELISK_ROOT
+      dockerfile: Dockerfile
+    network_mode: host
+    ipc: host
+    environment:
+      DISPLAY: $DISPLAY
+      USER: $USER
+      UID: $UID
+      GID: $UID
+      OBELISK_ROOT: $OBELISK_ROOT
+      QT_X11_NO_MITSHM: 1
+    security_opt:
+      - seccomp=unconfined
+    cap_add:
+      - NET_ADMIN
+    volumes:
+      - $OBELISK_ROOT:$OBELISK_ROOT
+      - /tmp/.X11-unix:/tmp/.X11-unix
+      - $HOME/.Xauthority:$HOME/.Xauthority:rw
+      - $HOME/.bashrc:$HOME/.bashrc
+      - $HOME/.bash_aliases:$HOME/.bash_aliases
+    ports:
+      - 7007:7007
+    privileged: true
+    working_dir: $OBELISK_ROOT
+    stdin_open: true
+    tty: true
+    command: /bin/bash

docker/docker-compose-no-gpu.yml

@@ -27,7 +27,9 @@ services:
       - /tmp/.X11-unix:/tmp/.X11-unix
       - $HOME/.Xauthority:$HOME/.Xauthority:rw
       - $HOME/.bashrc:$HOME/.bashrc
-      - /etc/sysctl.d/60-cyclonedds.conf:/etc/sysctl.d/60-cyclonedds.conf
+      - $HOME/.bash_aliases:$HOME/.bash_aliases
+      - $HOME/.gitconfig:$HOME/.gitconfig
+      - $HOME/.ssh:$HOME/.ssh
     ports:
       - 7007:7007
     privileged: true

docker/docker-compose.yml

@@ -28,7 +28,9 @@ services:
       - /tmp/.X11-unix:/tmp/.X11-unix
       - $HOME/.Xauthority:$HOME/.Xauthority:rw
       - $HOME/.bashrc:$HOME/.bashrc
-      - /etc/sysctl.d/60-cyclonedds.conf:/etc/sysctl.d/60-cyclonedds.conf
+      - $HOME/.bash_aliases:$HOME/.bash_aliases
+      - $HOME/.gitconfig:$HOME/.gitconfig
+      - $HOME/.ssh:$HOME/.ssh
     ports:
       - 7007:7007
     privileged: true