From 870c8300b532bb23c8c393c8a030632b551e6a91 Mon Sep 17 00:00:00 2001 From: Jeff Hykin Date: Thu, 12 Feb 2026 23:51:08 -0800 Subject: [PATCH 001/140] move, no fixed links --- docs/api/README.md | 11 - docs/api/assets/transforms.png | 3 - docs/api/assets/transforms_chain.svg | 12 -- docs/api/assets/transforms_modules.svg | 20 -- docs/api/assets/transforms_tree.svg | 26 --- docs/development/writing_docs.md | 7 + docs/development/writing_docs/README.md | 17 -- .../assets/codeblocks_example.svg | 47 ----- .../writing_docs/assets/pikchr_basic.svg | 12 -- .../writing_docs/assets/pikchr_branch.svg | 16 -- .../writing_docs/assets/pikchr_explicit.svg | 8 - .../writing_docs/assets/pikchr_labels.svg | 5 - .../writing_docs/assets/pikchr_sizing.svg | 13 -- docs/development/writing_docs/codeblocks.md | 195 ------------------ .../writing_docs/diagram_practices.md | 146 ------------- docs/development/writing_docs/doclinks.md | 119 ----------- docs/{concepts => usage}/README.md | 0 .../assets/abstraction_layers.svg | 0 .../assets/camera_module.svg | 0 .../assets/go2_agentic.svg | 0 docs/{concepts => usage}/assets/go2_nav.svg | 0 docs/{concepts => usage}/assets/lcmspy.png | 0 .../assets/pubsub_benchmark.png | 0 docs/{concepts => usage}/blueprints.md | 0 docs/{api => usage}/configuration.md | 0 docs/{concepts => usage}/lcm.md | 0 docs/{concepts => usage}/modules.md | 0 docs/{api => usage}/sensor_streams/README.md | 0 .../sensor_streams/advanced_streams.md | 0 .../sensor_streams/assets/alignment_flow.svg | 0 .../assets/alignment_overview.svg | 0 .../assets/alignment_timeline.png | 0 .../assets/alignment_timeline2.png | 0 .../assets/alignment_timeline3.png | 0 .../sensor_streams/assets/backpressure.svg | 0 .../assets/backpressure_solution.svg | 0 .../sensor_streams/assets/frame_mosaic.jpg | 0 .../sensor_streams/assets/frame_mosaic2.jpg | 0 .../sensor_streams/assets/getter_hot_cold.svg | 0 .../sensor_streams/assets/observable_flow.svg | 0 .../sensor_streams/assets/sharpness_graph.svg | 0 .../assets/sharpness_graph2.svg | 0 .../sensor_streams/quality_filter.md | 0 .../sensor_streams/reactivex.md | 0 .../sensor_streams/storage_replay.md | 0 .../sensor_streams/temporal_alignment.md | 0 docs/{api => usage}/transforms.md | 0 docs/{concepts => usage}/transports.md | 0 docs/{api => usage}/visualization.md | 0 49 files changed, 7 insertions(+), 650 deletions(-) delete mode 100644 docs/api/README.md delete mode 100644 docs/api/assets/transforms.png delete mode 100644 docs/api/assets/transforms_chain.svg delete mode 100644 docs/api/assets/transforms_modules.svg delete mode 100644 docs/api/assets/transforms_tree.svg create mode 100644 docs/development/writing_docs.md delete mode 100644 docs/development/writing_docs/README.md delete mode 100644 docs/development/writing_docs/assets/codeblocks_example.svg delete mode 100644 docs/development/writing_docs/assets/pikchr_basic.svg delete mode 100644 docs/development/writing_docs/assets/pikchr_branch.svg delete mode 100644 docs/development/writing_docs/assets/pikchr_explicit.svg delete mode 100644 docs/development/writing_docs/assets/pikchr_labels.svg delete mode 100644 docs/development/writing_docs/assets/pikchr_sizing.svg delete mode 100644 docs/development/writing_docs/codeblocks.md delete mode 100644 docs/development/writing_docs/diagram_practices.md delete mode 100644 docs/development/writing_docs/doclinks.md rename docs/{concepts => usage}/README.md (100%) rename docs/{concepts => usage}/assets/abstraction_layers.svg (100%) rename docs/{concepts => usage}/assets/camera_module.svg (100%) rename docs/{concepts => usage}/assets/go2_agentic.svg (100%) rename docs/{concepts => usage}/assets/go2_nav.svg (100%) rename docs/{concepts => usage}/assets/lcmspy.png (100%) rename docs/{concepts => usage}/assets/pubsub_benchmark.png (100%) rename docs/{concepts => usage}/blueprints.md (100%) rename docs/{api => usage}/configuration.md (100%) rename docs/{concepts => usage}/lcm.md (100%) rename docs/{concepts => usage}/modules.md (100%) rename docs/{api => usage}/sensor_streams/README.md (100%) rename docs/{api => usage}/sensor_streams/advanced_streams.md (100%) rename docs/{api => usage}/sensor_streams/assets/alignment_flow.svg (100%) rename docs/{api => usage}/sensor_streams/assets/alignment_overview.svg (100%) rename docs/{api => usage}/sensor_streams/assets/alignment_timeline.png (100%) rename docs/{api => usage}/sensor_streams/assets/alignment_timeline2.png (100%) rename docs/{api => usage}/sensor_streams/assets/alignment_timeline3.png (100%) rename docs/{api => usage}/sensor_streams/assets/backpressure.svg (100%) rename docs/{api => usage}/sensor_streams/assets/backpressure_solution.svg (100%) rename docs/{api => usage}/sensor_streams/assets/frame_mosaic.jpg (100%) rename docs/{api => usage}/sensor_streams/assets/frame_mosaic2.jpg (100%) rename docs/{api => usage}/sensor_streams/assets/getter_hot_cold.svg (100%) rename docs/{api => usage}/sensor_streams/assets/observable_flow.svg (100%) rename docs/{api => usage}/sensor_streams/assets/sharpness_graph.svg (100%) rename docs/{api => usage}/sensor_streams/assets/sharpness_graph2.svg (100%) rename docs/{api => usage}/sensor_streams/quality_filter.md (100%) rename docs/{api => usage}/sensor_streams/reactivex.md (100%) rename docs/{api => usage}/sensor_streams/storage_replay.md (100%) rename docs/{api => usage}/sensor_streams/temporal_alignment.md (100%) rename docs/{api => usage}/transforms.md (100%) rename docs/{concepts => usage}/transports.md (100%) rename docs/{api => usage}/visualization.md (100%) diff --git a/docs/api/README.md b/docs/api/README.md deleted file mode 100644 index 1a14f83640..0000000000 --- a/docs/api/README.md +++ /dev/null @@ -1,11 +0,0 @@ -# API - -Note: Please see [Concepts](/docs/concepts/README.md) before diving into these API docs. These docs are designed to be technical, cover specific tooling, and give examples of using those tools (argument types) rather than explaining when to use the tool. - - -# Table of Contents - -- [adding configs to your modules](./configuration.md) -- [controlling how visualizations are rendered](./visualization.md) -- [understanding sensor streams](./sensor_streams/README.md) -- [creating coordinate frames and transforms for your hardware](./transforms.md) diff --git a/docs/api/assets/transforms.png b/docs/api/assets/transforms.png deleted file mode 100644 index 49dba4ab9a..0000000000 --- a/docs/api/assets/transforms.png +++ /dev/null @@ -1,3 +0,0 @@ -version https://git-lfs.github.com/spec/v1 -oid sha256:6597e0008197902e321a3ad3dfb1e838f860fa7ca1277c369ed6ff7da8bf757d -size 101102 diff --git a/docs/api/assets/transforms_chain.svg b/docs/api/assets/transforms_chain.svg deleted file mode 100644 index 3f6c21741b..0000000000 --- a/docs/api/assets/transforms_chain.svg +++ /dev/null @@ -1,12 +0,0 @@ - - -base_link - - - -camera_link - - - -camera_optical - diff --git a/docs/api/assets/transforms_modules.svg b/docs/api/assets/transforms_modules.svg deleted file mode 100644 index 08e7c309a5..0000000000 --- a/docs/api/assets/transforms_modules.svg +++ /dev/null @@ -1,20 +0,0 @@ - - -world - - - -base_link - - - -camera_link - - - -camera_optical - -RobotBaseModule - -CameraModule - diff --git a/docs/api/assets/transforms_tree.svg b/docs/api/assets/transforms_tree.svg deleted file mode 100644 index f95f1a6621..0000000000 --- a/docs/api/assets/transforms_tree.svg +++ /dev/null @@ -1,26 +0,0 @@ - - -world - - - -robot_base - - - -camera_link - - - -camera_optical -mug here - - - -arm_base - - - -gripper -target here - diff --git a/docs/development/writing_docs.md b/docs/development/writing_docs.md new file mode 100644 index 0000000000..58466d6592 --- /dev/null +++ b/docs/development/writing_docs.md @@ -0,0 +1,7 @@ +# Writing Docs + +1. Where to put your docs: + - If it only matters to people who contribute to dimos (like this doc), put them in `docs/development` + - Otherwise put them in `docs/usage` +2. Run `bin/gen_diagrams` to generate the svg's for your diagrams. We use [pikchr](https://pikchr.org/home/doc/trunk/doc/userman.md) as a diagram language. +3. Use [md-babel-py](https://github.com/leshy/md-babel-py/) (`md-babel-py run thing.md`) to make sure your code examples work. diff --git a/docs/development/writing_docs/README.md b/docs/development/writing_docs/README.md deleted file mode 100644 index abced8b706..0000000000 --- a/docs/development/writing_docs/README.md +++ /dev/null @@ -1,17 +0,0 @@ -# Writing Docs - -Note: as of the DimOS beta, not all existing docs conform to this guide, but newly added docs should. - -## Need-to-know Things - -1. Where to put your docs. - - Some docs are under `docs/` (like this one) but others are stored in the actual codebase, like `dimos/robot/drone/README.md`. - - If your docs have code examples and are somewhere under `docs/`, those code examples must be executable. See [codeblocks guide](/docs/development/writing_docs/codeblocks.md) for details and instructions on how to execute your code examples. - - If your docs nicely *introduce* a new API, or they are a tutorial, then put them in `docs/concepts/` (even if they are about a specific API). - - If the docs are highly technical or exhaustive there are a three options: - - If your docs are about a user-facing API (ex: the reader can follow your instructions without cloning dimos) then put them in `docs/api/`. - - Otherwise (if the reader is modifying their own copy of the dimos codebase) then your docs have two options: - 1. You can choose to store your docs next to relevant python files (ex: `dimos/robot/drone/README.md`), and we are less strict about the contents (code examples don't need to be executable) **BUT**, you need to edit something in `docs/development/` or `docs/api/` to add a reference/link to those docs (don't create "dangling" documentation). - 2. Alternatively, you can put your docs in `docs/development/`. Code examples there should be executable. -2. Even if you know how to link to other docs, read our [how we do doc linking guide](/docs/development/writing_docs/doclinks.md). -3. Even if you know how to create diagrams on your own, read our [how we do diagrams guide](/docs/development/writing_docs/diagram_practices.md). diff --git a/docs/development/writing_docs/assets/codeblocks_example.svg b/docs/development/writing_docs/assets/codeblocks_example.svg deleted file mode 100644 index 3ba6c37a4b..0000000000 --- a/docs/development/writing_docs/assets/codeblocks_example.svg +++ /dev/null @@ -1,47 +0,0 @@ - - - - - - - - -A - -A - - - -B - -B - - - -A->B - - - - - -C - -C - - - -A->C - - - - - -B->C - - - - - diff --git a/docs/development/writing_docs/assets/pikchr_basic.svg b/docs/development/writing_docs/assets/pikchr_basic.svg deleted file mode 100644 index 9dee0bfdec..0000000000 --- a/docs/development/writing_docs/assets/pikchr_basic.svg +++ /dev/null @@ -1,12 +0,0 @@ - - -Step 1 - - - -Step 2 - - - -Step 3 - diff --git a/docs/development/writing_docs/assets/pikchr_branch.svg b/docs/development/writing_docs/assets/pikchr_branch.svg deleted file mode 100644 index e7b2b86596..0000000000 --- a/docs/development/writing_docs/assets/pikchr_branch.svg +++ /dev/null @@ -1,16 +0,0 @@ - - -Input - - - -Process - - - -Path A - - - -Path B - diff --git a/docs/development/writing_docs/assets/pikchr_explicit.svg b/docs/development/writing_docs/assets/pikchr_explicit.svg deleted file mode 100644 index a6a913fcb4..0000000000 --- a/docs/development/writing_docs/assets/pikchr_explicit.svg +++ /dev/null @@ -1,8 +0,0 @@ - - -Step 1 - - - -Step 2 - diff --git a/docs/development/writing_docs/assets/pikchr_labels.svg b/docs/development/writing_docs/assets/pikchr_labels.svg deleted file mode 100644 index b11fe64bca..0000000000 --- a/docs/development/writing_docs/assets/pikchr_labels.svg +++ /dev/null @@ -1,5 +0,0 @@ - - -Box -label below - diff --git a/docs/development/writing_docs/assets/pikchr_sizing.svg b/docs/development/writing_docs/assets/pikchr_sizing.svg deleted file mode 100644 index 9d17f571d1..0000000000 --- a/docs/development/writing_docs/assets/pikchr_sizing.svg +++ /dev/null @@ -1,13 +0,0 @@ - - -short - - - -.subscribe() - - - -two lines -of text - diff --git a/docs/development/writing_docs/codeblocks.md b/docs/development/writing_docs/codeblocks.md deleted file mode 100644 index a928f1ceb4..0000000000 --- a/docs/development/writing_docs/codeblocks.md +++ /dev/null @@ -1,195 +0,0 @@ -# Code Blocks Must Be Executable - -We use [md-babel-py](https://github.com/leshy/md-babel-py/) to execute code blocks in markdown and insert results. - -## Golden Rule - -**Never write illustrative/pseudo code blocks.** If you're showing an API usage pattern, create a minimal working example that actually runs. This ensures documentation stays correct as the codebase evolves. - -## Installation - -
-Click to see full installation instructions - -### Nix (recommended) - -```sh skip -# (assuming you have nix) - -# Run directly from GitHub -nix run github:leshy/md-babel-py -- run README.md --stdout - -# run locally -nix run . -- run README.md --stdout -``` - -### Docker - -```sh skip -# Pull from Docker Hub -docker run -v $(pwd):/work lesh/md-babel-py:main run /work/README.md --stdout - -# Or build locally via Nix -nix build '.#docker' # builds tarball to ./result -docker load < result # loads image from tarball -docker run -v $(pwd):/work md-babel-py:latest run /work/file.md --stdout -``` - -### pipx - -```sh skip -pipx install md-babel-py -# or: uv pip install md-babel-py -md-babel-py run README.md --stdout -``` - -If not using nix or docker, evaluators require system dependencies: - -| Language | System packages | -|-----------|-----------------------------| -| python | python3 | -| node | nodejs | -| dot | graphviz | -| asymptote | asymptote, texlive, dvisvgm | -| pikchr | pikchr | -| openscad | openscad, xvfb, imagemagick | -| diagon | diagon | - -```sh skip -# Arch Linux -sudo pacman -S python nodejs graphviz asymptote texlive-basic openscad xorg-server-xvfb imagemagick - -# Debian/Ubuntu -sudo apt-get install python3 nodejs graphviz asymptote texlive xvfb imagemagick openscad -``` - -Note: pikchr and diagon may need to be built from source. Use Docker or Nix for full evaluator support. - -## Usage - -```sh skip -# Edit file in-place -md-babel-py run document.md - -# Output to separate file -md-babel-py run document.md --output result.md - -# Print to stdout -md-babel-py run document.md --stdout - -# Only run specific languages -md-babel-py run document.md --lang python,sh - -# Dry run - show what would execute -md-babel-py run document.md --dry-run -``` - -
- - -## Running - -```sh skip -md-babel-py run document.md # edit in-place -md-babel-py run document.md --stdout # preview to stdout -md-babel-py run document.md --dry-run # show what would run -``` - -## Supported Languages - -Python, Shell (sh), Node.js, plus visualization: Matplotlib, Graphviz, Pikchr, Asymptote, OpenSCAD, Diagon. - -## Code Block Flags - -Add flags after the language identifier: - -| Flag | Effect | -|------|--------| -| `session=NAME` | Share state between blocks with same session name | -| `output=path.png` | Write output to file instead of inline | -| `no-result` | Execute but don't insert result | -| `skip` | Don't execute this block | -| `expected-error` | Block is expected to fail | - -## Examples - -# md-babel-py - -Execute code blocks in markdown files and insert the results. - -![Demo](assets/screencast.gif) - -**Use cases:** -- Keep documentation examples up-to-date automatically -- Validate code snippets in docs actually work -- Generate diagrams and charts from code in markdown -- Literate programming with executable documentation - -## Languages - -### Shell - -```sh -echo "cwd: $(pwd)" -``` - - -``` -cwd: /work -``` - -### Python - -```python session=example -a = "hello world" -print(a) -``` - - -``` -hello world -``` - -Sessions preserve state between code blocks: - -```python session=example -print(a, "again") -``` - - -``` -hello world again -``` - -### Node.js - -```node -console.log("Hello from Node.js"); -console.log(`Node version: ${process.version}`); -``` - - -``` -Hello from Node.js -Node version: v22.21.1 -``` - -### Matplotlib - -```python output=assets/matplotlib-demo.svg -import matplotlib.pyplot as plt -import numpy as np -plt.style.use('dark_background') -x = np.linspace(0, 4 * np.pi, 200) -plt.figure(figsize=(8, 4)) -plt.plot(x, np.sin(x), label='sin(x)', linewidth=2) -plt.plot(x, np.cos(x), label='cos(x)', linewidth=2) -plt.xlabel('x') -plt.ylabel('y') -plt.legend() -plt.grid(alpha=0.3) -plt.savefig('{output}', transparent=True) -``` - - -![output](assets/matplotlib-demo.svg) diff --git a/docs/development/writing_docs/diagram_practices.md b/docs/development/writing_docs/diagram_practices.md deleted file mode 100644 index 81f3da73a5..0000000000 --- a/docs/development/writing_docs/diagram_practices.md +++ /dev/null @@ -1,146 +0,0 @@ -We have many diagramming tools. View source code of this page to see examples. - -# How to make diagrams - -1. First define a diagram using a codeblock (examples below). See [Pikchr](https://pikchr.org/) for more details on syntax. -2. Then use the cli tool `md-babel-py` (ex: `md-babel-py run README.md`) to generate the diagram. See [codeblocks.md](/docs/development/writing_docs/codeblocks.md) for how to get the `md-babel-py` cli tool. - -# Pikchr - -[Pikchr](https://pikchr.org/) is a diagram language from SQLite. Use it for flowcharts and architecture diagrams. - -**Important:** Always wrap pikchr blocks in `
` tags so the source is collapsed by default on GitHub. The rendered SVG stays visible outside the fold. Code blocks (Python, etc.) should NOT be folded—they're meant to be read. - -## Basic syntax - -
-diagram source - -```pikchr fold output=assets/pikchr_basic.svg -color = white -fill = none - -A: box "Step 1" rad 5px fit wid 170% ht 170% -arrow right 0.3in -B: box "Step 2" rad 5px fit wid 170% ht 170% -arrow right 0.3in -C: box "Step 3" rad 5px fit wid 170% ht 170% -``` - -
- - -![output](assets/pikchr_basic.svg) - -## Box sizing - -Use `fit` with percentage scaling to auto-size boxes with padding: - -
-diagram source - -```pikchr fold output=assets/pikchr_sizing.svg -color = white -fill = none - -# fit wid 170% ht 170% = auto-size + padding -A: box "short" rad 5px fit wid 170% ht 170% -arrow right 0.3in -B: box ".subscribe()" rad 5px fit wid 170% ht 170% -arrow right 0.3in -C: box "two lines" "of text" rad 5px fit wid 170% ht 170% -``` - -
- - -![output](assets/pikchr_sizing.svg) - -The pattern `fit wid 170% ht 170%` means: auto-size to text, then scale width by 170% and height by 170%. - -For explicit sizing (when you need consistent box sizes): - -
-diagram source - -```pikchr fold output=assets/pikchr_explicit.svg -color = white -fill = none - -A: box "Step 1" rad 5px fit wid 170% ht 170% -arrow right 0.3in -B: box "Step 2" rad 5px fit wid 170% ht 170% -``` - -
- - -![output](assets/pikchr_explicit.svg) - -## Common settings - -Always start with: - -``` -color = white # text color -fill = none # transparent box fill -``` - -## Branching paths - -
-diagram source - -```pikchr fold output=assets/pikchr_branch.svg -color = white -fill = none - -A: box "Input" rad 5px fit wid 170% ht 170% -arrow -B: box "Process" rad 5px fit wid 170% ht 170% - -# Branch up -arrow from B.e right 0.3in then up 0.35in then right 0.3in -C: box "Path A" rad 5px fit wid 170% ht 170% - -# Branch down -arrow from B.e right 0.3in then down 0.35in then right 0.3in -D: box "Path B" rad 5px fit wid 170% ht 170% -``` - -
- - -![output](assets/pikchr_branch.svg) - -**Tip:** For tree/hierarchy diagrams, prefer left-to-right layout (root on left, children branching right). This reads more naturally and avoids awkward vertical stacking. - -## Adding labels - -
-diagram source - -```pikchr fold output=assets/pikchr_labels.svg -color = white -fill = none - -A: box "Box" rad 5px fit wid 170% ht 170% -text "label below" at (A.x, A.y - 0.4in) -``` - -
- - -![output](assets/pikchr_labels.svg) - -## Reference - -| Element | Syntax | -|---------|--------| -| Box | `box "text" rad 5px wid Xin ht Yin` | -| Arrow | `arrow right 0.3in` | -| Oval | `oval "text" wid Xin ht Yin` | -| Text | `text "label" at (X, Y)` | -| Named point | `A: box ...` then reference `A.e`, `A.n`, `A.x`, `A.y` | - -See [pikchr.org/home/doc/trunk/doc/userman.md](https://pikchr.org/home/doc/trunk/doc/userman.md) for full documentation. diff --git a/docs/development/writing_docs/doclinks.md b/docs/development/writing_docs/doclinks.md deleted file mode 100644 index e9a6ee9d8c..0000000000 --- a/docs/development/writing_docs/doclinks.md +++ /dev/null @@ -1,119 +0,0 @@ -# Use Doclinks to Resolve file references - -## Syntax - - -| Pattern | Example | -|-------------|-----------------------------------------------------| -| Code file | `[`service/spec.py`]()` → resolves path | -| With symbol | `Configurable` in `[`spec.py`]()` → adds `#L` | -| Doc link | `[Configuration](.md)` → resolves to doc | - - -## Usage - -```bash -bin/doclinks docs/guide.md # single file -bin/doclinks docs/ # directory -bin/doclinks --dry-run ... # preview only -``` - -## Full Documentation - -
-Click to see full documentation - -## What it does - -When writing docs, you can use placeholder links like: - - -```markdown -See [`service/spec.py`]() for the implementation. -``` - - -Running `doclinks` resolves these to actual paths: - - -```markdown -See [`service/spec.py`](/dimos/protocol/service/spec.py) for the implementation. -``` - - -## Features - - -- **Code file links**: `[`filename.py`]()` resolves to the file's path -- **Symbol line linking**: If another backticked term appears on the same line, it finds that symbol in the file and adds `#L`: - ```markdown - See `Configurable` in [`config.py`]() - → [`config.py`](/path/config.py#L42) - ``` -- **Doc-to-doc links**: `[Modules](.md)` resolves to `modules.md` or `modules/index.md` - -- **Multiple link modes**: absolute, relative, or GitHub URLs -- **Watch mode**: Automatically re-process on file changes -- **Ignore regions**: Skip sections with `` comments - -## Usage - -```bash -# Process a single file -bin/doclinks docs/guide.md - -# Process a directory recursively -bin/doclinks docs/ - -# Relative links (from doc location) -bin/doclinks --link-mode relative docs/ - -# GitHub links -bin/doclinks --link-mode github \ - --github-url https://github.com/org/repo docs/ - -# Dry run (preview changes) -bin/doclinks --dry-run docs/ - -# CI check (exit 1 if changes needed) -bin/doclinks --check docs/ - -# Watch mode (auto-update on changes) -bin/doclinks --watch docs/ -``` - -## Options - -| Option | Description | -|--------------------|-------------------------------------------------| -| `--root PATH` | Repository root (default: auto-detect git root) | -| `--link-mode MODE` | `absolute` (default), `relative`, or `github` | -| `--github-url URL` | Base GitHub URL (required for github mode) | -| `--github-ref REF` | Branch/ref for GitHub links (default: `main`) | -| `--dry-run` | Show changes without modifying files | -| `--check` | Exit with error if changes needed (for CI) | -| `--watch` | Watch for changes and re-process | - -## Link patterns - - -| Pattern | Description | -|----------------------|------------------------------------------------| -| `[`file.py`]()` | Code file reference (empty or any link) | -| `[`path/file.py`]()` | Code file with partial path for disambiguation | -| `[`file.py`](#L42)` | Preserves existing line fragments | -| `[Doc Name](.md)` | Doc-to-doc link (resolves by name) | - - -## How resolution works - -The tool builds an index of all files in the repo. For `/dimos/protocol/service/spec.py`, it creates lookup entries for: - -- `spec.py` -- `service/spec.py` -- `protocol/service/spec.py` -- `dimos/protocol/service/spec.py` - -Use longer paths when multiple files share the same name. - -
diff --git a/docs/concepts/README.md b/docs/usage/README.md similarity index 100% rename from docs/concepts/README.md rename to docs/usage/README.md diff --git a/docs/concepts/assets/abstraction_layers.svg b/docs/usage/assets/abstraction_layers.svg similarity index 100% rename from docs/concepts/assets/abstraction_layers.svg rename to docs/usage/assets/abstraction_layers.svg diff --git a/docs/concepts/assets/camera_module.svg b/docs/usage/assets/camera_module.svg similarity index 100% rename from docs/concepts/assets/camera_module.svg rename to docs/usage/assets/camera_module.svg diff --git a/docs/concepts/assets/go2_agentic.svg b/docs/usage/assets/go2_agentic.svg similarity index 100% rename from docs/concepts/assets/go2_agentic.svg rename to docs/usage/assets/go2_agentic.svg diff --git a/docs/concepts/assets/go2_nav.svg b/docs/usage/assets/go2_nav.svg similarity index 100% rename from docs/concepts/assets/go2_nav.svg rename to docs/usage/assets/go2_nav.svg diff --git a/docs/concepts/assets/lcmspy.png b/docs/usage/assets/lcmspy.png similarity index 100% rename from docs/concepts/assets/lcmspy.png rename to docs/usage/assets/lcmspy.png diff --git a/docs/concepts/assets/pubsub_benchmark.png b/docs/usage/assets/pubsub_benchmark.png similarity index 100% rename from docs/concepts/assets/pubsub_benchmark.png rename to docs/usage/assets/pubsub_benchmark.png diff --git a/docs/concepts/blueprints.md b/docs/usage/blueprints.md similarity index 100% rename from docs/concepts/blueprints.md rename to docs/usage/blueprints.md diff --git a/docs/api/configuration.md b/docs/usage/configuration.md similarity index 100% rename from docs/api/configuration.md rename to docs/usage/configuration.md diff --git a/docs/concepts/lcm.md b/docs/usage/lcm.md similarity index 100% rename from docs/concepts/lcm.md rename to docs/usage/lcm.md diff --git a/docs/concepts/modules.md b/docs/usage/modules.md similarity index 100% rename from docs/concepts/modules.md rename to docs/usage/modules.md diff --git a/docs/api/sensor_streams/README.md b/docs/usage/sensor_streams/README.md similarity index 100% rename from docs/api/sensor_streams/README.md rename to docs/usage/sensor_streams/README.md diff --git a/docs/api/sensor_streams/advanced_streams.md b/docs/usage/sensor_streams/advanced_streams.md similarity index 100% rename from docs/api/sensor_streams/advanced_streams.md rename to docs/usage/sensor_streams/advanced_streams.md diff --git a/docs/api/sensor_streams/assets/alignment_flow.svg b/docs/usage/sensor_streams/assets/alignment_flow.svg similarity index 100% rename from docs/api/sensor_streams/assets/alignment_flow.svg rename to docs/usage/sensor_streams/assets/alignment_flow.svg diff --git a/docs/api/sensor_streams/assets/alignment_overview.svg b/docs/usage/sensor_streams/assets/alignment_overview.svg similarity index 100% rename from docs/api/sensor_streams/assets/alignment_overview.svg rename to docs/usage/sensor_streams/assets/alignment_overview.svg diff --git a/docs/api/sensor_streams/assets/alignment_timeline.png b/docs/usage/sensor_streams/assets/alignment_timeline.png similarity index 100% rename from docs/api/sensor_streams/assets/alignment_timeline.png rename to docs/usage/sensor_streams/assets/alignment_timeline.png diff --git a/docs/api/sensor_streams/assets/alignment_timeline2.png b/docs/usage/sensor_streams/assets/alignment_timeline2.png similarity index 100% rename from docs/api/sensor_streams/assets/alignment_timeline2.png rename to docs/usage/sensor_streams/assets/alignment_timeline2.png diff --git a/docs/api/sensor_streams/assets/alignment_timeline3.png b/docs/usage/sensor_streams/assets/alignment_timeline3.png similarity index 100% rename from docs/api/sensor_streams/assets/alignment_timeline3.png rename to docs/usage/sensor_streams/assets/alignment_timeline3.png diff --git a/docs/api/sensor_streams/assets/backpressure.svg b/docs/usage/sensor_streams/assets/backpressure.svg similarity index 100% rename from docs/api/sensor_streams/assets/backpressure.svg rename to docs/usage/sensor_streams/assets/backpressure.svg diff --git a/docs/api/sensor_streams/assets/backpressure_solution.svg b/docs/usage/sensor_streams/assets/backpressure_solution.svg similarity index 100% rename from docs/api/sensor_streams/assets/backpressure_solution.svg rename to docs/usage/sensor_streams/assets/backpressure_solution.svg diff --git a/docs/api/sensor_streams/assets/frame_mosaic.jpg b/docs/usage/sensor_streams/assets/frame_mosaic.jpg similarity index 100% rename from docs/api/sensor_streams/assets/frame_mosaic.jpg rename to docs/usage/sensor_streams/assets/frame_mosaic.jpg diff --git a/docs/api/sensor_streams/assets/frame_mosaic2.jpg b/docs/usage/sensor_streams/assets/frame_mosaic2.jpg similarity index 100% rename from docs/api/sensor_streams/assets/frame_mosaic2.jpg rename to docs/usage/sensor_streams/assets/frame_mosaic2.jpg diff --git a/docs/api/sensor_streams/assets/getter_hot_cold.svg b/docs/usage/sensor_streams/assets/getter_hot_cold.svg similarity index 100% rename from docs/api/sensor_streams/assets/getter_hot_cold.svg rename to docs/usage/sensor_streams/assets/getter_hot_cold.svg diff --git a/docs/api/sensor_streams/assets/observable_flow.svg b/docs/usage/sensor_streams/assets/observable_flow.svg similarity index 100% rename from docs/api/sensor_streams/assets/observable_flow.svg rename to docs/usage/sensor_streams/assets/observable_flow.svg diff --git a/docs/api/sensor_streams/assets/sharpness_graph.svg b/docs/usage/sensor_streams/assets/sharpness_graph.svg similarity index 100% rename from docs/api/sensor_streams/assets/sharpness_graph.svg rename to docs/usage/sensor_streams/assets/sharpness_graph.svg diff --git a/docs/api/sensor_streams/assets/sharpness_graph2.svg b/docs/usage/sensor_streams/assets/sharpness_graph2.svg similarity index 100% rename from docs/api/sensor_streams/assets/sharpness_graph2.svg rename to docs/usage/sensor_streams/assets/sharpness_graph2.svg diff --git a/docs/api/sensor_streams/quality_filter.md b/docs/usage/sensor_streams/quality_filter.md similarity index 100% rename from docs/api/sensor_streams/quality_filter.md rename to docs/usage/sensor_streams/quality_filter.md diff --git a/docs/api/sensor_streams/reactivex.md b/docs/usage/sensor_streams/reactivex.md similarity index 100% rename from docs/api/sensor_streams/reactivex.md rename to docs/usage/sensor_streams/reactivex.md diff --git a/docs/api/sensor_streams/storage_replay.md b/docs/usage/sensor_streams/storage_replay.md similarity index 100% rename from docs/api/sensor_streams/storage_replay.md rename to docs/usage/sensor_streams/storage_replay.md diff --git a/docs/api/sensor_streams/temporal_alignment.md b/docs/usage/sensor_streams/temporal_alignment.md similarity index 100% rename from docs/api/sensor_streams/temporal_alignment.md rename to docs/usage/sensor_streams/temporal_alignment.md diff --git a/docs/api/transforms.md b/docs/usage/transforms.md similarity index 100% rename from docs/api/transforms.md rename to docs/usage/transforms.md diff --git a/docs/concepts/transports.md b/docs/usage/transports.md similarity index 100% rename from docs/concepts/transports.md rename to docs/usage/transports.md diff --git a/docs/api/visualization.md b/docs/usage/visualization.md similarity index 100% rename from docs/api/visualization.md rename to docs/usage/visualization.md From 45f382a1a8942c7e9a925872706e0a57e2212452 Mon Sep 17 00:00:00 2001 From: Jeff Hykin Date: Thu, 12 Feb 2026 23:57:32 -0800 Subject: [PATCH 002/140] fix renamed references --- README.md | 4 ++-- dimos/utils/docs/doclinks.py | 4 ++-- dimos/utils/docs/test_doclinks.py | 6 +++--- dimos/visualization/rerun/bridge.py | 2 +- docs/development/README.md | 2 +- docs/development/depth_camera_integration.md | 4 ++-- docs/usage/README.md | 12 ++++++------ docs/usage/configuration.md | 2 +- docs/usage/modules.md | 4 ++-- docs/usage/sensor_streams/quality_filter.md | 2 +- docs/usage/transforms.md | 4 ++-- docs/usage/transports.md | 6 +++--- examples/simplerobot/README.md | 2 +- 13 files changed, 27 insertions(+), 27 deletions(-) diff --git a/README.md b/README.md index 2c5242a0e6..0a693f35ab 100644 --- a/README.md +++ b/README.md @@ -242,8 +242,8 @@ DimOS comes with a number of monitoring tools: # Documentation Concepts: -- [Modules](/docs/concepts/modules.md): The building blocks of DimOS, modules run in parallel and are singleton python classes. -- [Streams](/docs/api/sensor_streams/index.md): How modules communicate, a Pub / Sub system. +- [Modules](/docs/usage/modules.md): The building blocks of DimOS, modules run in parallel and are singleton python classes. +- [Streams](/docs/usage/sensor_streams/index.md): How modules communicate, a Pub / Sub system. - [Blueprints](/dimos/core/README_BLUEPRINTS.md): a way to group modules together and define their connections to each other. - [RPC](/dimos/core/README_BLUEPRINTS.md#calling-the-methods-of-other-modules): how one module can call a method on another module (arguments get serialized to JSON-like binary data). - [Skills](/dimos/core/README_BLUEPRINTS.md#defining-skills): An RPC function, except it can be called by an AI agent (a tool for an AI). diff --git a/dimos/utils/docs/doclinks.py b/dimos/utils/docs/doclinks.py index 74a9349eca..c04fe7ef16 100644 --- a/dimos/utils/docs/doclinks.py +++ b/dimos/utils/docs/doclinks.py @@ -106,8 +106,8 @@ def build_doc_index(root: Path) -> dict[str, list[Path]]: """ Build an index mapping lowercase doc names to .md file paths. - For docs/concepts/modules.md, creates entry: - - "modules" -> [Path("docs/concepts/modules.md")] + For docs/usage/modules.md, creates entry: + - "modules" -> [Path("docs/usage/modules.md")] Also indexes directory index files: - "modules" -> [Path("docs/modules/index.md")] (if modules/index.md exists) diff --git a/dimos/utils/docs/test_doclinks.py b/dimos/utils/docs/test_doclinks.py index 016cc30113..7e40a5ad28 100644 --- a/dimos/utils/docs/test_doclinks.py +++ b/dimos/utils/docs/test_doclinks.py @@ -256,7 +256,7 @@ def test_github_mode(self, file_index): def test_relative_mode(self, file_index): """Should generate relative paths in relative mode.""" content = "See [`service/spec.py`]()" - doc_path = REPO_ROOT / "docs/concepts/test.md" + doc_path = REPO_ROOT / "docs/usage/test.md" new_content, _changes, _errors = process_markdown( content, @@ -350,7 +350,7 @@ def test_doc_link_github_mode(self, file_index, doc_index): def test_doc_link_relative_mode(self, file_index, doc_index): """Should generate relative paths for doc links.""" content = "See [Blueprints](.md)" - doc_path = REPO_ROOT / "docs/api/test.md" + doc_path = REPO_ROOT / "docs/usage/test.md" new_content, _changes, errors = process_markdown( content, @@ -364,7 +364,7 @@ def test_doc_link_relative_mode(self, file_index, doc_index): ) assert len(errors) == 0 - # Should be relative path from docs/concepts/ to docs/ + # Should be relative path from docs/usage/ to docs/ assert "../" in new_content def test_doc_not_found_error(self, file_index, doc_index): diff --git a/dimos/visualization/rerun/bridge.py b/dimos/visualization/rerun/bridge.py index 5263e59a44..dff6a01560 100644 --- a/dimos/visualization/rerun/bridge.py +++ b/dimos/visualization/rerun/bridge.py @@ -75,7 +75,7 @@ # This is easy to reconstruct but a service/tf.py already does this so should be integrated here # # we have decoupled entity paths and actual transforms (like ROS TF frames) -# https://rerun.io/docs/concepts/logging-and-ingestion/transforms +# https://rerun.io/docs/usage/logging-and-ingestion/transforms # # tf#/world # tf#/base_link diff --git a/docs/development/README.md b/docs/development/README.md index 0e5a4a2021..7394f8a6dc 100644 --- a/docs/development/README.md +++ b/docs/development/README.md @@ -264,7 +264,7 @@ You can enable a tag by selecting -m - these are configured in `./pyp - Open the PR against the `dev` branch (not `main`). - **No matter what, provide a few-lines that, when run, let a reviewer test the feature you added** (assuming you changed functional python code). - Less changed files = better. -- If you're writing documentation, see [writing docs](/docs/development/writing_docs/README.md) +- If you're writing documentation, see [writing docs](/docs/development/writing_docs.md) - If you get mypy errors, please fix them. Don't just add # type: ignore. Please first understand why mypy is complaining and try to fix it. It's only okay to ignore if the issue cannot be fixed. - If you made a change that is likely going to involve a debate, open the github UI and add a graphical comment on that code. Justify your choice and explain downsides of alternatives. - We don't require 100% test coverage, but if you're making a PR of notable python changes you should probably either have unit tests or good reason why not (ex: visualization stuff is hard to test so we don't). diff --git a/docs/development/depth_camera_integration.md b/docs/development/depth_camera_integration.md index 3ff162d646..a52c860162 100644 --- a/docs/development/depth_camera_integration.md +++ b/docs/development/depth_camera_integration.md @@ -143,5 +143,5 @@ Install Foxglove from: - **Skills** are callable methods (decorated with `@skill`) exposed by `SkillModule` for agents. Reference: -- Modules overview: `/docs/concepts/modules.md` -- TF fundamentals: `/docs/api/transforms.md` +- Modules overview: `/docs/usage/modules.md` +- TF fundamentals: `/docs/usage/transforms.md` diff --git a/docs/usage/README.md b/docs/usage/README.md index 0f82783099..315fdbb1c2 100644 --- a/docs/usage/README.md +++ b/docs/usage/README.md @@ -1,12 +1,12 @@ # Concepts -This page explains general concepts. For specific API docs see [the API reference](/docs/api/README.md). +This page explains general concepts. For specific API docs see [the API reference](/docs/usage/README.md). ## Table of Contents -- [Modules](/docs/concepts/modules.md): The primary units of deployment in DimOS, modules run in parallel and are python classes. -- [Streams](/docs/api/sensor_streams/README.md): How modules communicate, a Pub / Sub system. -- [Blueprints](/docs/concepts/blueprints.md): a way to group modules together and define their connections to each other. -- [RPC](/docs/concepts/blueprints.md#calling-the-methods-of-other-modules): how one module can call a method on another module (arguments get serialized to JSON-like binary data). -- [Skills](/docs/concepts/blueprints.md#defining-skills): An RPC function, except it can be called by an AI agent (a tool for an AI). +- [Modules](/docs/usage/modules.md): The primary units of deployment in DimOS, modules run in parallel and are python classes. +- [Streams](/docs/usage/sensor_streams/README.md): How modules communicate, a Pub / Sub system. +- [Blueprints](/docs/usage/blueprints.md): a way to group modules together and define their connections to each other. +- [RPC](/docs/usage/blueprints.md#calling-the-methods-of-other-modules): how one module can call a method on another module (arguments get serialized to JSON-like binary data). +- [Skills](/docs/usage/blueprints.md#defining-skills): An RPC function, except it can be called by an AI agent (a tool for an AI). - Agents: AI that has an objective, access to stream data, and is capable of calling skills as tools. diff --git a/docs/usage/configuration.md b/docs/usage/configuration.md index 162c343ffa..eaad4a9271 100644 --- a/docs/usage/configuration.md +++ b/docs/usage/configuration.md @@ -45,7 +45,7 @@ Error: Config.__init__() got an unexpected keyword argument 'something' # Configurable Modules -[Modules](/docs/concepts/modules.md) inherit from `Configurable`, so all of the above applies. Module configs should inherit from `ModuleConfig` ([`core/module.py`](/dimos/core/module.py#L40)), which includes shared configuration for all modules like transport protocols, frame IDs, etc. +[Modules](/docs/usage/modules.md) inherit from `Configurable`, so all of the above applies. Module configs should inherit from `ModuleConfig` ([`core/module.py`](/dimos/core/module.py#L40)), which includes shared configuration for all modules like transport protocols, frame IDs, etc. ```python from dataclasses import dataclass diff --git a/docs/usage/modules.md b/docs/usage/modules.md index 344efa0774..3b6e482555 100644 --- a/docs/usage/modules.md +++ b/docs/usage/modules.md @@ -60,7 +60,7 @@ We can see that the camera module outputs two streams: It offers two RPC calls: `start()` and `stop()` (lifecycle methods). -It also exposes an agentic [skill](/docs/concepts/blueprints.md#defining-skills) called `video_stream` (more on skills in the Blueprints guide). +It also exposes an agentic [skill](/docs/usage/blueprints.md#defining-skills) called `video_stream` (more on skills in the Blueprints guide). We can start this module and explore the output of its streams in real time (this will use your webcam). @@ -176,4 +176,4 @@ to_svg(agentic, "assets/go2_agentic.svg") ![output](assets/go2_agentic.svg) -To see more information on how to use Blueprints, see [Blueprints](/docs/concepts/blueprints.md). +To see more information on how to use Blueprints, see [Blueprints](/docs/usage/blueprints.md). diff --git a/docs/usage/sensor_streams/quality_filter.md b/docs/usage/sensor_streams/quality_filter.md index c0bbfc10a3..db21da9c54 100644 --- a/docs/usage/sensor_streams/quality_filter.md +++ b/docs/usage/sensor_streams/quality_filter.md @@ -50,7 +50,7 @@ Qualities: [0.9] For camera streams, we provide `sharpness_barrier` which uses the image's sharpness score. -Let's use real camera data from the Unitree Go2 robot to demonstrate. We use the [Sensor Storage & Replay](/docs/api/sensor_streams/storage_replay.md) toolkit, which provides access to recorded robot data: +Let's use real camera data from the Unitree Go2 robot to demonstrate. We use the [Sensor Storage & Replay](/docs/usage/sensor_streams/storage_replay.md) toolkit, which provides access to recorded robot data: ```python session=qb from dimos.utils.testing import TimedSensorReplay diff --git a/docs/usage/transforms.md b/docs/usage/transforms.md index b64b133dea..2435839feb 100644 --- a/docs/usage/transforms.md +++ b/docs/usage/transforms.md @@ -465,5 +465,5 @@ For the mathematical foundations, the ROS documentation provides detailed backgr - [ROS REP 105 - Coordinate Frames for Mobile Platforms](https://www.ros.org/reps/rep-0105.html) See also: -- [Modules](/docs/concepts/modules/index.md) for understanding the module system -- [Configuration](/docs/concepts/configuration.md) for module configuration patterns +- [Modules](/docs/usage/modules.md) for understanding the module system +- [Configuration](/docs/usage/configuration.md) for module configuration patterns diff --git a/docs/usage/transports.md b/docs/usage/transports.md index e4b62b01ce..39c3a9cc66 100644 --- a/docs/usage/transports.md +++ b/docs/usage/transports.md @@ -196,7 +196,7 @@ Encoding is an implementation detail, but we encourage using LCM-compatible mess ### Encoding helpers -Many of our message types provide `lcm_encode` / `lcm_decode` for compact, language-agnostic binary encoding (often faster than pickle). For details, see [LCM](/docs/concepts/lcm.md). +Many of our message types provide `lcm_encode` / `lcm_decode` for compact, language-agnostic binary encoding (often faster than pickle). For details, see [LCM](/docs/usage/lcm.md). --- @@ -230,7 +230,7 @@ print(inspect.getsource(PubSub.subscribe)) ... ``` -Topic/message types are flexible: bytes, JSON, or our ROS-compatible [LCM](/docs/concepts/lcm.md) types. We also have pickle-based transports for arbitrary Python objects. +Topic/message types are flexible: bytes, JSON, or our ROS-compatible [LCM](/docs/usage/lcm.md) types. We also have pickle-based transports for arbitrary Python objects. ### LCM (UDP multicast) @@ -337,7 +337,7 @@ Transports often need to serialize messages before sending and deserialize after | `LCMEncoderMixin` | LCM binary | Cross-language (C/C++/Python/Go/…) | | `JpegEncoderMixin` | JPEG compressed | Image data, reduces bandwidth | -`LCMEncoderMixin` is especially useful: you can use LCM message definitions with *any* transport (not just UDP multicast). See [LCM](/docs/concepts/lcm.md) for details. +`LCMEncoderMixin` is especially useful: you can use LCM message definitions with *any* transport (not just UDP multicast). See [LCM](/docs/usage/lcm.md) for details. ### Creating a custom mixin diff --git a/examples/simplerobot/README.md b/examples/simplerobot/README.md index bc6686f77c..8c7b6dfbc7 100644 --- a/examples/simplerobot/README.md +++ b/examples/simplerobot/README.md @@ -11,7 +11,7 @@ A minimal virtual robot for testing and development. It implements some of the s Physical robots typically publish multiple poses in a relationship as `TransformStamped` in a TF tree, while SimpleRobot publishes `PoseStamped` directly for simplicity. -For details on this check [Transforms](/docs/api/transforms.md) +For details on this check [Transforms](/docs/usage/transforms.md) ## Usage From a82a89c474383ec16228059f30c34697457fefd8 Mon Sep 17 00:00:00 2001 From: Jeff Hykin Date: Thu, 12 Feb 2026 23:59:27 -0800 Subject: [PATCH 003/140] add missing assets --- docs/usage/assets/transforms.png | 3 +++ docs/usage/assets/transforms_chain.svg | 12 +++++++++++ docs/usage/assets/transforms_modules.svg | 20 ++++++++++++++++++ docs/usage/assets/transforms_tree.svg | 26 ++++++++++++++++++++++++ 4 files changed, 61 insertions(+) create mode 100644 docs/usage/assets/transforms.png create mode 100644 docs/usage/assets/transforms_chain.svg create mode 100644 docs/usage/assets/transforms_modules.svg create mode 100644 docs/usage/assets/transforms_tree.svg diff --git a/docs/usage/assets/transforms.png b/docs/usage/assets/transforms.png new file mode 100644 index 0000000000..49dba4ab9a --- /dev/null +++ b/docs/usage/assets/transforms.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:6597e0008197902e321a3ad3dfb1e838f860fa7ca1277c369ed6ff7da8bf757d +size 101102 diff --git a/docs/usage/assets/transforms_chain.svg b/docs/usage/assets/transforms_chain.svg new file mode 100644 index 0000000000..3f6c21741b --- /dev/null +++ b/docs/usage/assets/transforms_chain.svg @@ -0,0 +1,12 @@ + + +base_link + + + +camera_link + + + +camera_optical + diff --git a/docs/usage/assets/transforms_modules.svg b/docs/usage/assets/transforms_modules.svg new file mode 100644 index 0000000000..08e7c309a5 --- /dev/null +++ b/docs/usage/assets/transforms_modules.svg @@ -0,0 +1,20 @@ + + +world + + + +base_link + + + +camera_link + + + +camera_optical + +RobotBaseModule + +CameraModule + diff --git a/docs/usage/assets/transforms_tree.svg b/docs/usage/assets/transforms_tree.svg new file mode 100644 index 0000000000..f95f1a6621 --- /dev/null +++ b/docs/usage/assets/transforms_tree.svg @@ -0,0 +1,26 @@ + + +world + + + +robot_base + + + +camera_link + + + +camera_optical +mug here + + + +arm_base + + + +gripper +target here + From 8adfdfc61463f924f4b90cb2b6abfa12e79e1474 Mon Sep 17 00:00:00 2001 From: Jeff Hykin Date: Fri, 13 Feb 2026 00:23:05 -0800 Subject: [PATCH 004/140] fix doclink tests --- dimos/utils/docs/test_doclinks.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/dimos/utils/docs/test_doclinks.py b/dimos/utils/docs/test_doclinks.py index 7e40a5ad28..f1303a2245 100644 --- a/dimos/utils/docs/test_doclinks.py +++ b/dimos/utils/docs/test_doclinks.py @@ -364,8 +364,8 @@ def test_doc_link_relative_mode(self, file_index, doc_index): ) assert len(errors) == 0 - # Should be relative path from docs/usage/ to docs/ - assert "../" in new_content + # Should be relative path from docs/usage/ to target doc + assert "[Blueprints](blueprints.md)" in new_content def test_doc_not_found_error(self, file_index, doc_index): """Should error when doc doesn't exist.""" From 8df41cd32f7dc8c223cd3fd4529cdfd41688d3e8 Mon Sep 17 00:00:00 2001 From: Jeff Hykin Date: Fri, 13 Feb 2026 02:33:41 -0600 Subject: [PATCH 005/140] Update docs/usage/README.md Co-authored-by: greptile-apps[bot] <165735046+greptile-apps[bot]@users.noreply.github.com> --- docs/usage/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/usage/README.md b/docs/usage/README.md index 315fdbb1c2..071b6fc0b2 100644 --- a/docs/usage/README.md +++ b/docs/usage/README.md @@ -1,6 +1,6 @@ # Concepts -This page explains general concepts. For specific API docs see [the API reference](/docs/usage/README.md). +This page explains general concepts. ## Table of Contents From d321d9353a54a0650407a18a67eeec4ea97f8d89 Mon Sep 17 00:00:00 2001 From: Jeff Hykin Date: Fri, 13 Feb 2026 00:34:13 -0800 Subject: [PATCH 006/140] - --- dimos/visualization/rerun/bridge.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/dimos/visualization/rerun/bridge.py b/dimos/visualization/rerun/bridge.py index dff6a01560..5263e59a44 100644 --- a/dimos/visualization/rerun/bridge.py +++ b/dimos/visualization/rerun/bridge.py @@ -75,7 +75,7 @@ # This is easy to reconstruct but a service/tf.py already does this so should be integrated here # # we have decoupled entity paths and actual transforms (like ROS TF frames) -# https://rerun.io/docs/usage/logging-and-ingestion/transforms +# https://rerun.io/docs/concepts/logging-and-ingestion/transforms # # tf#/world # tf#/base_link From 9c9e4f91f98e7970eb10a92ff5557e47c567ff5d Mon Sep 17 00:00:00 2001 From: Ivan Nikolic Date: Sat, 14 Feb 2026 17:55:10 +0800 Subject: [PATCH 007/140] testing inline ascii art --- NEWREADME.MD | 46 ++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 46 insertions(+) create mode 100644 NEWREADME.MD diff --git a/NEWREADME.MD b/NEWREADME.MD new file mode 100644 index 0000000000..178b7a836c --- /dev/null +++ b/NEWREADME.MD @@ -0,0 +1,46 @@ +
+
+          ██████╗ ██╗███╗   ███╗███████╗███╗   ██╗███████╗██╗ ██████╗ ███╗   ██╗ █████╗ ██╗
+          ██╔══██╗██║████╗ ████║██╔════╝████╗  ██║██╔════╝██║██╔═══██╗████╗  ██║██╔══██╗██║
+          ██║  ██║██║██╔████╔██║█████╗  ██╔██╗ ██║███████╗██║██║   ██║██╔██╗ ██║███████║██║
+          ██║  ██║██║██║╚██╔╝██║██╔══╝  ██║╚██╗██║╚════██║██║██║   ██║██║╚██╗██║██╔══██║██║
+          ██████╔╝██║██║ ╚═╝ ██║███████╗██║ ╚████║███████║██║╚██████╔╝██║ ╚████║██║  ██║███████╗
+          ╚═════╝ ╚═╝╚═╝     ╚═╝╚══════╝╚═╝  ╚═══╝╚══════╝╚═╝ ╚═════╝ ╚═╝  ╚═══╝╚═╝  ╚═╝╚══════╝
+
+ + +
+ +[![Discord](https://img.shields.io/discord/1341146487186391173?style=flat-square&logo=discord&logoColor=white&label=Discord&color=5865F2)](https://discord.gg/dimos) +[![Stars](https://img.shields.io/github/stars/dimensionalOS/dimos?style=flat-square)](https://github.com/dimensionalOS/dimos/stargazers) +[![Forks](https://img.shields.io/github/forks/dimensionalOS/dimos?style=flat-square)](https://github.com/dimensionalOS/dimos/fork) +[![Contributors](https://img.shields.io/github/contributors/dimensionalOS/dimos?style=flat-square)](https://github.com/dimensionalOS/dimos/graphs/contributors) +
+![Nix](https://img.shields.io/badge/Nix-flakes-5277C3?style=flat-square&logo=NixOS&logoColor=white) +![NixOS](https://img.shields.io/badge/NixOS-supported-5277C3?style=flat-square&logo=NixOS&logoColor=white) +![CUDA](https://img.shields.io/badge/CUDA-12.x-76B900?style=flat-square&logo=nvidia&logoColor=white) +[![Docker](https://img.shields.io/badge/Docker-ready-2496ED?style=flat-square&logo=docker&logoColor=white)](https://www.docker.com/) + + +# Features + +Navigation + +Agentic + +Perception + +# Hardware + +Go2 + +Arms + +G1 + + +# Installation + +- general linux (nixos) +- macos +- ubuntu 2.4 From 3c553bd02c735841c5ed6f75dcbf123640297bb3 Mon Sep 17 00:00:00 2001 From: Ivan Nikolic Date: Sat, 14 Feb 2026 17:59:11 +0800 Subject: [PATCH 008/140] adjusting ascii --- NEWREADME.MD | 1 + 1 file changed, 1 insertion(+) diff --git a/NEWREADME.MD b/NEWREADME.MD index 178b7a836c..c0326f0a27 100644 --- a/NEWREADME.MD +++ b/NEWREADME.MD @@ -6,6 +6,7 @@ ██║ ██║██║██║╚██╔╝██║██╔══╝ ██║╚██╗██║╚════██║██║██║ ██║██║╚██╗██║██╔══██║██║ ██████╔╝██║██║ ╚═╝ ██║███████╗██║ ╚████║███████║██║╚██████╔╝██║ ╚████║██║ ██║███████╗ ╚═════╝ ╚═╝╚═╝ ╚═╝╚══════╝╚═╝ ╚═══╝╚══════╝╚═╝ ╚═════╝ ╚═╝ ╚═══╝╚═╝ ╚═╝╚══════╝ + From 3d85bbea8633d71a5d23c53e71057bb0da8c490e Mon Sep 17 00:00:00 2001 From: Ivan Nikolic Date: Sat, 14 Feb 2026 18:03:56 +0800 Subject: [PATCH 009/140] ascii adjust --- NEWREADME.MD | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/NEWREADME.MD b/NEWREADME.MD index c0326f0a27..dcbcfaade2 100644 --- a/NEWREADME.MD +++ b/NEWREADME.MD @@ -1,12 +1,12 @@ 
-          ██████╗ ██╗███╗   ███╗███████╗███╗   ██╗███████╗██╗ ██████╗ ███╗   ██╗ █████╗ ██╗
-          ██╔══██╗██║████╗ ████║██╔════╝████╗  ██║██╔════╝██║██╔═══██╗████╗  ██║██╔══██╗██║
-          ██║  ██║██║██╔████╔██║█████╗  ██╔██╗ ██║███████╗██║██║   ██║██╔██╗ ██║███████║██║
-          ██║  ██║██║██║╚██╔╝██║██╔══╝  ██║╚██╗██║╚════██║██║██║   ██║██║╚██╗██║██╔══██║██║
-          ██████╔╝██║██║ ╚═╝ ██║███████╗██║ ╚████║███████║██║╚██████╔╝██║ ╚████║██║  ██║███████╗
-          ╚═════╝ ╚═╝╚═╝     ╚═╝╚══════╝╚═╝  ╚═══╝╚══════╝╚═╝ ╚═════╝ ╚═╝  ╚═══╝╚═╝  ╚═╝╚══════╝
-
+            ██████╗ ██╗███╗   ███╗███████╗███╗   ██╗███████╗██╗ ██████╗ ███╗   ██╗ █████╗ ██╗
+            ██╔══██╗██║████╗ ████║██╔════╝████╗  ██║██╔════╝██║██╔═══██╗████╗  ██║██╔══██╗██║
+            ██║  ██║██║██╔████╔██║█████╗  ██╔██╗ ██║███████╗██║██║   ██║██╔██╗ ██║███████║██║
+            ██║  ██║██║██║╚██╔╝██║██╔══╝  ██║╚██╗██║╚════██║██║██║   ██║██║╚██╗██║██╔══██║██║
+            ██████╔╝██║██║ ╚═╝ ██║███████╗██║ ╚████║███████║██║╚██████╔╝██║ ╚████║██║  ██║███████╗
+            ╚═════╝ ╚═╝╚═╝     ╚═╝╚══════╝╚═╝  ╚═══╝╚══════╝╚═╝ ╚═════╝ ╚═╝  ╚═══╝╚═╝  ╚═╝╚══════╝
+                             Operating System for Generalist Robotics
From 31674dc79df59ecf38fd326aadba4a7da56ed83d Mon Sep 17 00:00:00 2001 From: Ivan Nikolic Date: Sat, 14 Feb 2026 18:04:51 +0800 Subject: [PATCH 010/140] micro adjustments --- NEWREADME.MD | 7 ++----- 1 file changed, 2 insertions(+), 5 deletions(-) diff --git a/NEWREADME.MD b/NEWREADME.MD index dcbcfaade2..dbfc88d327 100644 --- a/NEWREADME.MD +++ b/NEWREADME.MD @@ -1,4 +1,3 @@ -
             ██████╗ ██╗███╗   ███╗███████╗███╗   ██╗███████╗██╗ ██████╗ ███╗   ██╗ █████╗ ██╗
             ██╔══██╗██║████╗ ████║██╔════╝████╗  ██║██╔════╝██║██╔═══██╗████╗  ██║██╔══██╗██║
@@ -6,12 +5,10 @@
             ██║  ██║██║██║╚██╔╝██║██╔══╝  ██║╚██╗██║╚════██║██║██║   ██║██║╚██╗██║██╔══██║██║
             ██████╔╝██║██║ ╚═╝ ██║███████╗██║ ╚████║███████║██║╚██████╔╝██║ ╚████║██║  ██║███████╗
             ╚═════╝ ╚═╝╚═╝     ╚═╝╚══════╝╚═╝  ╚═══╝╚══════╝╚═╝ ╚═════╝ ╚═╝  ╚═══╝╚═╝  ╚═╝╚══════╝
-                             Operating System for Generalist Robotics
-
- +
[![Discord](https://img.shields.io/discord/1341146487186391173?style=flat-square&logo=discord&logoColor=white&label=Discord&color=5865F2)](https://discord.gg/dimos) [![Stars](https://img.shields.io/github/stars/dimensionalOS/dimos?style=flat-square)](https://github.com/dimensionalOS/dimos/stargazers) [![Forks](https://img.shields.io/github/forks/dimensionalOS/dimos?style=flat-square)](https://github.com/dimensionalOS/dimos/fork) @@ -21,7 +18,7 @@ ![NixOS](https://img.shields.io/badge/NixOS-supported-5277C3?style=flat-square&logo=NixOS&logoColor=white) ![CUDA](https://img.shields.io/badge/CUDA-12.x-76B900?style=flat-square&logo=nvidia&logoColor=white) [![Docker](https://img.shields.io/badge/Docker-ready-2496ED?style=flat-square&logo=docker&logoColor=white)](https://www.docker.com/) - +
# Features From 69bb232956a975d25f57aa84989df494833d4ebc Mon Sep 17 00:00:00 2001 From: Ivan Nikolic Date: Sat, 14 Feb 2026 18:06:51 +0800 Subject: [PATCH 011/140] readme --- NEWREADME.MD | 29 ++++++++++++----------------- 1 file changed, 12 insertions(+), 17 deletions(-) diff --git a/NEWREADME.MD b/NEWREADME.MD index dbfc88d327..fec7229a3e 100644 --- a/NEWREADME.MD +++ b/NEWREADME.MD @@ -7,34 +7,29 @@ ╚═════╝ ╚═╝╚═╝ ╚═╝╚══════╝╚═╝ ╚═══╝╚══════╝╚═╝ ╚═════╝ ╚═╝ ╚═══╝╚═╝ ╚═╝╚══════╝ -
+ +
+ [![Discord](https://img.shields.io/discord/1341146487186391173?style=flat-square&logo=discord&logoColor=white&label=Discord&color=5865F2)](https://discord.gg/dimos) [![Stars](https://img.shields.io/github/stars/dimensionalOS/dimos?style=flat-square)](https://github.com/dimensionalOS/dimos/stargazers) [![Forks](https://img.shields.io/github/forks/dimensionalOS/dimos?style=flat-square)](https://github.com/dimensionalOS/dimos/fork) [![Contributors](https://img.shields.io/github/contributors/dimensionalOS/dimos?style=flat-square)](https://github.com/dimensionalOS/dimos/graphs/contributors) +
+ ![Nix](https://img.shields.io/badge/Nix-flakes-5277C3?style=flat-square&logo=NixOS&logoColor=white) ![NixOS](https://img.shields.io/badge/NixOS-supported-5277C3?style=flat-square&logo=NixOS&logoColor=white) ![CUDA](https://img.shields.io/badge/CUDA-12.x-76B900?style=flat-square&logo=nvidia&logoColor=white) [![Docker](https://img.shields.io/badge/Docker-ready-2496ED?style=flat-square&logo=docker&logoColor=white)](https://www.docker.com/) -
- -# Features - -Navigation - -Agentic - -Perception - -# Hardware - -Go2 - -Arms -G1 +

+ Features • + Installation • + Documentation • + Development • + Contributing +

# Installation From ab29ec666967bd8d4fe6dbd71e16fba672528213 Mon Sep 17 00:00:00 2001 From: Ivan Nikolic Date: Sat, 14 Feb 2026 18:08:26 +0800 Subject: [PATCH 012/140] readme --- NEWREADME.MD | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/NEWREADME.MD b/NEWREADME.MD index fec7229a3e..5886859e99 100644 --- a/NEWREADME.MD +++ b/NEWREADME.MD @@ -1,3 +1,5 @@ +
+ 
             ██████╗ ██╗███╗   ███╗███████╗███╗   ██╗███████╗██╗ ██████╗ ███╗   ██╗ █████╗ ██╗
             ██╔══██╗██║████╗ ████║██╔════╝████╗  ██║██╔════╝██║██╔═══██╗████╗  ██║██╔══██╗██║
@@ -7,7 +9,7 @@
             ╚═════╝ ╚═╝╚═╝     ╚═╝╚══════╝╚═╝  ╚═══╝╚══════╝╚═╝ ╚═════╝ ╚═╝  ╚═══╝╚═╝  ╚═╝╚══════╝
-
+

The Agentive Operating System for Generalist Robotics


From 530bff97b513dde2e8ffae719fbd0859e13e0ed2 Mon Sep 17 00:00:00 2001 From: Ivan Nikolic Date: Sat, 14 Feb 2026 18:25:59 +0800 Subject: [PATCH 013/140] svg logo tests --- NEWREADME.MD | 11 ++++++++++- assets/dimensional-text.svg | 20 ++++++++++++++++++++ assets/dimensional.svg | 23 +++++++++++++++++++++++ 3 files changed, 53 insertions(+), 1 deletion(-) create mode 100644 assets/dimensional-text.svg create mode 100644 assets/dimensional.svg diff --git a/NEWREADME.MD b/NEWREADME.MD index 5886859e99..80f7f93da9 100644 --- a/NEWREADME.MD +++ b/NEWREADME.MD @@ -9,7 +9,8 @@ ╚═════╝ ╚═╝╚═╝ ╚═╝╚══════╝╚═╝ ╚═══╝╚══════╝╚═╝ ╚═════╝ ╚═╝ ╚═══╝╚═╝ ╚═╝╚══════╝ -

The Agentive Operating System for Generalist Robotics

+Dimensional +Dimensional
@@ -39,3 +40,11 @@ - general linux (nixos) - macos - ubuntu 2.4 + +# Documentation + + +# Development + + +# Contributing diff --git a/assets/dimensional-text.svg b/assets/dimensional-text.svg new file mode 100644 index 0000000000..0cf32b3d19 --- /dev/null +++ b/assets/dimensional-text.svg @@ -0,0 +1,20 @@ + + + + diff --git a/assets/dimensional.svg b/assets/dimensional.svg new file mode 100644 index 0000000000..f36a0dea40 --- /dev/null +++ b/assets/dimensional.svg @@ -0,0 +1,23 @@ + + + + From 65318b59bb04785ea3ffc05906e6590b3eb2abd5 Mon Sep 17 00:00:00 2001 From: Ivan Nikolic Date: Sat, 14 Feb 2026 18:31:16 +0800 Subject: [PATCH 014/140] light/dark svg --- NEWREADME.MD | 6 +++++- assets/dimensional-dark.svg | 23 +++++++++++++++++++++++ assets/dimensional-light.svg | 23 +++++++++++++++++++++++ 3 files changed, 51 insertions(+), 1 deletion(-) create mode 100644 assets/dimensional-dark.svg create mode 100644 assets/dimensional-light.svg diff --git a/NEWREADME.MD b/NEWREADME.MD index 80f7f93da9..ec297f5c80 100644 --- a/NEWREADME.MD +++ b/NEWREADME.MD @@ -9,9 +9,13 @@ ╚═════╝ ╚═╝╚═╝ ╚═╝╚══════╝╚═╝ ╚═══╝╚══════╝╚═╝ ╚═════╝ ╚═╝ ╚═══╝╚═╝ ╚═╝╚══════╝ -Dimensional Dimensional +LIGHT/DARK switch + +![DIMENSIONAL](assets/dimensional-light.svg#gh-light-mode-only) +![DIMENSIONAL](assets/dimensional-dark.svg#gh-dark-mode-only) +
[![Discord](https://img.shields.io/discord/1341146487186391173?style=flat-square&logo=discord&logoColor=white&label=Discord&color=5865F2)](https://discord.gg/dimos) diff --git a/assets/dimensional-dark.svg b/assets/dimensional-dark.svg new file mode 100644 index 0000000000..95edaadc0e --- /dev/null +++ b/assets/dimensional-dark.svg @@ -0,0 +1,23 @@ + + + + diff --git a/assets/dimensional-light.svg b/assets/dimensional-light.svg new file mode 100644 index 0000000000..f0a107bd10 --- /dev/null +++ b/assets/dimensional-light.svg @@ -0,0 +1,23 @@ + + + + From b931ea7f1c4e4f8def1306200c67c0f9a373250d Mon Sep 17 00:00:00 2001 From: Ivan Nikolic Date: Sat, 14 Feb 2026 18:33:58 +0800 Subject: [PATCH 015/140] alignment --- NEWREADME.MD | 20 ++------------------ 1 file changed, 2 insertions(+), 18 deletions(-) diff --git a/NEWREADME.MD b/NEWREADME.MD index ec297f5c80..b91a8c3a84 100644 --- a/NEWREADME.MD +++ b/NEWREADME.MD @@ -1,35 +1,19 @@
-
-            ██████╗ ██╗███╗   ███╗███████╗███╗   ██╗███████╗██╗ ██████╗ ███╗   ██╗ █████╗ ██╗
-            ██╔══██╗██║████╗ ████║██╔════╝████╗  ██║██╔════╝██║██╔═══██╗████╗  ██║██╔══██╗██║
-            ██║  ██║██║██╔████╔██║█████╗  ██╔██╗ ██║███████╗██║██║   ██║██╔██╗ ██║███████║██║
-            ██║  ██║██║██║╚██╔╝██║██╔══╝  ██║╚██╗██║╚════██║██║██║   ██║██║╚██╗██║██╔══██║██║
-            ██████╔╝██║██║ ╚═╝ ██║███████╗██║ ╚████║███████║██║╚██████╔╝██║ ╚████║██║  ██║███████╗
-            ╚═════╝ ╚═╝╚═╝     ╚═╝╚══════╝╚═╝  ╚═══╝╚══════╝╚═╝ ╚═════╝ ╚═╝  ╚═══╝╚═╝  ╚═╝╚══════╝
-
- -Dimensional - -LIGHT/DARK switch - ![DIMENSIONAL](assets/dimensional-light.svg#gh-light-mode-only) ![DIMENSIONAL](assets/dimensional-dark.svg#gh-dark-mode-only) -
- [![Discord](https://img.shields.io/discord/1341146487186391173?style=flat-square&logo=discord&logoColor=white&label=Discord&color=5865F2)](https://discord.gg/dimos) [![Stars](https://img.shields.io/github/stars/dimensionalOS/dimos?style=flat-square)](https://github.com/dimensionalOS/dimos/stargazers) [![Forks](https://img.shields.io/github/forks/dimensionalOS/dimos?style=flat-square)](https://github.com/dimensionalOS/dimos/fork) [![Contributors](https://img.shields.io/github/contributors/dimensionalOS/dimos?style=flat-square)](https://github.com/dimensionalOS/dimos/graphs/contributors) - -
- ![Nix](https://img.shields.io/badge/Nix-flakes-5277C3?style=flat-square&logo=NixOS&logoColor=white) ![NixOS](https://img.shields.io/badge/NixOS-supported-5277C3?style=flat-square&logo=NixOS&logoColor=white) ![CUDA](https://img.shields.io/badge/CUDA-12.x-76B900?style=flat-square&logo=nvidia&logoColor=white) [![Docker](https://img.shields.io/badge/Docker-ready-2496ED?style=flat-square&logo=docker&logoColor=white)](https://www.docker.com/) +
+

Features • Installation • From 300820be61272ce7b65bba3c7e2aa0ac4d5dd3c2 Mon Sep 17 00:00:00 2001 From: Ivan Nikolic Date: Sat, 14 Feb 2026 18:35:33 +0800 Subject: [PATCH 016/140] alignment attemps --- NEWREADME.MD | 2 ++ 1 file changed, 2 insertions(+) diff --git a/NEWREADME.MD b/NEWREADME.MD index b91a8c3a84..2a5fdedfc7 100644 --- a/NEWREADME.MD +++ b/NEWREADME.MD @@ -3,6 +3,8 @@ ![DIMENSIONAL](assets/dimensional-light.svg#gh-light-mode-only) ![DIMENSIONAL](assets/dimensional-dark.svg#gh-dark-mode-only) +
+ [![Discord](https://img.shields.io/discord/1341146487186391173?style=flat-square&logo=discord&logoColor=white&label=Discord&color=5865F2)](https://discord.gg/dimos) [![Stars](https://img.shields.io/github/stars/dimensionalOS/dimos?style=flat-square)](https://github.com/dimensionalOS/dimos/stargazers) [![Forks](https://img.shields.io/github/forks/dimensionalOS/dimos?style=flat-square)](https://github.com/dimensionalOS/dimos/fork) From 198ac147405ebe48aa50c0c96438a231879d1091 Mon Sep 17 00:00:00 2001 From: Ivan Nikolic Date: Sun, 15 Feb 2026 12:51:22 +0800 Subject: [PATCH 017/140] testing raw ascii --- NEWREADME.MD | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/NEWREADME.MD b/NEWREADME.MD index 2a5fdedfc7..443a3b61f2 100644 --- a/NEWREADME.MD +++ b/NEWREADME.MD @@ -1,5 +1,16 @@

+
+
+          ██████╗ ██╗███╗   ███╗███████╗███╗   ██╗███████╗██╗ ██████╗ ███╗   ██╗ █████╗ ██╗
+          ██╔══██╗██║████╗ ████║██╔════╝████╗  ██║██╔════╝██║██╔═══██╗████╗  ██║██╔══██╗██║
+          ██║  ██║██║██╔████╔██║█████╗  ██╔██╗ ██║███████╗██║██║   ██║██╔██╗ ██║███████║██║
+          ██║  ██║██║██║╚██╔╝██║██╔══╝  ██║╚██╗██║╚════██║██║██║   ██║██║╚██╗██║██╔══██║██║
+          ██████╔╝██║██║ ╚═╝ ██║███████╗██║ ╚████║███████║██║╚██████╔╝██║ ╚████║██║  ██║███████╗
+          ╚═════╝ ╚═╝╚═╝     ╚═╝╚══════╝╚═╝  ╚═══╝╚══════╝╚═╝ ╚═════╝ ╚═╝  ╚═══╝╚═╝  ╚═╝╚══════╝
+
+
+ ![DIMENSIONAL](assets/dimensional-light.svg#gh-light-mode-only) ![DIMENSIONAL](assets/dimensional-dark.svg#gh-dark-mode-only) From 1cf3768b22e778abf84f8c613532ed514dd76128 Mon Sep 17 00:00:00 2001 From: Ivan Nikolic Date: Sun, 15 Feb 2026 12:53:21 +0800 Subject: [PATCH 018/140] trying to fix rendering --- NEWREADME.MD | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/NEWREADME.MD b/NEWREADME.MD index 443a3b61f2..0fa6b0a109 100644 --- a/NEWREADME.MD +++ b/NEWREADME.MD @@ -8,7 +8,7 @@ ██║ ██║██║██║╚██╔╝██║██╔══╝ ██║╚██╗██║╚════██║██║██║ ██║██║╚██╗██║██╔══██║██║ ██████╔╝██║██║ ╚═╝ ██║███████╗██║ ╚████║███████║██║╚██████╔╝██║ ╚████║██║ ██║███████╗ ╚═════╝ ╚═╝╚═╝ ╚═╝╚══════╝╚═╝ ╚═══╝╚══════╝╚═╝ ╚═════╝ ╚═╝ ╚═══╝╚═╝ ╚═╝╚══════╝ - + bla ![DIMENSIONAL](assets/dimensional-light.svg#gh-light-mode-only) From 347348d7ff864d0f2fbfd53ccf0ee1ba39177cc0 Mon Sep 17 00:00:00 2001 From: Ivan Nikolic Date: Sun, 15 Feb 2026 12:54:11 +0800 Subject: [PATCH 019/140] fixing centering --- NEWREADME.MD | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/NEWREADME.MD b/NEWREADME.MD index 0fa6b0a109..49930ca7ff 100644 --- a/NEWREADME.MD +++ b/NEWREADME.MD @@ -1,4 +1,3 @@ -
 
@@ -8,9 +7,13 @@
           ██║  ██║██║██║╚██╔╝██║██╔══╝  ██║╚██╗██║╚════██║██║██║   ██║██║╚██╗██║██╔══██║██║
           ██████╔╝██║██║ ╚═╝ ██║███████╗██║ ╚████║███████║██║╚██████╔╝██║ ╚████║██║  ██║███████╗
           ╚═════╝ ╚═╝╚═╝     ╚═╝╚══════╝╚═╝  ╚═══╝╚══════╝╚═╝ ╚═════╝ ╚═╝  ╚═══╝╚═╝  ╚═╝╚══════╝
-          bla
+
+
+ + + ![DIMENSIONAL](assets/dimensional-light.svg#gh-light-mode-only) ![DIMENSIONAL](assets/dimensional-dark.svg#gh-dark-mode-only) From a6acc7e51fb1e2f32204f0d08e2f1cdeff93c963 Mon Sep 17 00:00:00 2001 From: Ivan Nikolic Date: Sun, 15 Feb 2026 12:55:07 +0800 Subject: [PATCH 020/140] shifting --- NEWREADME.MD | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/NEWREADME.MD b/NEWREADME.MD index 49930ca7ff..3d802318da 100644 --- a/NEWREADME.MD +++ b/NEWREADME.MD @@ -1,12 +1,12 @@ 
 
-          ██████╗ ██╗███╗   ███╗███████╗███╗   ██╗███████╗██╗ ██████╗ ███╗   ██╗ █████╗ ██╗
-          ██╔══██╗██║████╗ ████║██╔════╝████╗  ██║██╔════╝██║██╔═══██╗████╗  ██║██╔══██╗██║
-          ██║  ██║██║██╔████╔██║█████╗  ██╔██╗ ██║███████╗██║██║   ██║██╔██╗ ██║███████║██║
-          ██║  ██║██║██║╚██╔╝██║██╔══╝  ██║╚██╗██║╚════██║██║██║   ██║██║╚██╗██║██╔══██║██║
-          ██████╔╝██║██║ ╚═╝ ██║███████╗██║ ╚████║███████║██║╚██████╔╝██║ ╚████║██║  ██║███████╗
-          ╚═════╝ ╚═╝╚═╝     ╚═╝╚══════╝╚═╝  ╚═══╝╚══════╝╚═╝ ╚═════╝ ╚═╝  ╚═══╝╚═╝  ╚═╝╚══════╝
+                  ██████╗ ██╗███╗   ███╗███████╗███╗   ██╗███████╗██╗ ██████╗ ███╗   ██╗ █████╗ ██╗
+                  ██╔══██╗██║████╗ ████║██╔════╝████╗  ██║██╔════╝██║██╔═══██╗████╗  ██║██╔══██╗██║
+                  ██║  ██║██║██╔████╔██║█████╗  ██╔██╗ ██║███████╗██║██║   ██║██╔██╗ ██║███████║██║
+                  ██║  ██║██║██║╚██╔╝██║██╔══╝  ██║╚██╗██║╚════██║██║██║   ██║██║╚██╗██║██╔══██║██║
+                  ██████╔╝██║██║ ╚═╝ ██║███████╗██║ ╚████║███████║██║╚██████╔╝██║ ╚████║██║  ██║███████╗
+                  ╚═════╝ ╚═╝╚═╝     ╚═╝╚══════╝╚═╝  ╚═══╝╚══════╝╚═╝ ╚═════╝ ╚═╝  ╚═══╝╚═╝  ╚═╝╚══════╝
From 62698e5b75fa4807fe6794498f5e164f5cbb5f28 Mon Sep 17 00:00:00 2001 From: Ivan Nikolic Date: Sun, 15 Feb 2026 13:04:35 +0800 Subject: [PATCH 021/140] cleanup --- NEWREADME.MD | 32 ++++++-------------------------- 1 file changed, 6 insertions(+), 26 deletions(-) diff --git a/NEWREADME.MD b/NEWREADME.MD index 3d802318da..4d042260c8 100644 --- a/NEWREADME.MD +++ b/NEWREADME.MD @@ -1,43 +1,23 @@ 
-
                   ██████╗ ██╗███╗   ███╗███████╗███╗   ██╗███████╗██╗ ██████╗ ███╗   ██╗ █████╗ ██╗
                   ██╔══██╗██║████╗ ████║██╔════╝████╗  ██║██╔════╝██║██╔═══██╗████╗  ██║██╔══██╗██║
                   ██║  ██║██║██╔████╔██║█████╗  ██╔██╗ ██║███████╗██║██║   ██║██╔██╗ ██║███████║██║
                   ██║  ██║██║██║╚██╔╝██║██╔══╝  ██║╚██╗██║╚════██║██║██║   ██║██║╚██╗██║██╔══██║██║
                   ██████╔╝██║██║ ╚═╝ ██║███████╗██║ ╚████║███████║██║╚██████╔╝██║ ╚████║██║  ██║███████╗
                   ╚═════╝ ╚═╝╚═╝     ╚═╝╚══════╝╚═╝  ╚═══╝╚══════╝╚═╝ ╚═════╝ ╚═╝  ╚═══╝╚═╝  ╚═╝╚══════╝
-
-
+The Agentive Operating System for Generalist Robotics - - -![DIMENSIONAL](assets/dimensional-light.svg#gh-light-mode-only) -![DIMENSIONAL](assets/dimensional-dark.svg#gh-dark-mode-only) - -
- -[![Discord](https://img.shields.io/discord/1341146487186391173?style=flat-square&logo=discord&logoColor=white&label=Discord&color=5865F2)](https://discord.gg/dimos) -[![Stars](https://img.shields.io/github/stars/dimensionalOS/dimos?style=flat-square)](https://github.com/dimensionalOS/dimos/stargazers) -[![Forks](https://img.shields.io/github/forks/dimensionalOS/dimos?style=flat-square)](https://github.com/dimensionalOS/dimos/fork) -[![Contributors](https://img.shields.io/github/contributors/dimensionalOS/dimos?style=flat-square)](https://github.com/dimensionalOS/dimos/graphs/contributors) -![Nix](https://img.shields.io/badge/Nix-flakes-5277C3?style=flat-square&logo=NixOS&logoColor=white) -![NixOS](https://img.shields.io/badge/NixOS-supported-5277C3?style=flat-square&logo=NixOS&logoColor=white) -![CUDA](https://img.shields.io/badge/CUDA-12.x-76B900?style=flat-square&logo=nvidia&logoColor=white) -[![Docker](https://img.shields.io/badge/Docker-ready-2496ED?style=flat-square&logo=docker&logoColor=white)](https://www.docker.com/) +[Features](#the-dimensional-framework) • +[Installation](#installation) • +[Documentation](#documentation) • +[Development](#development) • +[Contributing](#contributing)
-

- Features • - Installation • - Documentation • - Development • - Contributing -

- # Installation From 49fb7a1a7c675db09451d59d629f9867aeb044e5 Mon Sep 17 00:00:00 2001 From: Ivan Nikolic Date: Sun, 15 Feb 2026 13:05:46 +0800 Subject: [PATCH 022/140] .. --- NEWREADME.MD | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/NEWREADME.MD b/NEWREADME.MD index 4d042260c8..2fe6f0e31b 100644 --- a/NEWREADME.MD +++ b/NEWREADME.MD @@ -8,7 +8,9 @@ ╚═════╝ ╚═╝╚═╝ ╚═╝╚══════╝╚═╝ ╚═══╝╚══════╝╚═╝ ╚═════╝ ╚═╝ ╚═══╝╚═╝ ╚═╝╚══════╝
-The Agentive Operating System for Generalist Robotics + +**The Agentive Operating System for Generalist Robotics** + [Features](#the-dimensional-framework) • [Installation](#installation) • From d9a9e8ae26cb36b0e7e7acee97546072aedd4811 Mon Sep 17 00:00:00 2001 From: Ivan Nikolic Date: Sun, 15 Feb 2026 13:19:04 +0800 Subject: [PATCH 023/140] testing table --- NEWREADME.MD | 16 ++++++++++++++++ assets/readme/detections.png | 3 +++ assets/readme/lidar.png | 3 +++ assets/readme/nav.png | 3 +++ 4 files changed, 25 insertions(+) create mode 100644 assets/readme/detections.png create mode 100644 assets/readme/lidar.png create mode 100644 assets/readme/nav.png diff --git a/NEWREADME.MD b/NEWREADME.MD index 2fe6f0e31b..21f22ddce9 100644 --- a/NEWREADME.MD +++ b/NEWREADME.MD @@ -21,6 +21,22 @@
+ + + + + + +
+ Navigation
+

Nav

+

ros and non ros

+ 		+ Det
+

Perception

+

bla bla perception

+
+ # Installation - general linux (nixos) diff --git a/assets/readme/detections.png b/assets/readme/detections.png new file mode 100644 index 0000000000..dcaef40506 --- /dev/null +++ b/assets/readme/detections.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:f168ddbb7fbac24e24547a5249197b8205b06e392db6def3de3c11df92b93c23 +size 767587 diff --git a/assets/readme/lidar.png b/assets/readme/lidar.png new file mode 100644 index 0000000000..1b499de10f --- /dev/null +++ b/assets/readme/lidar.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:65b1797fd9ac8edae5dce0691397b6aca2e975badfd58462ed8e20a4dace655e +size 927067 diff --git a/assets/readme/nav.png b/assets/readme/nav.png new file mode 100644 index 0000000000..16819a5007 --- /dev/null +++ b/assets/readme/nav.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:472cabca4b0d661658bf9ffbde78e636668e9ef6499dc38ea0f552557d735bd9 +size 617989 From 710c1d69745dc6b6625771abb9771743cc4ac7d8 Mon Sep 17 00:00:00 2001 From: Ivan Nikolic Date: Sun, 15 Feb 2026 13:22:51 +0800 Subject: [PATCH 024/140] size --- NEWREADME.MD | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/NEWREADME.MD b/NEWREADME.MD index 21f22ddce9..0cd4c4774c 100644 --- a/NEWREADME.MD +++ b/NEWREADME.MD @@ -25,12 +25,12 @@ From cf5873b0f93f9d464ca69f83b59c4c1ca6309e6d Mon Sep 17 00:00:00 2001 From: Ivan Nikolic Date: Sun, 15 Feb 2026 13:31:08 +0800 Subject: [PATCH 025/140] new table row --- NEWREADME.MD | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/NEWREADME.MD b/NEWREADME.MD index 0cd4c4774c..8934f54cb8 100644 --- a/NEWREADME.MD +++ b/NEWREADME.MD @@ -35,6 +35,18 @@

bla bla perception

 + + + +
- Navigation
+ Navigation

Nav

ros and non ros

 - Det
+ Det

Perception

bla bla perception

+ Mapping
+

Mapping

+

Voxels

+ 		+ Agents
+

Agents integration

+

bla bla MCP

+
# Installation From 95d55bdc2a2411d71c9f9afb9159d738cebb7bb7 Mon Sep 17 00:00:00 2001 From: Ivan Nikolic Date: Sun, 15 Feb 2026 13:31:59 +0800 Subject: [PATCH 026/140] added agents --- assets/readme/agents.png | 3 +++ 1 file changed, 3 insertions(+) create mode 100644 assets/readme/agents.png diff --git a/assets/readme/agents.png b/assets/readme/agents.png new file mode 100644 index 0000000000..b05bee0b03 --- /dev/null +++ b/assets/readme/agents.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:a255d32f9a0ecff12d99dda9b8a51e0958ac282d7a0f814f93fd39261afaf84d +size 477123 From d1f2eecdb046f288fbd708b3aee4095b00f310a3 Mon Sep 17 00:00:00 2001 From: Ivan Nikolic Date: Sun, 15 Feb 2026 13:38:51 +0800 Subject: [PATCH 027/140] watch video links --- NEWREADME.MD | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/NEWREADME.MD b/NEWREADME.MD index 8934f54cb8..3664700b15 100644 --- a/NEWREADME.MD +++ b/NEWREADME.MD @@ -27,24 +27,24 @@ Navigation

Nav

-

ros and non ros

+

ros and non ros · ▶ Watch video

Det

Perception

-

bla bla perception

+

bla bla perception · ▶ Watch video

Mapping

Mapping

-

Voxels

+

Voxels · ▶ Watch video

Agents

Agents integration

-

bla bla MCP

+

bla bla MCP · ▶ Watch video

From 68f929f59c71043c700b275163298853bbb1a42d Mon Sep 17 00:00:00 2001 From: Ivan Nikolic Date: Sun, 15 Feb 2026 13:41:05 +0800 Subject: [PATCH 028/140] hr --- NEWREADME.MD | 12 ++++++++---- 1 file changed, 8 insertions(+), 4 deletions(-) diff --git a/NEWREADME.MD b/NEWREADME.MD index 3664700b15..54c4072b09 100644 --- a/NEWREADME.MD +++ b/NEWREADME.MD @@ -25,24 +25,28 @@ From 5560fa9ecad91b337f435edb04eb7c667edf86f5 Mon Sep 17 00:00:00 2001 From: Ivan Nikolic Date: Sun, 15 Feb 2026 13:42:13 +0800 Subject: [PATCH 029/140] table ased lines --- NEWREADME.MD | 28 ++++++++++++++++++---------- 1 file changed, 18 insertions(+), 10 deletions(-) diff --git a/NEWREADME.MD b/NEWREADME.MD index 54c4072b09..53cf37c38e 100644 --- a/NEWREADME.MD +++ b/NEWREADME.MD @@ -26,29 +26,37 @@ + + + + + + + +
- Navigation
+ Navigation +

Nav

ros and non ros · ▶ Watch video

 - Det
+ Det +

Perception

bla bla perception · ▶ Watch video
- Mapping
+ Mapping +

Mapping

Voxels · ▶ Watch video

 - Agents
+ Agents +

Agents integration

bla bla MCP · ▶ Watch video

Navigation -
-

Nav

-

ros and non ros · ▶ Watch video

 Det -
+
+

Nav

+

ros and non ros ▶ Watch video

+

Perception

-

bla bla perception · ▶ Watch video

+

bla bla perception ▶ Watch video
Mapping -
-

Mapping

-

Voxels · ▶ Watch video

 Agents -
+
+

Mapping

+

Voxels ▶ Watch video

+

Agents integration

-

bla bla MCP · ▶ Watch video

+

bla bla MCP ▶ Watch video
From 33ebf011d635ef2672996bd431f2ca4aad0271ae Mon Sep 17 00:00:00 2001 From: Ivan Nikolic Date: Sun, 15 Feb 2026 13:43:15 +0800 Subject: [PATCH 030/140] .. --- NEWREADME.MD | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/NEWREADME.MD b/NEWREADME.MD index 53cf37c38e..b7e37f8466 100644 --- a/NEWREADME.MD +++ b/NEWREADME.MD @@ -34,11 +34,11 @@

Nav

-

ros and non ros ▶ Watch video

+ ros and non ros ▶ Watch video

Perception

-

bla bla perception ▶ Watch video

+ bla bla perception ▶ Watch video @@ -52,11 +52,11 @@

Mapping

-

Voxels ▶ Watch video

+ Voxels ▶ Watch video

Agents integration

-

bla bla MCP ▶ Watch video

+ bla bla MCP ▶ Watch video From da06540abaad08a6e3354e3d4ade77e4d2db1c04 Mon Sep 17 00:00:00 2001 From: Ivan Nikolic Date: Sun, 15 Feb 2026 13:47:58 +0800 Subject: [PATCH 031/140] checking if diff branch triggers CI --- NEWREADME.MD | 1 - 1 file changed, 1 deletion(-) diff --git a/NEWREADME.MD b/NEWREADME.MD index b7e37f8466..6b2685727d 100644 --- a/NEWREADME.MD +++ b/NEWREADME.MD @@ -21,7 +21,6 @@
- diff --git a/assets/readme/detections.png b/assets/readme/perception.png similarity index 100% rename from assets/readme/detections.png rename to assets/readme/perception.png From 89ccb881e0301ca989bb89233ab9b3fe24f7f4c1 Mon Sep 17 00:00:00 2001 From: Ivan Nikolic Date: Sun, 15 Feb 2026 13:58:38 +0800 Subject: [PATCH 035/140] .. --- NEWREADME.MD | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/NEWREADME.MD b/NEWREADME.MD index 7454553938..13437ea1f3 100644 --- a/NEWREADME.MD +++ b/NEWREADME.MD @@ -33,11 +33,11 @@ @@ -51,11 +51,11 @@
From 4fe06f0dbb6ef48f9a9757e48fb9fb8fc818fa32 Mon Sep 17 00:00:00 2001 From: Ivan Nikolic Date: Sun, 15 Feb 2026 13:50:27 +0800 Subject: [PATCH 032/140] code cleanup run only on PR --- .github/workflows/code-cleanup.yml | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/.github/workflows/code-cleanup.yml b/.github/workflows/code-cleanup.yml index 7177b3f9d1..745f3852c1 100644 --- a/.github/workflows/code-cleanup.yml +++ b/.github/workflows/code-cleanup.yml @@ -1,7 +1,8 @@ name: code-cleanup on: - push: pull_request: + paths-ignore: + - '**.md' permissions: contents: write From ebbe331c197ff6143de7c3575082a5fca01d901f Mon Sep 17 00:00:00 2001 From: Ivan Nikolic Date: Sun, 15 Feb 2026 13:56:03 +0800 Subject: [PATCH 033/140] better detections image --- assets/readme/detections.png | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/assets/readme/detections.png b/assets/readme/detections.png index dcaef40506..7ec15aabbf 100644 --- a/assets/readme/detections.png +++ b/assets/readme/detections.png @@ -1,3 +1,3 @@ version https://git-lfs.github.com/spec/v1 -oid sha256:f168ddbb7fbac24e24547a5249197b8205b06e392db6def3de3c11df92b93c23 -size 767587 +oid sha256:48e4c61c1ec588d56d61a74fd9f0d9251eadc042e7a514fb1896826d52a32988 +size 797817 From d700c66fd7c1f784a51a7f2375e62a526237b5ca Mon Sep 17 00:00:00 2001 From: Ivan Nikolic Date: Sun, 15 Feb 2026 13:57:12 +0800 Subject: [PATCH 034/140] renamed to rerender --- NEWREADME.MD | 2 +- assets/readme/{detections.png => perception.png} | 0 2 files changed, 1 insertion(+), 1 deletion(-) rename assets/readme/{detections.png => perception.png} (100%) diff --git a/NEWREADME.MD b/NEWREADME.MD index 6b2685727d..7454553938 100644 --- a/NEWREADME.MD +++ b/NEWREADME.MD @@ -27,7 +27,7 @@ Navigation - Det + Det

Nav

- ros and non ros ▶ Watch video + ros and non ros
▶ Watch video

Perception

- bla bla perception ▶ Watch video + bla bla perception
▶ Watch video

Mapping

- Voxels ▶ Watch video + Voxels
▶ Watch video

Agents integration

- bla bla MCP ▶ Watch video + bla bla MCP
▶ Watch video
From d118bbd1b6b1c348de9683296cb21fe6f85f7827 Mon Sep 17 00:00:00 2001 From: Ivan Nikolic Date: Sun, 15 Feb 2026 14:02:03 +0800 Subject: [PATCH 036/140] .. --- NEWREADME.MD | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/NEWREADME.MD b/NEWREADME.MD index 13437ea1f3..92db577c58 100644 --- a/NEWREADME.MD +++ b/NEWREADME.MD @@ -33,11 +33,11 @@

Nav

- ros and non ros
▶ Watch video + ros and non ros
Watch video

Perception

- bla bla perception
▶ Watch video + bla bla perception
Watch video @@ -51,11 +51,11 @@

Mapping

- Voxels
▶ Watch video + Voxels
Watch video

Agents integration

- bla bla MCP
▶ Watch video + bla bla MCP
Watch video From 816e8b875745a633969ddf4eba17378c4ffc1345 Mon Sep 17 00:00:00 2001 From: Ivan Nikolic Date: Sun, 15 Feb 2026 14:03:48 +0800 Subject: [PATCH 037/140] maybe svg is better --- NEWREADME.MD | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/NEWREADME.MD b/NEWREADME.MD index 92db577c58..810c04c0ee 100644 --- a/NEWREADME.MD +++ b/NEWREADME.MD @@ -7,8 +7,12 @@ ██████╔╝██║██║ ╚═╝ ██║███████╗██║ ╚████║███████║██║╚██████╔╝██║ ╚████║██║ ██║███████╗ ╚═════╝ ╚═╝╚═╝ ╚═╝╚══════╝╚═╝ ╚═══╝╚══════╝╚═╝ ╚═════╝ ╚═╝ ╚═══╝╚═╝ ╚═╝╚══════╝ +
+![Dimensional](assets/dimensional-dark.svg#gh-dark-mode-only) +![Dimensional](assets/dimensional-light.svg#gh-light-mode-only) + **The Agentive Operating System for Generalist Robotics** From ce667729b44c5e4735eb31150a294520030a927a Mon Sep 17 00:00:00 2001 From: Ivan Nikolic Date: Sun, 15 Feb 2026 14:04:51 +0800 Subject: [PATCH 038/140] I'm sorry to say svg is better --- NEWREADME.MD | 11 +---------- 1 file changed, 1 insertion(+), 10 deletions(-) diff --git a/NEWREADME.MD b/NEWREADME.MD index 810c04c0ee..e3863be47b 100644 --- a/NEWREADME.MD +++ b/NEWREADME.MD @@ -1,21 +1,12 @@ -
-                  ██████╗ ██╗███╗   ███╗███████╗███╗   ██╗███████╗██╗ ██████╗ ███╗   ██╗ █████╗ ██╗
-                  ██╔══██╗██║████╗ ████║██╔════╝████╗  ██║██╔════╝██║██╔═══██╗████╗  ██║██╔══██╗██║
-                  ██║  ██║██║██╔████╔██║█████╗  ██╔██╗ ██║███████╗██║██║   ██║██╔██╗ ██║███████║██║
-                  ██║  ██║██║██║╚██╔╝██║██╔══╝  ██║╚██╗██║╚════██║██║██║   ██║██║╚██╗██║██╔══██║██║
-                  ██████╔╝██║██║ ╚═╝ ██║███████╗██║ ╚████║███████║██║╚██████╔╝██║ ╚████║██║  ██║███████╗
-                  ╚═════╝ ╚═╝╚═╝     ╚═╝╚══════╝╚═╝  ╚═══╝╚══════╝╚═╝ ╚═════╝ ╚═╝  ╚═══╝╚═╝  ╚═╝╚══════╝
-
-
![Dimensional](assets/dimensional-dark.svg#gh-dark-mode-only) ![Dimensional](assets/dimensional-light.svg#gh-light-mode-only) - **The Agentive Operating System for Generalist Robotics** + [Features](#the-dimensional-framework) • [Installation](#installation) • [Documentation](#documentation) • From 370021b82b86921ecbb2170c195751a15e506cc6 Mon Sep 17 00:00:00 2001 From: Ivan Nikolic Date: Sun, 15 Feb 2026 14:05:59 +0800 Subject: [PATCH 039/140] .. --- NEWREADME.MD | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/NEWREADME.MD b/NEWREADME.MD index e3863be47b..e6d8aae6a1 100644 --- a/NEWREADME.MD +++ b/NEWREADME.MD @@ -3,7 +3,7 @@ ![Dimensional](assets/dimensional-dark.svg#gh-dark-mode-only) ![Dimensional](assets/dimensional-light.svg#gh-light-mode-only) -**The Agentive Operating System for Generalist Robotics** +##The Agentive Operating System for Generalist Robotics From 33327e188e2a2fd79d361e3365c584574a0a16e5 Mon Sep 17 00:00:00 2001 From: Ivan Nikolic Date: Sun, 15 Feb 2026 14:06:46 +0800 Subject: [PATCH 040/140] .. --- NEWREADME.MD | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/NEWREADME.MD b/NEWREADME.MD index e6d8aae6a1..cabde30ea8 100644 --- a/NEWREADME.MD +++ b/NEWREADME.MD @@ -3,7 +3,7 @@ ![Dimensional](assets/dimensional-dark.svg#gh-dark-mode-only) ![Dimensional](assets/dimensional-light.svg#gh-light-mode-only) -##The Agentive Operating System for Generalist Robotics +

The Agentive Operating System for Generalist Robotics

From d6c5093806cf5b319a2984f10a26822cfe823e96 Mon Sep 17 00:00:00 2001 From: Ivan Nikolic Date: Sun, 15 Feb 2026 14:07:55 +0800 Subject: [PATCH 041/140] .. --- NEWREADME.MD | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/NEWREADME.MD b/NEWREADME.MD index cabde30ea8..f7905f439e 100644 --- a/NEWREADME.MD +++ b/NEWREADME.MD @@ -3,9 +3,7 @@ ![Dimensional](assets/dimensional-dark.svg#gh-dark-mode-only) ![Dimensional](assets/dimensional-light.svg#gh-light-mode-only) -

The Agentive Operating System for Generalist Robotics

- - +

Agentic Operating System for Generalist Robotics

[Features](#the-dimensional-framework) • [Installation](#installation) • From 072574e30efa54214628a4f6fcccb7095d7d6f4f Mon Sep 17 00:00:00 2001 From: Ivan Nikolic Date: Sun, 15 Feb 2026 14:09:58 +0800 Subject: [PATCH 042/140] .. --- NEWREADME.MD | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/NEWREADME.MD b/NEWREADME.MD index f7905f439e..dad6859536 100644 --- a/NEWREADME.MD +++ b/NEWREADME.MD @@ -3,13 +3,15 @@ ![Dimensional](assets/dimensional-dark.svg#gh-dark-mode-only) ![Dimensional](assets/dimensional-light.svg#gh-light-mode-only) -

Agentic Operating System for Generalist Robotics

+

Program Atoms

+

[Features](#the-dimensional-framework) • [Installation](#installation) • [Documentation](#documentation) • [Development](#development) • [Contributing](#contributing) +

From e9df66282ecbc5cbfa4a6deb7dd2dbd8f17954d4 Mon Sep 17 00:00:00 2001 From: Ivan Nikolic Date: Sun, 15 Feb 2026 14:11:39 +0800 Subject: [PATCH 043/140] .. --- NEWREADME.MD | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/NEWREADME.MD b/NEWREADME.MD index dad6859536..6c4472d0ed 100644 --- a/NEWREADME.MD +++ b/NEWREADME.MD @@ -5,13 +5,15 @@ ![Dimensional](assets/dimensional-light.svg#gh-light-mode-only)

Program Atoms

-

+ + [Features](#the-dimensional-framework) • [Installation](#installation) • [Documentation](#documentation) • [Development](#development) • [Contributing](#contributing) -

+ +
From 406370515631859fe56c8e72670b3beaba6647f5 Mon Sep 17 00:00:00 2001 From: Ivan Nikolic Date: Sun, 15 Feb 2026 14:47:34 +0800 Subject: [PATCH 044/140] .. --- NEWREADME.MD | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/NEWREADME.MD b/NEWREADME.MD index 6c4472d0ed..d4d3377ceb 100644 --- a/NEWREADME.MD +++ b/NEWREADME.MD @@ -3,7 +3,7 @@ ![Dimensional](assets/dimensional-dark.svg#gh-dark-mode-only) ![Dimensional](assets/dimensional-light.svg#gh-light-mode-only) -

Program Atoms

+

Operating System for Generalist Robotics

From bf0782c37c6691940ebef5744e7663f51af416ae Mon Sep 17 00:00:00 2001 From: Ivan Nikolic Date: Sun, 15 Feb 2026 14:48:14 +0800 Subject: [PATCH 045/140] .. --- NEWREADME.MD | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/NEWREADME.MD b/NEWREADME.MD index d4d3377ceb..94579af15c 100644 --- a/NEWREADME.MD +++ b/NEWREADME.MD @@ -29,7 +29,7 @@ -

Nav

+

Navigation

ros and non ros
Watch video From f8e7c7a6c632ba450a5d4abf2240a2640098d244 Mon Sep 17 00:00:00 2001 From: Ivan Nikolic Date: Sun, 15 Feb 2026 15:30:20 +0800 Subject: [PATCH 046/140] nav gif --- NEWREADME.MD | 2 +- assets/readme/nav.gif | 3 +++ 2 files changed, 4 insertions(+), 1 deletion(-) create mode 100644 assets/readme/nav.gif diff --git a/NEWREADME.MD b/NEWREADME.MD index 94579af15c..ee864acc93 100644 --- a/NEWREADME.MD +++ b/NEWREADME.MD @@ -21,7 +21,7 @@ -
- Navigation + Navigation Det diff --git a/assets/readme/nav.gif b/assets/readme/nav.gif new file mode 100644 index 0000000000..66af38c568 --- /dev/null +++ b/assets/readme/nav.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:8f40536ed4a7d62d4803fe5f5c7926632e6f7585729b421a42cb1b8602878449 +size 1984148 From 007803da5818be51276012b56d793f0c280f5c29 Mon Sep 17 00:00:00 2001 From: Ivan Nikolic Date: Sun, 15 Feb 2026 15:33:32 +0800 Subject: [PATCH 047/140] better nav gif --- NEWREADME.MD | 2 +- assets/readme/nav.gif | 3 --- assets/readme/navigation.gif | 3 +++ assets/readme/{nav.png => navigation.png} | 0 4 files changed, 4 insertions(+), 4 deletions(-) delete mode 100644 assets/readme/nav.gif create mode 100644 assets/readme/navigation.gif rename assets/readme/{nav.png => navigation.png} (100%) diff --git a/NEWREADME.MD b/NEWREADME.MD index ee864acc93..e57397b0f5 100644 --- a/NEWREADME.MD +++ b/NEWREADME.MD @@ -21,7 +21,7 @@ +
- Navigation + Navigation Det diff --git a/assets/readme/nav.gif b/assets/readme/nav.gif deleted file mode 100644 index 66af38c568..0000000000 --- a/assets/readme/nav.gif +++ /dev/null @@ -1,3 +0,0 @@ -version https://git-lfs.github.com/spec/v1 -oid sha256:8f40536ed4a7d62d4803fe5f5c7926632e6f7585729b421a42cb1b8602878449 -size 1984148 diff --git a/assets/readme/navigation.gif b/assets/readme/navigation.gif new file mode 100644 index 0000000000..1402b1e85a --- /dev/null +++ b/assets/readme/navigation.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:64e7965f421916cdb71667a9ed99eab96c14c64bd195bd483628d1b9b9a4e95c +size 4395592 diff --git a/assets/readme/nav.png b/assets/readme/navigation.png similarity index 100% rename from assets/readme/nav.png rename to assets/readme/navigation.png From 3b1e5162268de01cc4fb70c3ab67a31ff0197182 Mon Sep 17 00:00:00 2001 From: Ivan Nikolic Date: Sun, 15 Feb 2026 15:47:03 +0800 Subject: [PATCH 048/140] .. --- NEWREADME.MD | 13 +++++++------ assets/readme/lidar.gif | 3 +++ 2 files changed, 10 insertions(+), 6 deletions(-) create mode 100644 assets/readme/lidar.gif diff --git a/NEWREADME.MD b/NEWREADME.MD index e57397b0f5..727d939bc5 100644 --- a/NEWREADME.MD +++ b/NEWREADME.MD @@ -39,22 +39,23 @@
- Mapping +

Mapping

+ Voxels
Watch video 		- Agents +

Agents integration

+ bla bla MCP
Watch video
-

Mapping

- Voxels
Watch video + Mapping 		-

Agents integration

- bla bla MCP
Watch video + Agents
# Installation diff --git a/assets/readme/lidar.gif b/assets/readme/lidar.gif new file mode 100644 index 0000000000..8302c2957d --- /dev/null +++ b/assets/readme/lidar.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:d47badc970572aa7badf98c908490c8b86ea9f1cafbb18507cfdb5d08655cdfb +size 5900150 From d5e19c605a5935663ccc1ba3e6559a0cfa81966e Mon Sep 17 00:00:00 2001 From: Ivan Nikolic Date: Sun, 15 Feb 2026 15:48:33 +0800 Subject: [PATCH 049/140] correct table --- NEWREADME.MD | 13 ++++++------- 1 file changed, 6 insertions(+), 7 deletions(-) diff --git a/NEWREADME.MD b/NEWREADME.MD index 727d939bc5..4f2a0061e0 100644 --- a/NEWREADME.MD +++ b/NEWREADME.MD @@ -39,23 +39,22 @@
-

Mapping

- Voxels
Watch video + Agents 		-

Agents integration

- bla bla MCP
Watch video + Mapping
- Mapping +

Agents integration

+ bla bla MCP
Watch video 		- Agents +

Mapping

+ Voxels
Watch video
# Installation From 80bc84efe33cbf43b1811c57c48148d2e4ecc264 Mon Sep 17 00:00:00 2001 From: Ivan Nikolic Date: Sun, 15 Feb 2026 16:00:11 +0800 Subject: [PATCH 050/140] hardware links --- NEWREADME.MD | 49 +++++++++++++++++++++++++++++++++++++++++++------ 1 file changed, 43 insertions(+), 6 deletions(-) diff --git a/NEWREADME.MD b/NEWREADME.MD index 4f2a0061e0..23b7356cb0 100644 --- a/NEWREADME.MD +++ b/NEWREADME.MD @@ -29,7 +29,7 @@ -

Navigation

+

Navigation and Mapping

ros and non ros
Watch video @@ -42,21 +42,58 @@ Agents - Mapping + Sensor Integrations -

Agents integration

- bla bla MCP
Watch video +

Agentic Control, MCP

+ "hey Claude, go to the kitchen"
Watch video -

Mapping

- Voxels
Watch video +

Sensor Integrations

+ Livox Mid360, Zed + +# Hardware + + + + + + + + + + + + + + + +
+ Dog + + Humanoid + + Arm + + Drone +
+

Dog

+ 		+

Humanoid

+ 		+

Arm

+ 		+

Drone

+
+ + + # Installation - general linux (nixos) From 34eac18dd98df6470fda718f4b05f86b6e8f0310 Mon Sep 17 00:00:00 2001 From: Ivan Nikolic Date: Sun, 15 Feb 2026 16:03:46 +0800 Subject: [PATCH 051/140] .. --- NEWREADME.MD | 17 +---------------- 1 file changed, 1 insertion(+), 16 deletions(-) diff --git a/NEWREADME.MD b/NEWREADME.MD index 23b7356cb0..697ca0909a 100644 --- a/NEWREADME.MD +++ b/NEWREADME.MD @@ -60,22 +60,7 @@ # Hardware - - - - - - - - +
- Dog - - Humanoid - - Arm - - Drone -

Dog

From d14897f39a23cdf5f57017ecca1b161c70b3d01e Mon Sep 17 00:00:00 2001 From: Ivan Nikolic Date: Sun, 15 Feb 2026 16:05:11 +0800 Subject: [PATCH 052/140] .. --- NEWREADME.MD | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/NEWREADME.MD b/NEWREADME.MD index 697ca0909a..c18793cc6e 100644 --- a/NEWREADME.MD +++ b/NEWREADME.MD @@ -60,18 +60,22 @@ # Hardware - +
From 1c171ac165f661903b439d9917708aa92fadb485 Mon Sep 17 00:00:00 2001 From: Ivan Nikolic Date: Sun, 15 Feb 2026 16:07:17 +0800 Subject: [PATCH 053/140] go2 link test --- NEWREADME.MD | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/NEWREADME.MD b/NEWREADME.MD index c18793cc6e..f9700b270d 100644 --- a/NEWREADME.MD +++ b/NEWREADME.MD @@ -63,20 +63,20 @@
+

Dog

 +

Humanoid

 +

Arm

 +

Drone
+

Dog

-

Dog

 -

Humanoid

+ 		-

Arm

+ 		-

Drone

+
From 799015a4e3fdb8d9688e3ceddd9cce3c3197e6ad Mon Sep 17 00:00:00 2001 From: Ivan Nikolic Date: Sun, 15 Feb 2026 16:08:45 +0800 Subject: [PATCH 054/140] .. --- NEWREADME.MD | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/NEWREADME.MD b/NEWREADME.MD index f9700b270d..3aad08832e 100644 --- a/NEWREADME.MD +++ b/NEWREADME.MD @@ -63,8 +63,9 @@
-

Dog

+

Dog

+ Unitree Go2 pro/air

Humanoid

From cd12c3bddb5f5d8896cb238c6f63ad0b2c7d1d90 Mon Sep 17 00:00:00 2001 From: Ivan Nikolic Date: Sun, 15 Feb 2026 16:09:34 +0800 Subject: [PATCH 055/140] hw links --- NEWREADME.MD | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/NEWREADME.MD b/NEWREADME.MD index 3aad08832e..5743adb1ce 100644 --- a/NEWREADME.MD +++ b/NEWREADME.MD @@ -70,14 +70,19 @@

Humanoid

+ Unitree G1

Arm

+ Xarm + Piper

Drone

+ Mavlink + DJI SDK
From 7722ee8bd3a67648b6f05b58aeccea19294f3b4f Mon Sep 17 00:00:00 2001 From: Ivan Nikolic Date: Sun, 15 Feb 2026 16:10:28 +0800 Subject: [PATCH 056/140] .. --- NEWREADME.MD | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/NEWREADME.MD b/NEWREADME.MD index 5743adb1ce..39c9caf9b5 100644 --- a/NEWREADME.MD +++ b/NEWREADME.MD @@ -65,24 +65,24 @@

Dog

- Unitree Go2 pro/air + Unitree Go2 pro/air

Humanoid

- Unitree G1 + Unitree G1

Arm

- Xarm - Piper + Xarm
+ Piper

Drone

- Mavlink - DJI SDK + Mavlink
+ DJI SDK
From cfe344424d62b92f5509ca9d1a9ff5866c1a42e1 Mon Sep 17 00:00:00 2001 From: Ivan Nikolic Date: Sun, 15 Feb 2026 17:07:09 +0800 Subject: [PATCH 057/140] structure --- NEWREADME.MD | 22 ++++++++++--------- docs/{usage => api}/README.md | 0 .../assets/abstraction_layers.svg | 0 docs/{usage => api}/assets/camera_module.svg | 0 docs/{usage => api}/assets/go2_agentic.svg | 0 docs/{usage => api}/assets/go2_nav.svg | 0 docs/{usage => api}/assets/lcmspy.png | 0 .../assets/pubsub_benchmark.png | 0 docs/{usage => api}/assets/transforms.png | 0 .../assets/transforms_chain.svg | 0 .../assets/transforms_modules.svg | 0 .../{usage => api}/assets/transforms_tree.svg | 0 docs/{usage => api}/blueprints.md | 0 docs/{usage => api}/configuration.md | 0 docs/{usage => api}/lcm.md | 0 docs/{usage => api}/modules.md | 0 docs/{usage => api}/sensor_streams/README.md | 0 .../sensor_streams/advanced_streams.md | 0 .../sensor_streams/assets/alignment_flow.svg | 0 .../assets/alignment_overview.svg | 0 .../assets/alignment_timeline.png | 0 .../assets/alignment_timeline2.png | 0 .../assets/alignment_timeline3.png | 0 .../sensor_streams/assets/backpressure.svg | 0 .../assets/backpressure_solution.svg | 0 .../sensor_streams/assets/frame_mosaic.jpg | 0 .../sensor_streams/assets/frame_mosaic2.jpg | 0 .../sensor_streams/assets/getter_hot_cold.svg | 0 .../sensor_streams/assets/observable_flow.svg | 0 .../sensor_streams/assets/sharpness_graph.svg | 0 .../assets/sharpness_graph2.svg | 0 .../sensor_streams/quality_filter.md | 0 .../sensor_streams/reactivex.md | 0 .../sensor_streams/storage_replay.md | 0 .../sensor_streams/temporal_alignment.md | 0 docs/{usage => api}/transforms.md | 0 docs/{usage => api}/transports.md | 0 docs/{usage => api}/visualization.md | 0 docs/capabilities/agents/readme.md | 1 + docs/capabilities/navigation/readme.md | 8 +++++++ docs/capabilities/perception/readme.md | 3 +++ docs/hardware/dog/go2/index.md | 1 + docs/installation/nix.md | 1 + docs/installation/osx.md | 1 + docs/installation/ubuntu.md | 1 + 45 files changed, 28 insertions(+), 10 deletions(-) rename docs/{usage => api}/README.md (100%) rename docs/{usage => api}/assets/abstraction_layers.svg (100%) rename docs/{usage => api}/assets/camera_module.svg (100%) rename docs/{usage => api}/assets/go2_agentic.svg (100%) rename docs/{usage => api}/assets/go2_nav.svg (100%) rename docs/{usage => api}/assets/lcmspy.png (100%) rename docs/{usage => api}/assets/pubsub_benchmark.png (100%) rename docs/{usage => api}/assets/transforms.png (100%) rename docs/{usage => api}/assets/transforms_chain.svg (100%) rename docs/{usage => api}/assets/transforms_modules.svg (100%) rename docs/{usage => api}/assets/transforms_tree.svg (100%) rename docs/{usage => api}/blueprints.md (100%) rename docs/{usage => api}/configuration.md (100%) rename docs/{usage => api}/lcm.md (100%) rename docs/{usage => api}/modules.md (100%) rename docs/{usage => api}/sensor_streams/README.md (100%) rename docs/{usage => api}/sensor_streams/advanced_streams.md (100%) rename docs/{usage => api}/sensor_streams/assets/alignment_flow.svg (100%) rename docs/{usage => api}/sensor_streams/assets/alignment_overview.svg (100%) rename docs/{usage => api}/sensor_streams/assets/alignment_timeline.png (100%) rename docs/{usage => api}/sensor_streams/assets/alignment_timeline2.png (100%) rename docs/{usage => api}/sensor_streams/assets/alignment_timeline3.png (100%) rename docs/{usage => api}/sensor_streams/assets/backpressure.svg (100%) rename docs/{usage => api}/sensor_streams/assets/backpressure_solution.svg (100%) rename docs/{usage => api}/sensor_streams/assets/frame_mosaic.jpg (100%) rename docs/{usage => api}/sensor_streams/assets/frame_mosaic2.jpg (100%) rename docs/{usage => api}/sensor_streams/assets/getter_hot_cold.svg (100%) rename docs/{usage => api}/sensor_streams/assets/observable_flow.svg (100%) rename docs/{usage => api}/sensor_streams/assets/sharpness_graph.svg (100%) rename docs/{usage => api}/sensor_streams/assets/sharpness_graph2.svg (100%) rename docs/{usage => api}/sensor_streams/quality_filter.md (100%) rename docs/{usage => api}/sensor_streams/reactivex.md (100%) rename docs/{usage => api}/sensor_streams/storage_replay.md (100%) rename docs/{usage => api}/sensor_streams/temporal_alignment.md (100%) rename docs/{usage => api}/transforms.md (100%) rename docs/{usage => api}/transports.md (100%) rename docs/{usage => api}/visualization.md (100%) create mode 100644 docs/capabilities/agents/readme.md create mode 100644 docs/capabilities/navigation/readme.md create mode 100644 docs/capabilities/perception/readme.md create mode 100644 docs/hardware/dog/go2/index.md create mode 100644 docs/installation/nix.md create mode 100644 docs/installation/osx.md create mode 100644 docs/installation/ubuntu.md diff --git a/NEWREADME.MD b/NEWREADME.MD index 39c9caf9b5..bb916a408d 100644 --- a/NEWREADME.MD +++ b/NEWREADME.MD @@ -17,6 +17,9 @@
+# Intro + +We aim to provide an easy to install and run modern framework for robotics @@ -87,18 +90,17 @@
- - # Installation -- general linux (nixos) -- macos -- ubuntu 2.4 - -# Documentation - +to setup your system dependencies follow one of these: -# Development +- [NixOS / General Linux](docs/installation/nix.md) +- [macOS](docs/installation/osx.md) +- [Ubuntu 24.04](docs/installation/ubuntu.md) +then just -# Contributing +```sh +pip install dimos[your_platform] +dimos run your_platform_blueprint +``` diff --git a/docs/usage/README.md b/docs/api/README.md similarity index 100% rename from docs/usage/README.md rename to docs/api/README.md diff --git a/docs/usage/assets/abstraction_layers.svg b/docs/api/assets/abstraction_layers.svg similarity index 100% rename from docs/usage/assets/abstraction_layers.svg rename to docs/api/assets/abstraction_layers.svg diff --git a/docs/usage/assets/camera_module.svg b/docs/api/assets/camera_module.svg similarity index 100% rename from docs/usage/assets/camera_module.svg rename to docs/api/assets/camera_module.svg diff --git a/docs/usage/assets/go2_agentic.svg b/docs/api/assets/go2_agentic.svg similarity index 100% rename from docs/usage/assets/go2_agentic.svg rename to docs/api/assets/go2_agentic.svg diff --git a/docs/usage/assets/go2_nav.svg b/docs/api/assets/go2_nav.svg similarity index 100% rename from docs/usage/assets/go2_nav.svg rename to docs/api/assets/go2_nav.svg diff --git a/docs/usage/assets/lcmspy.png b/docs/api/assets/lcmspy.png similarity index 100% rename from docs/usage/assets/lcmspy.png rename to docs/api/assets/lcmspy.png diff --git a/docs/usage/assets/pubsub_benchmark.png b/docs/api/assets/pubsub_benchmark.png similarity index 100% rename from docs/usage/assets/pubsub_benchmark.png rename to docs/api/assets/pubsub_benchmark.png diff --git a/docs/usage/assets/transforms.png b/docs/api/assets/transforms.png similarity index 100% rename from docs/usage/assets/transforms.png rename to docs/api/assets/transforms.png diff --git a/docs/usage/assets/transforms_chain.svg b/docs/api/assets/transforms_chain.svg similarity index 100% rename from docs/usage/assets/transforms_chain.svg rename to docs/api/assets/transforms_chain.svg diff --git a/docs/usage/assets/transforms_modules.svg b/docs/api/assets/transforms_modules.svg similarity index 100% rename from docs/usage/assets/transforms_modules.svg rename to docs/api/assets/transforms_modules.svg diff --git a/docs/usage/assets/transforms_tree.svg b/docs/api/assets/transforms_tree.svg similarity index 100% rename from docs/usage/assets/transforms_tree.svg rename to docs/api/assets/transforms_tree.svg diff --git a/docs/usage/blueprints.md b/docs/api/blueprints.md similarity index 100% rename from docs/usage/blueprints.md rename to docs/api/blueprints.md diff --git a/docs/usage/configuration.md b/docs/api/configuration.md similarity index 100% rename from docs/usage/configuration.md rename to docs/api/configuration.md diff --git a/docs/usage/lcm.md b/docs/api/lcm.md similarity index 100% rename from docs/usage/lcm.md rename to docs/api/lcm.md diff --git a/docs/usage/modules.md b/docs/api/modules.md similarity index 100% rename from docs/usage/modules.md rename to docs/api/modules.md diff --git a/docs/usage/sensor_streams/README.md b/docs/api/sensor_streams/README.md similarity index 100% rename from docs/usage/sensor_streams/README.md rename to docs/api/sensor_streams/README.md diff --git a/docs/usage/sensor_streams/advanced_streams.md b/docs/api/sensor_streams/advanced_streams.md similarity index 100% rename from docs/usage/sensor_streams/advanced_streams.md rename to docs/api/sensor_streams/advanced_streams.md diff --git a/docs/usage/sensor_streams/assets/alignment_flow.svg b/docs/api/sensor_streams/assets/alignment_flow.svg similarity index 100% rename from docs/usage/sensor_streams/assets/alignment_flow.svg rename to docs/api/sensor_streams/assets/alignment_flow.svg diff --git a/docs/usage/sensor_streams/assets/alignment_overview.svg b/docs/api/sensor_streams/assets/alignment_overview.svg similarity index 100% rename from docs/usage/sensor_streams/assets/alignment_overview.svg rename to docs/api/sensor_streams/assets/alignment_overview.svg diff --git a/docs/usage/sensor_streams/assets/alignment_timeline.png b/docs/api/sensor_streams/assets/alignment_timeline.png similarity index 100% rename from docs/usage/sensor_streams/assets/alignment_timeline.png rename to docs/api/sensor_streams/assets/alignment_timeline.png diff --git a/docs/usage/sensor_streams/assets/alignment_timeline2.png b/docs/api/sensor_streams/assets/alignment_timeline2.png similarity index 100% rename from docs/usage/sensor_streams/assets/alignment_timeline2.png rename to docs/api/sensor_streams/assets/alignment_timeline2.png diff --git a/docs/usage/sensor_streams/assets/alignment_timeline3.png b/docs/api/sensor_streams/assets/alignment_timeline3.png similarity index 100% rename from docs/usage/sensor_streams/assets/alignment_timeline3.png rename to docs/api/sensor_streams/assets/alignment_timeline3.png diff --git a/docs/usage/sensor_streams/assets/backpressure.svg b/docs/api/sensor_streams/assets/backpressure.svg similarity index 100% rename from docs/usage/sensor_streams/assets/backpressure.svg rename to docs/api/sensor_streams/assets/backpressure.svg diff --git a/docs/usage/sensor_streams/assets/backpressure_solution.svg b/docs/api/sensor_streams/assets/backpressure_solution.svg similarity index 100% rename from docs/usage/sensor_streams/assets/backpressure_solution.svg rename to docs/api/sensor_streams/assets/backpressure_solution.svg diff --git a/docs/usage/sensor_streams/assets/frame_mosaic.jpg b/docs/api/sensor_streams/assets/frame_mosaic.jpg similarity index 100% rename from docs/usage/sensor_streams/assets/frame_mosaic.jpg rename to docs/api/sensor_streams/assets/frame_mosaic.jpg diff --git a/docs/usage/sensor_streams/assets/frame_mosaic2.jpg b/docs/api/sensor_streams/assets/frame_mosaic2.jpg similarity index 100% rename from docs/usage/sensor_streams/assets/frame_mosaic2.jpg rename to docs/api/sensor_streams/assets/frame_mosaic2.jpg diff --git a/docs/usage/sensor_streams/assets/getter_hot_cold.svg b/docs/api/sensor_streams/assets/getter_hot_cold.svg similarity index 100% rename from docs/usage/sensor_streams/assets/getter_hot_cold.svg rename to docs/api/sensor_streams/assets/getter_hot_cold.svg diff --git a/docs/usage/sensor_streams/assets/observable_flow.svg b/docs/api/sensor_streams/assets/observable_flow.svg similarity index 100% rename from docs/usage/sensor_streams/assets/observable_flow.svg rename to docs/api/sensor_streams/assets/observable_flow.svg diff --git a/docs/usage/sensor_streams/assets/sharpness_graph.svg b/docs/api/sensor_streams/assets/sharpness_graph.svg similarity index 100% rename from docs/usage/sensor_streams/assets/sharpness_graph.svg rename to docs/api/sensor_streams/assets/sharpness_graph.svg diff --git a/docs/usage/sensor_streams/assets/sharpness_graph2.svg b/docs/api/sensor_streams/assets/sharpness_graph2.svg similarity index 100% rename from docs/usage/sensor_streams/assets/sharpness_graph2.svg rename to docs/api/sensor_streams/assets/sharpness_graph2.svg diff --git a/docs/usage/sensor_streams/quality_filter.md b/docs/api/sensor_streams/quality_filter.md similarity index 100% rename from docs/usage/sensor_streams/quality_filter.md rename to docs/api/sensor_streams/quality_filter.md diff --git a/docs/usage/sensor_streams/reactivex.md b/docs/api/sensor_streams/reactivex.md similarity index 100% rename from docs/usage/sensor_streams/reactivex.md rename to docs/api/sensor_streams/reactivex.md diff --git a/docs/usage/sensor_streams/storage_replay.md b/docs/api/sensor_streams/storage_replay.md similarity index 100% rename from docs/usage/sensor_streams/storage_replay.md rename to docs/api/sensor_streams/storage_replay.md diff --git a/docs/usage/sensor_streams/temporal_alignment.md b/docs/api/sensor_streams/temporal_alignment.md similarity index 100% rename from docs/usage/sensor_streams/temporal_alignment.md rename to docs/api/sensor_streams/temporal_alignment.md diff --git a/docs/usage/transforms.md b/docs/api/transforms.md similarity index 100% rename from docs/usage/transforms.md rename to docs/api/transforms.md diff --git a/docs/usage/transports.md b/docs/api/transports.md similarity index 100% rename from docs/usage/transports.md rename to docs/api/transports.md diff --git a/docs/usage/visualization.md b/docs/api/visualization.md similarity index 100% rename from docs/usage/visualization.md rename to docs/api/visualization.md diff --git a/docs/capabilities/agents/readme.md b/docs/capabilities/agents/readme.md new file mode 100644 index 0000000000..57be659e9c --- /dev/null +++ b/docs/capabilities/agents/readme.md @@ -0,0 +1 @@ +# Agents diff --git a/docs/capabilities/navigation/readme.md b/docs/capabilities/navigation/readme.md new file mode 100644 index 0000000000..0c6ff9efdd --- /dev/null +++ b/docs/capabilities/navigation/readme.md @@ -0,0 +1,8 @@ +# Navigation + + +## Non ROS + + + +## ROS diff --git a/docs/capabilities/perception/readme.md b/docs/capabilities/perception/readme.md new file mode 100644 index 0000000000..5d6e089dbf --- /dev/null +++ b/docs/capabilities/perception/readme.md @@ -0,0 +1,3 @@ +# Perception + +## Detections diff --git a/docs/hardware/dog/go2/index.md b/docs/hardware/dog/go2/index.md new file mode 100644 index 0000000000..3ce7c425de --- /dev/null +++ b/docs/hardware/dog/go2/index.md @@ -0,0 +1 @@ +# GO2 Getting started diff --git a/docs/installation/nix.md b/docs/installation/nix.md new file mode 100644 index 0000000000..342a8c5191 --- /dev/null +++ b/docs/installation/nix.md @@ -0,0 +1 @@ +# nix install diff --git a/docs/installation/osx.md b/docs/installation/osx.md new file mode 100644 index 0000000000..4ead4ccec5 --- /dev/null +++ b/docs/installation/osx.md @@ -0,0 +1 @@ +# osx install diff --git a/docs/installation/ubuntu.md b/docs/installation/ubuntu.md new file mode 100644 index 0000000000..2d64abe69c --- /dev/null +++ b/docs/installation/ubuntu.md @@ -0,0 +1 @@ +# Ubuntu install From c83ccb05619b79288cca31870accaf8c48532175 Mon Sep 17 00:00:00 2001 From: Ivan Nikolic Date: Sun, 15 Feb 2026 17:12:17 +0800 Subject: [PATCH 058/140] .. --- NEWREADME.MD | 22 +++++++++++++++++++++- 1 file changed, 21 insertions(+), 1 deletion(-) diff --git a/NEWREADME.MD b/NEWREADME.MD index bb916a408d..14ac8ee632 100644 --- a/NEWREADME.MD +++ b/NEWREADME.MD @@ -98,9 +98,29 @@ to setup your system dependencies follow one of these: - [macOS](docs/installation/osx.md) - [Ubuntu 24.04](docs/installation/ubuntu.md) -then just +then you are ready to jump into Python ```sh pip install dimos[your_platform] dimos run your_platform_blueprint ``` + +# API + +[Blueprints](docs/api/blueprints.md) • +[Modules](docs/api/modules.md) • +[Transports](docs/api/transports.md) • +[Sensor Streams](docs/api/sensor_streams/README.md) • +[LCM](docs/api/lcm.md) • +[Configuration](docs/api/configuration.md) • +[Visualization](docs/api/visualization.md) + +# Multi Language Support + +Python is our glue and prototyping language, but we support many languages, and ROS interop + +check our examples/language-interop + +# ROS interop + +for researchers etc we can talk to ros directly via [ROS Transports](docs/api/transports.md), or we can host ROS deployments as first class Dimos Modules From a9d292cfa6571a74dc3603beb4ab6d884374a53a Mon Sep 17 00:00:00 2001 From: Ivan Nikolic Date: Sun, 15 Feb 2026 17:15:27 +0800 Subject: [PATCH 059/140] .. --- NEWREADME.MD | 8 ++++---- docs/api/README.md | 2 +- docs/api/{sensor_streams => data_streams}/README.md | 0 .../{sensor_streams => data_streams}/advanced_streams.md | 0 .../assets/alignment_flow.svg | 0 .../assets/alignment_overview.svg | 0 .../assets/alignment_timeline.png | 0 .../assets/alignment_timeline2.png | 0 .../assets/alignment_timeline3.png | 0 .../assets/backpressure.svg | 0 .../assets/backpressure_solution.svg | 0 .../assets/frame_mosaic.jpg | 0 .../assets/frame_mosaic2.jpg | 0 .../assets/getter_hot_cold.svg | 0 .../assets/observable_flow.svg | 0 .../assets/sharpness_graph.svg | 0 .../assets/sharpness_graph2.svg | 0 .../{sensor_streams => data_streams}/quality_filter.md | 0 docs/api/{sensor_streams => data_streams}/reactivex.md | 0 .../{sensor_streams => data_streams}/storage_replay.md | 0 .../temporal_alignment.md | 0 21 files changed, 5 insertions(+), 5 deletions(-) rename docs/api/{sensor_streams => data_streams}/README.md (100%) rename docs/api/{sensor_streams => data_streams}/advanced_streams.md (100%) rename docs/api/{sensor_streams => data_streams}/assets/alignment_flow.svg (100%) rename docs/api/{sensor_streams => data_streams}/assets/alignment_overview.svg (100%) rename docs/api/{sensor_streams => data_streams}/assets/alignment_timeline.png (100%) rename docs/api/{sensor_streams => data_streams}/assets/alignment_timeline2.png (100%) rename docs/api/{sensor_streams => data_streams}/assets/alignment_timeline3.png (100%) rename docs/api/{sensor_streams => data_streams}/assets/backpressure.svg (100%) rename docs/api/{sensor_streams => data_streams}/assets/backpressure_solution.svg (100%) rename docs/api/{sensor_streams => data_streams}/assets/frame_mosaic.jpg (100%) rename docs/api/{sensor_streams => data_streams}/assets/frame_mosaic2.jpg (100%) rename docs/api/{sensor_streams => data_streams}/assets/getter_hot_cold.svg (100%) rename docs/api/{sensor_streams => data_streams}/assets/observable_flow.svg (100%) rename docs/api/{sensor_streams => data_streams}/assets/sharpness_graph.svg (100%) rename docs/api/{sensor_streams => data_streams}/assets/sharpness_graph2.svg (100%) rename docs/api/{sensor_streams => data_streams}/quality_filter.md (100%) rename docs/api/{sensor_streams => data_streams}/reactivex.md (100%) rename docs/api/{sensor_streams => data_streams}/storage_replay.md (100%) rename docs/api/{sensor_streams => data_streams}/temporal_alignment.md (100%) diff --git a/NEWREADME.MD b/NEWREADME.MD index 14ac8ee632..c324ac2a5c 100644 --- a/NEWREADME.MD +++ b/NEWREADME.MD @@ -19,7 +19,7 @@ # Intro -We aim to provide an easy to install and run modern framework for robotics +Our goal is to provide an easy to install and run modern framework for general robotics, you should be up and running in minutes. @@ -110,7 +110,7 @@ dimos run your_platform_blueprint [Blueprints](docs/api/blueprints.md) • [Modules](docs/api/modules.md) • [Transports](docs/api/transports.md) • -[Sensor Streams](docs/api/sensor_streams/README.md) • +[Data Streams](docs/api/data_streams/README.md) • [LCM](docs/api/lcm.md) • [Configuration](docs/api/configuration.md) • [Visualization](docs/api/visualization.md) @@ -119,8 +119,8 @@ dimos run your_platform_blueprint Python is our glue and prototyping language, but we support many languages, and ROS interop -check our examples/language-interop +check our [examples/language-interop](examples/language-interop/) # ROS interop -for researchers etc we can talk to ros directly via [ROS Transports](docs/api/transports.md), or we can host ROS deployments as first class Dimos Modules +for researchers we can talk to ros directly via [ROS Transports](docs/api/transports.md), or we can host ROS deployments as first class Dimos Modules diff --git a/docs/api/README.md b/docs/api/README.md index 071b6fc0b2..30831610bb 100644 --- a/docs/api/README.md +++ b/docs/api/README.md @@ -5,7 +5,7 @@ This page explains general concepts. ## Table of Contents - [Modules](/docs/usage/modules.md): The primary units of deployment in DimOS, modules run in parallel and are python classes. -- [Streams](/docs/usage/sensor_streams/README.md): How modules communicate, a Pub / Sub system. +- [Streams](/docs/usage/data_streams/README.md): How modules communicate, a Pub / Sub system. - [Blueprints](/docs/usage/blueprints.md): a way to group modules together and define their connections to each other. - [RPC](/docs/usage/blueprints.md#calling-the-methods-of-other-modules): how one module can call a method on another module (arguments get serialized to JSON-like binary data). - [Skills](/docs/usage/blueprints.md#defining-skills): An RPC function, except it can be called by an AI agent (a tool for an AI). diff --git a/docs/api/sensor_streams/README.md b/docs/api/data_streams/README.md similarity index 100% rename from docs/api/sensor_streams/README.md rename to docs/api/data_streams/README.md diff --git a/docs/api/sensor_streams/advanced_streams.md b/docs/api/data_streams/advanced_streams.md similarity index 100% rename from docs/api/sensor_streams/advanced_streams.md rename to docs/api/data_streams/advanced_streams.md diff --git a/docs/api/sensor_streams/assets/alignment_flow.svg b/docs/api/data_streams/assets/alignment_flow.svg similarity index 100% rename from docs/api/sensor_streams/assets/alignment_flow.svg rename to docs/api/data_streams/assets/alignment_flow.svg diff --git a/docs/api/sensor_streams/assets/alignment_overview.svg b/docs/api/data_streams/assets/alignment_overview.svg similarity index 100% rename from docs/api/sensor_streams/assets/alignment_overview.svg rename to docs/api/data_streams/assets/alignment_overview.svg diff --git a/docs/api/sensor_streams/assets/alignment_timeline.png b/docs/api/data_streams/assets/alignment_timeline.png similarity index 100% rename from docs/api/sensor_streams/assets/alignment_timeline.png rename to docs/api/data_streams/assets/alignment_timeline.png diff --git a/docs/api/sensor_streams/assets/alignment_timeline2.png b/docs/api/data_streams/assets/alignment_timeline2.png similarity index 100% rename from docs/api/sensor_streams/assets/alignment_timeline2.png rename to docs/api/data_streams/assets/alignment_timeline2.png diff --git a/docs/api/sensor_streams/assets/alignment_timeline3.png b/docs/api/data_streams/assets/alignment_timeline3.png similarity index 100% rename from docs/api/sensor_streams/assets/alignment_timeline3.png rename to docs/api/data_streams/assets/alignment_timeline3.png diff --git a/docs/api/sensor_streams/assets/backpressure.svg b/docs/api/data_streams/assets/backpressure.svg similarity index 100% rename from docs/api/sensor_streams/assets/backpressure.svg rename to docs/api/data_streams/assets/backpressure.svg diff --git a/docs/api/sensor_streams/assets/backpressure_solution.svg b/docs/api/data_streams/assets/backpressure_solution.svg similarity index 100% rename from docs/api/sensor_streams/assets/backpressure_solution.svg rename to docs/api/data_streams/assets/backpressure_solution.svg diff --git a/docs/api/sensor_streams/assets/frame_mosaic.jpg b/docs/api/data_streams/assets/frame_mosaic.jpg similarity index 100% rename from docs/api/sensor_streams/assets/frame_mosaic.jpg rename to docs/api/data_streams/assets/frame_mosaic.jpg diff --git a/docs/api/sensor_streams/assets/frame_mosaic2.jpg b/docs/api/data_streams/assets/frame_mosaic2.jpg similarity index 100% rename from docs/api/sensor_streams/assets/frame_mosaic2.jpg rename to docs/api/data_streams/assets/frame_mosaic2.jpg diff --git a/docs/api/sensor_streams/assets/getter_hot_cold.svg b/docs/api/data_streams/assets/getter_hot_cold.svg similarity index 100% rename from docs/api/sensor_streams/assets/getter_hot_cold.svg rename to docs/api/data_streams/assets/getter_hot_cold.svg diff --git a/docs/api/sensor_streams/assets/observable_flow.svg b/docs/api/data_streams/assets/observable_flow.svg similarity index 100% rename from docs/api/sensor_streams/assets/observable_flow.svg rename to docs/api/data_streams/assets/observable_flow.svg diff --git a/docs/api/sensor_streams/assets/sharpness_graph.svg b/docs/api/data_streams/assets/sharpness_graph.svg similarity index 100% rename from docs/api/sensor_streams/assets/sharpness_graph.svg rename to docs/api/data_streams/assets/sharpness_graph.svg diff --git a/docs/api/sensor_streams/assets/sharpness_graph2.svg b/docs/api/data_streams/assets/sharpness_graph2.svg similarity index 100% rename from docs/api/sensor_streams/assets/sharpness_graph2.svg rename to docs/api/data_streams/assets/sharpness_graph2.svg diff --git a/docs/api/sensor_streams/quality_filter.md b/docs/api/data_streams/quality_filter.md similarity index 100% rename from docs/api/sensor_streams/quality_filter.md rename to docs/api/data_streams/quality_filter.md diff --git a/docs/api/sensor_streams/reactivex.md b/docs/api/data_streams/reactivex.md similarity index 100% rename from docs/api/sensor_streams/reactivex.md rename to docs/api/data_streams/reactivex.md diff --git a/docs/api/sensor_streams/storage_replay.md b/docs/api/data_streams/storage_replay.md similarity index 100% rename from docs/api/sensor_streams/storage_replay.md rename to docs/api/data_streams/storage_replay.md diff --git a/docs/api/sensor_streams/temporal_alignment.md b/docs/api/data_streams/temporal_alignment.md similarity index 100% rename from docs/api/sensor_streams/temporal_alignment.md rename to docs/api/data_streams/temporal_alignment.md From c94eb5a7d77524f2e11fbeb87035ca42762e66e1 Mon Sep 17 00:00:00 2001 From: Ivan Nikolic Date: Sun, 15 Feb 2026 17:19:57 +0800 Subject: [PATCH 060/140] install --- NEWREADME.MD | 11 ++++++++++- 1 file changed, 10 insertions(+), 1 deletion(-) diff --git a/NEWREADME.MD b/NEWREADME.MD index c324ac2a5c..aa64796094 100644 --- a/NEWREADME.MD +++ b/NEWREADME.MD @@ -92,19 +92,28 @@ Our goal is to provide an easy to install and run modern framework for general r # Installation +## Step 1 - System Install + to setup your system dependencies follow one of these: - [NixOS / General Linux](docs/installation/nix.md) - [macOS](docs/installation/osx.md) - [Ubuntu 24.04](docs/installation/ubuntu.md) -then you are ready to jump into Python + +## Step 2 - Python Install + +We are ready to jump into Python ```sh pip install dimos[your_platform] dimos run your_platform_blueprint ``` +## Step 3 - Profit! + +![DimOS Demo](assets/readme/dimos_demo.gif) + # API [Blueprints](docs/api/blueprints.md) • From 2ea92f082bc49a9aacadfcee17d605aaf85dc5b4 Mon Sep 17 00:00:00 2001 From: Ivan Nikolic Date: Sun, 15 Feb 2026 17:21:14 +0800 Subject: [PATCH 061/140] .. --- NEWREADME.MD | 19 +++++++++++++++---- 1 file changed, 15 insertions(+), 4 deletions(-) diff --git a/NEWREADME.MD b/NEWREADME.MD index aa64796094..eb1e427bb5 100644 --- a/NEWREADME.MD +++ b/NEWREADME.MD @@ -68,22 +68,33 @@ Our goal is to provide an easy to install and run modern framework for general r + + + + + + + From 0a57c7def1a2b6196ae3b73e6fd219d4ab50e6cf Mon Sep 17 00:00:00 2001 From: Ivan Nikolic Date: Sun, 15 Feb 2026 17:21:55 +0800 Subject: [PATCH 062/140] .. --- NEWREADME.MD | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/NEWREADME.MD b/NEWREADME.MD index eb1e427bb5..d2a00f3254 100644 --- a/NEWREADME.MD +++ b/NEWREADME.MD @@ -125,7 +125,9 @@ dimos run your_platform_blueprint ![DimOS Demo](assets/readme/dimos_demo.gif) -# API +# Develop + +## API [Blueprints](docs/api/blueprints.md) • [Modules](docs/api/modules.md) • @@ -135,12 +137,12 @@ dimos run your_platform_blueprint [Configuration](docs/api/configuration.md) • [Visualization](docs/api/visualization.md) -# Multi Language Support +## Multi Language Support Python is our glue and prototyping language, but we support many languages, and ROS interop check our [examples/language-interop](examples/language-interop/) -# ROS interop +## ROS interop for researchers we can talk to ros directly via [ROS Transports](docs/api/transports.md), or we can host ROS deployments as first class Dimos Modules From ee208846337277edd0359838f57d3e72e8ebfae7 Mon Sep 17 00:00:00 2001 From: Ivan Nikolic Date: Sun, 15 Feb 2026 17:22:30 +0800 Subject: [PATCH 063/140] upload gif --- assets/readme/dimos_demo.gif | 3 +++ 1 file changed, 3 insertions(+) create mode 100644 assets/readme/dimos_demo.gif diff --git a/assets/readme/dimos_demo.gif b/assets/readme/dimos_demo.gif new file mode 100644 index 0000000000..5a68bd72ac --- /dev/null +++ b/assets/readme/dimos_demo.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:fda7f7a859ce98002e0faef88fb2942f395e19995b36b585c48447ec5a9435ee +size 24011189 From 9e8081bd3541cb3df136dc09be1b41639affd8ec Mon Sep 17 00:00:00 2001 From: Ivan Nikolic Date: Sun, 15 Feb 2026 17:23:45 +0800 Subject: [PATCH 064/140] .. --- NEWREADME.MD | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/NEWREADME.MD b/NEWREADME.MD index d2a00f3254..b734f4884c 100644 --- a/NEWREADME.MD +++ b/NEWREADME.MD @@ -103,7 +103,7 @@ Our goal is to provide an easy to install and run modern framework for general r # Installation -## Step 1 - System Install +### Step 1 - System Install to setup your system dependencies follow one of these: @@ -112,16 +112,16 @@ to setup your system dependencies follow one of these: - [Ubuntu 24.04](docs/installation/ubuntu.md) -## Step 2 - Python Install +### Step 2 - Python Install -We are ready to jump into Python +We are ready to jump into Python, check specific hardware docs above to choose appropriate pip install command and a blueprint to run ```sh pip install dimos[your_platform] dimos run your_platform_blueprint ``` -## Step 3 - Profit! +### Step 3 - Profit! ![DimOS Demo](assets/readme/dimos_demo.gif) From 878a13d9e8a8fe6daa954d0ebab9bd1d247d0792 Mon Sep 17 00:00:00 2001 From: Ivan Nikolic Date: Sun, 15 Feb 2026 17:26:39 +0800 Subject: [PATCH 065/140] .. --- NEWREADME.MD | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/NEWREADME.MD b/NEWREADME.MD index b734f4884c..7cafb8e842 100644 --- a/NEWREADME.MD +++ b/NEWREADME.MD @@ -55,7 +55,7 @@ Our goal is to provide an easy to install and run modern framework for general r

Dog

- Unitree Go2 pro/air

Humanoid

- Unitree G1

Arm

- Xarm
- Piper

Drone

+
+ Unitree Go2 pro/air
+ 		+ Unitree G1
+ 		+ Xarm
+ Piper
+ 		Mavlink
DJI SDK

Sensor Integrations

- Livox Mid360, Zed + Livox Mid360, Zed
@@ -129,13 +129,13 @@ dimos run your_platform_blueprint ## API -[Blueprints](docs/api/blueprints.md) • -[Modules](docs/api/modules.md) • -[Transports](docs/api/transports.md) • -[Data Streams](docs/api/data_streams/README.md) • -[LCM](docs/api/lcm.md) • -[Configuration](docs/api/configuration.md) • -[Visualization](docs/api/visualization.md) +- [Modules](docs/api/modules.md) +- [LCM](docs/api/lcm.md) +- [Blueprints](docs/api/blueprints.md) +- [Transports](docs/api/transports.md) +- [Data Streams](docs/api/data_streams/README.md) +- [Configuration](docs/api/configuration.md) +- [Visualization](docs/api/visualization.md) ## Multi Language Support From 214cd2e74e39776892e0945e593d758f2eb7f556 Mon Sep 17 00:00:00 2001 From: Ivan Nikolic Date: Sun, 15 Feb 2026 17:29:38 +0800 Subject: [PATCH 066/140] .. --- NEWREADME.MD | 22 +++++++++++----------- 1 file changed, 11 insertions(+), 11 deletions(-) diff --git a/NEWREADME.MD b/NEWREADME.MD index 7cafb8e842..a7e011e47d 100644 --- a/NEWREADME.MD +++ b/NEWREADME.MD @@ -19,7 +19,7 @@ # Intro -Our goal is to provide an easy to install and run modern framework for general robotics, you should be up and running in minutes. +Our goal is to provide an easy-to-install, modern framework for general robotics. You should be up and running in minutes. @@ -103,27 +103,27 @@ Our goal is to provide an easy to install and run modern framework for general r # Installation -### Step 1 - System Install +### Step 1: System Install -to setup your system dependencies follow one of these: +To set up your system dependencies, follow one of these guides: - [NixOS / General Linux](docs/installation/nix.md) - [macOS](docs/installation/osx.md) - [Ubuntu 24.04](docs/installation/ubuntu.md) +- [Docker](docs/installation/docker.md) +### Step 2: Python Install -### Step 2 - Python Install - -We are ready to jump into Python, check specific hardware docs above to choose appropriate pip install command and a blueprint to run +Now install the Python package. Check the [hardware docs](#hardware) above to choose the right extras and blueprint for your platform. ```sh pip install dimos[your_platform] dimos run your_platform_blueprint ``` -### Step 3 - Profit! +### Step 3 - Profit -![DimOS Demo](assets/readme/dimos_demo.gif) +DimOS Demo # Develop @@ -139,10 +139,10 @@ dimos run your_platform_blueprint ## Multi Language Support -Python is our glue and prototyping language, but we support many languages, and ROS interop +Python is our glue and prototyping language, but we support many languages via LCM interop. -check our [examples/language-interop](examples/language-interop/) +Check our [examples/language-interop](examples/language-interop/) for C++, Lua, and TypeScript examples. ## ROS interop -for researchers we can talk to ros directly via [ROS Transports](docs/api/transports.md), or we can host ROS deployments as first class Dimos Modules +For researchers, we can talk to ROS directly via [ROS Transports](docs/api/transports.md), or host ROS deployments as first-class DimOS modules. From f9bcc279af3b82159a6fe2793677ba6ae7cb1071 Mon Sep 17 00:00:00 2001 From: Ivan Nikolic Date: Sun, 15 Feb 2026 17:31:09 +0800 Subject: [PATCH 067/140] .. --- NEWREADME.MD | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/NEWREADME.MD b/NEWREADME.MD index a7e011e47d..997f7c6e05 100644 --- a/NEWREADME.MD +++ b/NEWREADME.MD @@ -66,20 +66,20 @@ Our goal is to provide an easy-to-install, modern framework for general robotics
From f38cb5069a259ecbd342de7238c8f1e55f8fe0c9 Mon Sep 17 00:00:00 2001 From: Ivan Nikolic Date: Sun, 15 Feb 2026 17:33:26 +0800 Subject: [PATCH 068/140] .. --- NEWREADME.MD | 19 ++++++++++--------- 1 file changed, 10 insertions(+), 9 deletions(-) diff --git a/NEWREADME.MD b/NEWREADME.MD index 997f7c6e05..d4ce65801b 100644 --- a/NEWREADME.MD +++ b/NEWREADME.MD @@ -7,11 +7,12 @@ -[Features](#the-dimensional-framework) • +[Intro](#intro) • +[Hardware](#hardware) • [Installation](#installation) • -[Documentation](#documentation) • -[Development](#development) • -[Contributing](#contributing) +[Development](#develop) • +[Multi Language](#multi-language-support) • +[ROS](#ros-interop) @@ -67,19 +68,19 @@ Our goal is to provide an easy-to-install, modern framework for general robotics @@ -125,7 +126,7 @@ dimos run your_platform_blueprint DimOS Demo -# Develop +# Development ## API From c1a31a0874800f1236542ff7e8152e3f409bb4af Mon Sep 17 00:00:00 2001 From: Ivan Nikolic Date: Sun, 15 Feb 2026 17:37:00 +0800 Subject: [PATCH 069/140] .. --- NEWREADME.MD | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/NEWREADME.MD b/NEWREADME.MD index d4ce65801b..657510230a 100644 --- a/NEWREADME.MD +++ b/NEWREADME.MD @@ -10,7 +10,7 @@ [Intro](#intro) • [Hardware](#hardware) • [Installation](#installation) • -[Development](#develop) • +[Development](#development) • [Multi Language](#multi-language-support) • [ROS](#ros-interop) @@ -86,18 +86,18 @@ Our goal is to provide an easy-to-install, modern framework for general robotics
-

Dog

- +

Quadruped

+

Humanoid

- +

Arm

- +

Drone

- +

Quadruped

- +

Humanoid

- +

Arm

- +

Drone

- +
- Unitree Go2 pro/air
+ Unitree Go2 pro/air
- Unitree G1
+ Unitree G1
- Xarm
- Piper
+ Xarm
+ Piper
- Mavlink
- DJI SDK
+ Mavlink
+ DJI SDK
From d8fd8946150b3d0175c7a8744668fabe0e1ec5ea Mon Sep 17 00:00:00 2001 From: Ivan Nikolic Date: Sun, 15 Feb 2026 17:38:22 +0800 Subject: [PATCH 070/140] .. --- NEWREADME.MD | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/NEWREADME.MD b/NEWREADME.MD index 657510230a..d98740148e 100644 --- a/NEWREADME.MD +++ b/NEWREADME.MD @@ -7,6 +7,16 @@ +[![Discord](https://img.shields.io/discord/1341146487186391173?style=flat-square&logo=discord&logoColor=white&label=Discord&color=5865F2)](https://discord.gg/dimos) +[![Stars](https://img.shields.io/github/stars/dimensionalOS/dimos?style=flat-square)](https://github.com/dimensionalOS/dimos/stargazers) +[![Forks](https://img.shields.io/github/forks/dimensionalOS/dimos?style=flat-square)](https://github.com/dimensionalOS/dimos/fork) +[![Contributors](https://img.shields.io/github/contributors/dimensionalOS/dimos?style=flat-square)](https://github.com/dimensionalOS/dimos/graphs/contributors) +![Nix](https://img.shields.io/badge/Nix-flakes-5277C3?style=flat-square&logo=NixOS&logoColor=white) +![NixOS](https://img.shields.io/badge/NixOS-supported-5277C3?style=flat-square&logo=NixOS&logoColor=white) +![CUDA](https://img.shields.io/badge/CUDA-12.x-76B900?style=flat-square&logo=nvidia&logoColor=white) +[![Docker](https://img.shields.io/badge/Docker-ready-2496ED?style=flat-square&logo=docker&logoColor=white)](https://www.docker.com/) + + [Intro](#intro) • [Hardware](#hardware) • [Installation](#installation) • From 2330719e4c86b3f8b4864843b3529f8d82b31042 Mon Sep 17 00:00:00 2001 From: Ivan Nikolic Date: Sun, 15 Feb 2026 17:39:55 +0800 Subject: [PATCH 071/140] .. --- NEWREADME.MD | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/NEWREADME.MD b/NEWREADME.MD index d98740148e..80e1f14eb4 100644 --- a/NEWREADME.MD +++ b/NEWREADME.MD @@ -3,9 +3,6 @@ ![Dimensional](assets/dimensional-dark.svg#gh-dark-mode-only) ![Dimensional](assets/dimensional-light.svg#gh-light-mode-only) -

Operating System for Generalist Robotics

- - [![Discord](https://img.shields.io/discord/1341146487186391173?style=flat-square&logo=discord&logoColor=white&label=Discord&color=5865F2)](https://discord.gg/dimos) [![Stars](https://img.shields.io/github/stars/dimensionalOS/dimos?style=flat-square)](https://github.com/dimensionalOS/dimos/stargazers) @@ -16,6 +13,9 @@ ![CUDA](https://img.shields.io/badge/CUDA-12.x-76B900?style=flat-square&logo=nvidia&logoColor=white) [![Docker](https://img.shields.io/badge/Docker-ready-2496ED?style=flat-square&logo=docker&logoColor=white)](https://www.docker.com/) +

Operating System for Generalist Robotics

+ + [Intro](#intro) • [Hardware](#hardware) • From 778bab16156960c9edaf9777f727ba4e3fd2cc7a Mon Sep 17 00:00:00 2001 From: Ivan Nikolic Date: Sun, 15 Feb 2026 17:40:57 +0800 Subject: [PATCH 072/140] .. --- NEWREADME.MD | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/NEWREADME.MD b/NEWREADME.MD index 80e1f14eb4..b057a8f577 100644 --- a/NEWREADME.MD +++ b/NEWREADME.MD @@ -4,6 +4,8 @@ ![Dimensional](assets/dimensional-dark.svg#gh-dark-mode-only) ![Dimensional](assets/dimensional-light.svg#gh-light-mode-only) +

Operating System for Generalist Robotics

+ [![Discord](https://img.shields.io/discord/1341146487186391173?style=flat-square&logo=discord&logoColor=white&label=Discord&color=5865F2)](https://discord.gg/dimos) [![Stars](https://img.shields.io/github/stars/dimensionalOS/dimos?style=flat-square)](https://github.com/dimensionalOS/dimos/stargazers) [![Forks](https://img.shields.io/github/forks/dimensionalOS/dimos?style=flat-square)](https://github.com/dimensionalOS/dimos/fork) @@ -11,10 +13,9 @@ ![Nix](https://img.shields.io/badge/Nix-flakes-5277C3?style=flat-square&logo=NixOS&logoColor=white) ![NixOS](https://img.shields.io/badge/NixOS-supported-5277C3?style=flat-square&logo=NixOS&logoColor=white) ![CUDA](https://img.shields.io/badge/CUDA-12.x-76B900?style=flat-square&logo=nvidia&logoColor=white) +![CUDA](https://img.shields.io/badge/CUDA-13.x-76B900?style=flat-square&logo=nvidia&logoColor=white) [![Docker](https://img.shields.io/badge/Docker-ready-2496ED?style=flat-square&logo=docker&logoColor=white)](https://www.docker.com/) -

Operating System for Generalist Robotics

- [Intro](#intro) • From 75b0c4199ac0e87ba7680d925f8fd0a1a73578a1 Mon Sep 17 00:00:00 2001 From: Ivan Nikolic Date: Sun, 15 Feb 2026 17:42:01 +0800 Subject: [PATCH 073/140] .. --- NEWREADME.MD | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/NEWREADME.MD b/NEWREADME.MD index b057a8f577..c36293e127 100644 --- a/NEWREADME.MD +++ b/NEWREADME.MD @@ -12,8 +12,7 @@ [![Contributors](https://img.shields.io/github/contributors/dimensionalOS/dimos?style=flat-square)](https://github.com/dimensionalOS/dimos/graphs/contributors) ![Nix](https://img.shields.io/badge/Nix-flakes-5277C3?style=flat-square&logo=NixOS&logoColor=white) ![NixOS](https://img.shields.io/badge/NixOS-supported-5277C3?style=flat-square&logo=NixOS&logoColor=white) -![CUDA](https://img.shields.io/badge/CUDA-12.x-76B900?style=flat-square&logo=nvidia&logoColor=white) -![CUDA](https://img.shields.io/badge/CUDA-13.x-76B900?style=flat-square&logo=nvidia&logoColor=white) +![CUDA](https://img.shields.io/badge/CUDA-supported-76B900?style=flat-square&logo=nvidia&logoColor=white) [![Docker](https://img.shields.io/badge/Docker-ready-2496ED?style=flat-square&logo=docker&logoColor=white)](https://www.docker.com/) From 5faea0b5ec0b8130bedc5ecda132b5e190fbbb9a Mon Sep 17 00:00:00 2001 From: Ivan Nikolic Date: Sun, 15 Feb 2026 17:43:33 +0800 Subject: [PATCH 074/140] .. --- NEWREADME.MD | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/NEWREADME.MD b/NEWREADME.MD index c36293e127..49879189dd 100644 --- a/NEWREADME.MD +++ b/NEWREADME.MD @@ -15,16 +15,15 @@ ![CUDA](https://img.shields.io/badge/CUDA-supported-76B900?style=flat-square&logo=nvidia&logoColor=white) [![Docker](https://img.shields.io/badge/Docker-ready-2496ED?style=flat-square&logo=docker&logoColor=white)](https://www.docker.com/) - + -[Intro](#intro) • [Hardware](#hardware) • [Installation](#installation) • [Development](#development) • [Multi Language](#multi-language-support) • [ROS](#ros-interop) - +
From 756991775e3ae50a50a09ccd0c8762198207cd68 Mon Sep 17 00:00:00 2001 From: Ivan Nikolic Date: Sun, 15 Feb 2026 17:45:59 +0800 Subject: [PATCH 075/140] .. --- NEWREADME.MD | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/NEWREADME.MD b/NEWREADME.MD index 49879189dd..66d61fc969 100644 --- a/NEWREADME.MD +++ b/NEWREADME.MD @@ -111,6 +111,8 @@ Our goal is to provide an easy-to-install, modern framework for general robotics +[New Hardware Integration Guide](docs/hardware/integration_guide.md) + # Installation ### Step 1: System Install @@ -124,7 +126,9 @@ To set up your system dependencies, follow one of these guides: ### Step 2: Python Install -Now install the Python package. Check the [hardware docs](#hardware) above to choose the right extras and blueprint for your platform. +Now install the Python package. + +Check the [hardware section](#hardware) above to choose the right `extras` and `blueprint` for your platform. ```sh pip install dimos[your_platform] From 6fb43fcbb261b22b16dee7a855b05225ff879025 Mon Sep 17 00:00:00 2001 From: Ivan Nikolic Date: Sun, 15 Feb 2026 17:48:30 +0800 Subject: [PATCH 076/140] .. --- NEWREADME.MD | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/NEWREADME.MD b/NEWREADME.MD index 66d61fc969..ab64261447 100644 --- a/NEWREADME.MD +++ b/NEWREADME.MD @@ -130,10 +130,9 @@ Now install the Python package. Check the [hardware section](#hardware) above to choose the right `extras` and `blueprint` for your platform. -```sh -pip install dimos[your_platform] -dimos run your_platform_blueprint -``` +$${\Large\color{cyan}\texttt{pip}\ \color{white}\texttt{install}\ \color{green}\texttt{dimos}\color{gray}\texttt{[}\color{yellow}\texttt{your\_platform}\color{gray}\texttt{]}}$$ + +$${\Large\color{cyan}\texttt{dimos}\ \color{white}\texttt{run}\ \color{yellow}\texttt{your\_platform\_blueprint}}$$ ### Step 3 - Profit From 66b5e5967b893be889eb213efd25f0624a78e6f2 Mon Sep 17 00:00:00 2001 From: Ivan Nikolic Date: Sun, 15 Feb 2026 17:50:51 +0800 Subject: [PATCH 077/140] .. --- NEWREADME.MD | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/NEWREADME.MD b/NEWREADME.MD index ab64261447..732cfcab44 100644 --- a/NEWREADME.MD +++ b/NEWREADME.MD @@ -130,9 +130,9 @@ Now install the Python package. Check the [hardware section](#hardware) above to choose the right `extras` and `blueprint` for your platform. -$${\Large\color{cyan}\texttt{pip}\ \color{white}\texttt{install}\ \color{green}\texttt{dimos}\color{gray}\texttt{[}\color{yellow}\texttt{your\_platform}\color{gray}\texttt{]}}$$ +$${\Large\color{cyan}\mathtt{pip}\ \color{white}\mathtt{install}\ \color{green}\mathtt{dimos}\color{gray}\mathtt{[}\color{yellow}\mathtt{your\textunderscore platform}\color{gray}\mathtt{]}}$$ -$${\Large\color{cyan}\texttt{dimos}\ \color{white}\texttt{run}\ \color{yellow}\texttt{your\_platform\_blueprint}}$$ +$${\Large\color{cyan}\mathtt{dimos}\ \color{white}\mathtt{run}\ \color{yellow}\mathtt{your\textunderscore platform\textunderscore blueprint}}$$ ### Step 3 - Profit From a4dd38761a77c5b4de421a1718ffca127aa0b531 Mon Sep 17 00:00:00 2001 From: Ivan Nikolic Date: Sun, 15 Feb 2026 17:52:26 +0800 Subject: [PATCH 078/140] .. --- NEWREADME.MD | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/NEWREADME.MD b/NEWREADME.MD index 732cfcab44..bf6085ca7a 100644 --- a/NEWREADME.MD +++ b/NEWREADME.MD @@ -111,7 +111,7 @@ Our goal is to provide an easy-to-install, modern framework for general robotics -[New Hardware Integration Guide](docs/hardware/integration_guide.md) +New Hardware Integration Guide # Installation @@ -130,9 +130,10 @@ Now install the Python package. Check the [hardware section](#hardware) above to choose the right `extras` and `blueprint` for your platform. -$${\Large\color{cyan}\mathtt{pip}\ \color{white}\mathtt{install}\ \color{green}\mathtt{dimos}\color{gray}\mathtt{[}\color{yellow}\mathtt{your\textunderscore platform}\color{gray}\mathtt{]}}$$ - -$${\Large\color{cyan}\mathtt{dimos}\ \color{white}\mathtt{run}\ \color{yellow}\mathtt{your\textunderscore platform\textunderscore blueprint}}$$ +```bash +pip install dimos[your_platform] +dimos run your_platform_blueprint +``` ### Step 3 - Profit From 5b2740cfc57071fa54b2620adf6147631c1c0410 Mon Sep 17 00:00:00 2001 From: Ivan Nikolic Date: Sun, 15 Feb 2026 17:54:39 +0800 Subject: [PATCH 079/140] .. --- NEWREADME.MD | 13 +++++++++++++ 1 file changed, 13 insertions(+) diff --git a/NEWREADME.MD b/NEWREADME.MD index bf6085ca7a..bdf4002eb8 100644 --- a/NEWREADME.MD +++ b/NEWREADME.MD @@ -130,11 +130,24 @@ Now install the Python package. Check the [hardware section](#hardware) above to choose the right `extras` and `blueprint` for your platform. +To use DimOS as a library / UI + ```bash pip install dimos[your_platform] dimos run your_platform_blueprint ``` +To develop on DimOS + +```bash +git clone https://github.com/dimensionalOS/dimos/ dimos +cd dimos +uv sync --all-extras +mypy dimos +pytest dimos +dimos --replay run unitree-go2 +``` + ### Step 3 - Profit DimOS Demo From e54cb67f9daca1a72207747a748565f2fd5c53b6 Mon Sep 17 00:00:00 2001 From: Ivan Nikolic Date: Sun, 15 Feb 2026 17:56:37 +0800 Subject: [PATCH 080/140] .. --- NEWREADME.MD | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/NEWREADME.MD b/NEWREADME.MD index bdf4002eb8..8d806bcd1a 100644 --- a/NEWREADME.MD +++ b/NEWREADME.MD @@ -130,18 +130,20 @@ Now install the Python package. Check the [hardware section](#hardware) above to choose the right `extras` and `blueprint` for your platform. -To use DimOS as a library / UI +*Use DimOS as a library / UI* ```bash pip install dimos[your_platform] dimos run your_platform_blueprint ``` -To develop on DimOS +*Develop DimOS* ```bash git clone https://github.com/dimensionalOS/dimos/ dimos cd dimos +uv venv -p 3.12 +source .venv/bin/activate uv sync --all-extras mypy dimos pytest dimos From bcb478e2f61b20c42184f837bf221b14319cd349 Mon Sep 17 00:00:00 2001 From: Ivan Nikolic Date: Sun, 15 Feb 2026 17:57:56 +0800 Subject: [PATCH 081/140] .. --- NEWREADME.MD | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/NEWREADME.MD b/NEWREADME.MD index 8d806bcd1a..085826a488 100644 --- a/NEWREADME.MD +++ b/NEWREADME.MD @@ -130,14 +130,14 @@ Now install the Python package. Check the [hardware section](#hardware) above to choose the right `extras` and `blueprint` for your platform. -*Use DimOS as a library / UI* +**Use DimOS as a library / UI** ```bash pip install dimos[your_platform] dimos run your_platform_blueprint ``` -*Develop DimOS* +**Develop DimOS** ```bash git clone https://github.com/dimensionalOS/dimos/ dimos From c9a1f5610d2b552dd0151056febfca86c331f832 Mon Sep 17 00:00:00 2001 From: Ivan Nikolic Date: Sun, 15 Feb 2026 17:59:29 +0800 Subject: [PATCH 082/140] .. --- NEWREADME.MD | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/NEWREADME.MD b/NEWREADME.MD index 085826a488..6123894382 100644 --- a/NEWREADME.MD +++ b/NEWREADME.MD @@ -170,7 +170,10 @@ dimos --replay run unitree-go2 Python is our glue and prototyping language, but we support many languages via LCM interop. -Check our [examples/language-interop](examples/language-interop/) for C++, Lua, and TypeScript examples. +Check our language interop examples: +- [C++](examples/language-interop/cpp/) +- [Lua](examples/language-interop/lua/) +- [TypeScript](examples/language-interop/ts/) ## ROS interop From a986e7c40a96342dab80c57d6001f2db0f779cb8 Mon Sep 17 00:00:00 2001 From: Ivan Nikolic Date: Sun, 15 Feb 2026 18:03:02 +0800 Subject: [PATCH 083/140] .. --- NEWREADME.MD | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/NEWREADME.MD b/NEWREADME.MD index 6123894382..5efb4add76 100644 --- a/NEWREADME.MD +++ b/NEWREADME.MD @@ -111,7 +111,7 @@ Our goal is to provide an easy-to-install, modern framework for general robotics -New Hardware Integration Guide +[New Hardware Integration Guide](docs/hardware/integration_guide.md) # Installation @@ -177,4 +177,4 @@ Check our language interop examples: ## ROS interop -For researchers, we can talk to ROS directly via [ROS Transports](docs/api/transports.md), or host ROS deployments as first-class DimOS modules. +For researchers, we can talk to ROS directly via [ROS Transports](docs/api/transports.md), or host dockerized ROS deployments as first-class DimOS modules, allowing you easy installation and portability From 6c7adee076a0b230a56a758425a159d19a879d86 Mon Sep 17 00:00:00 2001 From: Ivan Nikolic Date: Sun, 15 Feb 2026 18:06:44 +0800 Subject: [PATCH 084/140] torque --- NEWREADME.MD | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/NEWREADME.MD b/NEWREADME.MD index 5efb4add76..5d3c77020a 100644 --- a/NEWREADME.MD +++ b/NEWREADME.MD @@ -91,6 +91,10 @@ Our goal is to provide an easy-to-install, modern framework for general robotics

Drone

+ +

Misc

+ + @@ -108,6 +112,9 @@ Our goal is to provide an easy-to-install, modern framework for general robotics Mavlink
DJI SDK
+ + Force Torque Sensor
+ From 795172ab2bc641ac9b5f793a94a2fa59d0c531b3 Mon Sep 17 00:00:00 2001 From: Ivan Nikolic Date: Sun, 15 Feb 2026 18:07:43 +0800 Subject: [PATCH 085/140] .. --- NEWREADME.MD | 20 ++++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/NEWREADME.MD b/NEWREADME.MD index 5d3c77020a..7aa7b4f8a3 100644 --- a/NEWREADME.MD +++ b/NEWREADME.MD @@ -75,44 +75,44 @@ Our goal is to provide an easy-to-install, modern framework for general robotics - - - - - - - - - - From ac3444cd5118a09ea79b8ce4387e2aa789ce773b Mon Sep 17 00:00:00 2001 From: Ivan Nikolic Date: Sun, 15 Feb 2026 18:10:23 +0800 Subject: [PATCH 086/140] .. --- NEWREADME.MD | 16 +++++++++------- 1 file changed, 9 insertions(+), 7 deletions(-) diff --git a/NEWREADME.MD b/NEWREADME.MD index 7aa7b4f8a3..6475e3eb9d 100644 --- a/NEWREADME.MD +++ b/NEWREADME.MD @@ -99,25 +99,27 @@ Our goal is to provide an easy-to-install, modern framework for general robotics
+

Quadruped

 +

Humanoid

 +

Arm

 +

Drone

 +

Misc
+ Unitree Go2 pro/air
+ Unitree G1
+ Xarm
Piper
+ Mavlink
DJI SDK
+ Force Torque Sensor
- Unitree Go2 pro/air
+ Unitree Go2 pro/air 🟢
 - Unitree G1
+ Unitree G1 🟠
 - Xarm
- Piper
+ Xarm 🟡
+ Piper 🟡
 - Mavlink
- DJI SDK
+ Mavlink 🟠
+ DJI SDK 🔴
 - Force Torque Sensor
+ Force Torque Sensor 🟡
+🟢 stable · 🟡 beta · 🟠 alpha · 🔴 experimental + [New Hardware Integration Guide](docs/hardware/integration_guide.md) # Installation From 5192f8463bd1da69c2e0f434c74d77cad8749d55 Mon Sep 17 00:00:00 2001 From: Ivan Nikolic Date: Sun, 15 Feb 2026 18:11:48 +0800 Subject: [PATCH 087/140] .. --- NEWREADME.MD | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/NEWREADME.MD b/NEWREADME.MD index 6475e3eb9d..3a9d7b90c4 100644 --- a/NEWREADME.MD +++ b/NEWREADME.MD @@ -72,6 +72,9 @@ Our goal is to provide an easy-to-install, modern framework for general robotics # Hardware +
+🟢 stable • 🟡 beta • 🟠 alpha • 🔴 experimental +
@@ -118,7 +121,6 @@ Our goal is to provide an easy-to-install, modern framework for general robotics
-🟢 stable · 🟡 beta · 🟠 alpha · 🔴 experimental [New Hardware Integration Guide](docs/hardware/integration_guide.md) From 2e059fef6873df4b4cbdc430dd47d065f27ad531 Mon Sep 17 00:00:00 2001 From: Ivan Nikolic Date: Sun, 15 Feb 2026 18:12:59 +0800 Subject: [PATCH 088/140] .. --- NEWREADME.MD | 2 ++ 1 file changed, 2 insertions(+) diff --git a/NEWREADME.MD b/NEWREADME.MD index 3a9d7b90c4..0c99f2969e 100644 --- a/NEWREADME.MD +++ b/NEWREADME.MD @@ -76,6 +76,8 @@ Our goal is to provide an easy-to-install, modern framework for general robotics 🟢 stable • 🟡 beta • 🟠 alpha • 🔴 experimental
+
+
From 4f088d0638105783509e6299e29d9db17dcb5ff1 Mon Sep 17 00:00:00 2001 From: Ivan Nikolic Date: Sun, 15 Feb 2026 18:14:00 +0800 Subject: [PATCH 089/140] .. --- NEWREADME.MD | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/NEWREADME.MD b/NEWREADME.MD index 0c99f2969e..7d4bfc392b 100644 --- a/NEWREADME.MD +++ b/NEWREADME.MD @@ -72,10 +72,11 @@ Our goal is to provide an easy-to-install, modern framework for general robotics # Hardware + +
🟢 stable • 🟡 beta • 🟠 alpha • 🔴 experimental
-
From edd3258c4463611e428748fde341dd8eac14c162 Mon Sep 17 00:00:00 2001 From: Ivan Nikolic Date: Sun, 15 Feb 2026 18:14:17 +0800 Subject: [PATCH 090/140] .. --- NEWREADME.MD | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/NEWREADME.MD b/NEWREADME.MD index 7d4bfc392b..cf10021b6a 100644 --- a/NEWREADME.MD +++ b/NEWREADME.MD @@ -75,7 +75,7 @@ Our goal is to provide an easy-to-install, modern framework for general robotics
-🟢 stable • 🟡 beta • 🟠 alpha • 🔴 experimental +🟢 stable 🟡 beta 🟠 alpha 🔴 experimental

From 70f302b2b8e8bb4340d088148cabfea8c01622fb Mon Sep 17 00:00:00 2001 From: Ivan Nikolic Date: Sun, 15 Feb 2026 18:14:50 +0800 Subject: [PATCH 091/140] .. --- NEWREADME.MD | 11 ++++------- 1 file changed, 4 insertions(+), 7 deletions(-) diff --git a/NEWREADME.MD b/NEWREADME.MD index cf10021b6a..9cf38f6287 100644 --- a/NEWREADME.MD +++ b/NEWREADME.MD @@ -73,12 +73,6 @@ Our goal is to provide an easy-to-install, modern framework for general robotics # Hardware -
-
-🟢 stable 🟡 beta 🟠 alpha 🔴 experimental -
-
-
@@ -123,7 +117,10 @@ Our goal is to provide an easy-to-install, modern framework for general robotics
- +
+
+🟢 stable 🟡 beta 🟠 alpha 🔴 experimental +
[New Hardware Integration Guide](docs/hardware/integration_guide.md) From 2f37e5d172da277179791fb92be36bd87bea6336 Mon Sep 17 00:00:00 2001 From: Ivan Nikolic Date: Sun, 15 Feb 2026 18:16:38 +0800 Subject: [PATCH 092/140] .. --- NEWREADME.MD | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/NEWREADME.MD b/NEWREADME.MD index 9cf38f6287..9e86dd2265 100644 --- a/NEWREADME.MD +++ b/NEWREADME.MD @@ -99,27 +99,27 @@ Our goal is to provide an easy-to-install, modern framework for general robotics
- Unitree Go2 pro/air 🟢
+ Unitree Go2 pro/air 🟩
 - Unitree G1 🟠
+ Unitree G1 🟧
 - Xarm 🟡
- Piper 🟡
+ Xarm 🟦
+ Piper 🟦
 - Mavlink 🟠
- DJI SDK 🔴
+ Mavlink 🟧
+ DJI SDK 🟥
 - Force Torque Sensor 🟡
+ Force Torque Sensor 🟦

-🟢 stable 🟡 beta 🟠 alpha 🔴 experimental +🟩 stable 🟦 beta 🟧 alpha 🟥 experimental
[New Hardware Integration Guide](docs/hardware/integration_guide.md) From 4e7adeb12d0eddd19b86ed1f63575d47ec4cb9fd Mon Sep 17 00:00:00 2001 From: Ivan Nikolic Date: Sun, 15 Feb 2026 18:18:02 +0800 Subject: [PATCH 093/140] .. --- NEWREADME.MD | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/NEWREADME.MD b/NEWREADME.MD index 9e86dd2265..079cc6928a 100644 --- a/NEWREADME.MD +++ b/NEWREADME.MD @@ -105,21 +105,22 @@ Our goal is to provide an easy-to-install, modern framework for general robotics Unitree G1 🟧
- Xarm 🟦
- Piper 🟦
+ Xarm 🟨
+ Piper 🟨
Mavlink 🟧
DJI SDK 🟥
- Force Torque Sensor 🟦
+ Force Torque Sensor 🟨

-🟩 stable 🟦 beta 🟧 alpha 🟥 experimental +🟩 stable 🟨 beta 🟧 alpha 🟥 experimental +
[New Hardware Integration Guide](docs/hardware/integration_guide.md) From c32fcf2b5a773de2c3de6d65b67052533fd4f722 Mon Sep 17 00:00:00 2001 From: Ivan Nikolic Date: Sun, 15 Feb 2026 18:18:59 +0800 Subject: [PATCH 094/140] .. --- NEWREADME.MD | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/NEWREADME.MD b/NEWREADME.MD index 079cc6928a..23c850216a 100644 --- a/NEWREADME.MD +++ b/NEWREADME.MD @@ -131,10 +131,10 @@ Our goal is to provide an easy-to-install, modern framework for general robotics To set up your system dependencies, follow one of these guides: -- [NixOS / General Linux](docs/installation/nix.md) -- [macOS](docs/installation/osx.md) -- [Ubuntu 24.04](docs/installation/ubuntu.md) -- [Docker](docs/installation/docker.md) +- [NixOS / General Linux](docs/installation/nix.md) 🟩 +- [macOS](docs/installation/osx.md) 🟥 +- [Ubuntu 24.04](docs/installation/ubuntu.md) 🟩 +- [Docker](docs/installation/docker.md) 🟨 ### Step 2: Python Install From cd4789d30f6c9283979963511753a475f9112b98 Mon Sep 17 00:00:00 2001 From: Ivan Nikolic Date: Sun, 15 Feb 2026 18:20:25 +0800 Subject: [PATCH 095/140] .. --- NEWREADME.MD | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/NEWREADME.MD b/NEWREADME.MD index 23c850216a..7631f79d1e 100644 --- a/NEWREADME.MD +++ b/NEWREADME.MD @@ -131,10 +131,10 @@ Our goal is to provide an easy-to-install, modern framework for general robotics To set up your system dependencies, follow one of these guides: -- [NixOS / General Linux](docs/installation/nix.md) 🟩 -- [macOS](docs/installation/osx.md) 🟥 -- [Ubuntu 24.04](docs/installation/ubuntu.md) 🟩 -- [Docker](docs/installation/docker.md) 🟨 +- 🟩 [NixOS / General Linux](docs/installation/nix.md) +- 🟥 [macOS](docs/installation/osx.md) +- 🟩 [Ubuntu 24.04](docs/installation/ubuntu.md) +- 🟨 [Docker](docs/installation/docker.md) ### Step 2: Python Install From 619124eeed8edb15dd0807860d220917a6b6caf2 Mon Sep 17 00:00:00 2001 From: Ivan Nikolic Date: Sun, 15 Feb 2026 18:21:26 +0800 Subject: [PATCH 096/140] .. --- NEWREADME.MD | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/NEWREADME.MD b/NEWREADME.MD index 7631f79d1e..87b927d0f1 100644 --- a/NEWREADME.MD +++ b/NEWREADME.MD @@ -99,21 +99,21 @@ Our goal is to provide an easy-to-install, modern framework for general robotics - Unitree Go2 pro/air 🟩
+ 🟩 Unitree Go2 pro/air
- Unitree G1 🟧
+ 🟧 Unitree G1
- Xarm 🟨
- Piper 🟨
+ 🟨 Xarm
+ 🟨 Piper
- Mavlink 🟧
- DJI SDK 🟥
+ 🟧 Mavlink
+ 🟥 DJI SDK
- Force Torque Sensor 🟨
+ 🟨 Force Torque Sensor
From 7adec9ad278bab874653428f656a5d974cf18574 Mon Sep 17 00:00:00 2001 From: Ivan Nikolic Date: Sun, 15 Feb 2026 21:02:00 +0800 Subject: [PATCH 097/140] .. --- NEWREADME.MD | 192 --------------------------- README.md | 360 +++++++++++++++++++++------------------------------ 2 files changed, 150 insertions(+), 402 deletions(-) delete mode 100644 NEWREADME.MD diff --git a/NEWREADME.MD b/NEWREADME.MD deleted file mode 100644 index 87b927d0f1..0000000000 --- a/NEWREADME.MD +++ /dev/null @@ -1,192 +0,0 @@ - -
- -![Dimensional](assets/dimensional-dark.svg#gh-dark-mode-only) -![Dimensional](assets/dimensional-light.svg#gh-light-mode-only) - -

Operating System for Generalist Robotics

- -[![Discord](https://img.shields.io/discord/1341146487186391173?style=flat-square&logo=discord&logoColor=white&label=Discord&color=5865F2)](https://discord.gg/dimos) -[![Stars](https://img.shields.io/github/stars/dimensionalOS/dimos?style=flat-square)](https://github.com/dimensionalOS/dimos/stargazers) -[![Forks](https://img.shields.io/github/forks/dimensionalOS/dimos?style=flat-square)](https://github.com/dimensionalOS/dimos/fork) -[![Contributors](https://img.shields.io/github/contributors/dimensionalOS/dimos?style=flat-square)](https://github.com/dimensionalOS/dimos/graphs/contributors) -![Nix](https://img.shields.io/badge/Nix-flakes-5277C3?style=flat-square&logo=NixOS&logoColor=white) -![NixOS](https://img.shields.io/badge/NixOS-supported-5277C3?style=flat-square&logo=NixOS&logoColor=white) -![CUDA](https://img.shields.io/badge/CUDA-supported-76B900?style=flat-square&logo=nvidia&logoColor=white) -[![Docker](https://img.shields.io/badge/Docker-ready-2496ED?style=flat-square&logo=docker&logoColor=white)](https://www.docker.com/) - - - -[Hardware](#hardware) • -[Installation](#installation) • -[Development](#development) • -[Multi Language](#multi-language-support) • -[ROS](#ros-interop) - - - -
- -# Intro - -Our goal is to provide an easy-to-install, modern framework for general robotics. You should be up and running in minutes. - - - - - - - - - - - - - - - - - - -
- Navigation - - Det -
-

Navigation and Mapping

- ros and non ros
Watch video - 		-

Perception

- bla bla perception
Watch video -
- Agents - - Sensor Integrations -
-

Agentic Control, MCP

- "hey Claude, go to the kitchen"
Watch video - 		-

Sensor Integrations

- Livox Mid360, Zed -
- - -# Hardware - - - - - - - - - - - - - - - - - -
-

Quadruped

- - 		-

Humanoid

- - 		-

Arm

- - 		-

Drone

- - 		-

Misc

- -
- 🟩 Unitree Go2 pro/air
- 		- 🟧 Unitree G1
- 		- 🟨 Xarm
- 🟨 Piper
- 		- 🟧 Mavlink
- 🟥 DJI SDK
- 		- 🟨 Force Torque Sensor
-
-
-
-🟩 stable 🟨 beta 🟧 alpha 🟥 experimental - -
- -[New Hardware Integration Guide](docs/hardware/integration_guide.md) - -# Installation - -### Step 1: System Install - -To set up your system dependencies, follow one of these guides: - -- 🟩 [NixOS / General Linux](docs/installation/nix.md) -- 🟥 [macOS](docs/installation/osx.md) -- 🟩 [Ubuntu 24.04](docs/installation/ubuntu.md) -- 🟨 [Docker](docs/installation/docker.md) - -### Step 2: Python Install - -Now install the Python package. - -Check the [hardware section](#hardware) above to choose the right `extras` and `blueprint` for your platform. - -**Use DimOS as a library / UI** - -```bash -pip install dimos[your_platform] -dimos run your_platform_blueprint -``` - -**Develop DimOS** - -```bash -git clone https://github.com/dimensionalOS/dimos/ dimos -cd dimos -uv venv -p 3.12 -source .venv/bin/activate -uv sync --all-extras -mypy dimos -pytest dimos -dimos --replay run unitree-go2 -``` - -### Step 3 - Profit - -DimOS Demo - -# Development - -## API - -- [Modules](docs/api/modules.md) -- [LCM](docs/api/lcm.md) -- [Blueprints](docs/api/blueprints.md) -- [Transports](docs/api/transports.md) -- [Data Streams](docs/api/data_streams/README.md) -- [Configuration](docs/api/configuration.md) -- [Visualization](docs/api/visualization.md) - -## Multi Language Support - -Python is our glue and prototyping language, but we support many languages via LCM interop. - -Check our language interop examples: -- [C++](examples/language-interop/cpp/) -- [Lua](examples/language-interop/lua/) -- [TypeScript](examples/language-interop/ts/) - -## ROS interop - -For researchers, we can talk to ROS directly via [ROS Transports](docs/api/transports.md), or host dockerized ROS deployments as first-class DimOS modules, allowing you easy installation and portability diff --git a/README.md b/README.md index c646f7aa7f..87b927d0f1 100644 --- a/README.md +++ b/README.md @@ -1,252 +1,192 @@ +
- banner_bordered_trimmed -

Program Atoms

-

The Agentive Operating System for Generalist Robotics

+![Dimensional](assets/dimensional-dark.svg#gh-dark-mode-only) +![Dimensional](assets/dimensional-light.svg#gh-light-mode-only) -
+

Operating System for Generalist Robotics

[![Discord](https://img.shields.io/discord/1341146487186391173?style=flat-square&logo=discord&logoColor=white&label=Discord&color=5865F2)](https://discord.gg/dimos) [![Stars](https://img.shields.io/github/stars/dimensionalOS/dimos?style=flat-square)](https://github.com/dimensionalOS/dimos/stargazers) [![Forks](https://img.shields.io/github/forks/dimensionalOS/dimos?style=flat-square)](https://github.com/dimensionalOS/dimos/fork) [![Contributors](https://img.shields.io/github/contributors/dimensionalOS/dimos?style=flat-square)](https://github.com/dimensionalOS/dimos/graphs/contributors) -
![Nix](https://img.shields.io/badge/Nix-flakes-5277C3?style=flat-square&logo=NixOS&logoColor=white) ![NixOS](https://img.shields.io/badge/NixOS-supported-5277C3?style=flat-square&logo=NixOS&logoColor=white) -![CUDA](https://img.shields.io/badge/CUDA-12.x-76B900?style=flat-square&logo=nvidia&logoColor=white) +![CUDA](https://img.shields.io/badge/CUDA-supported-76B900?style=flat-square&logo=nvidia&logoColor=white) [![Docker](https://img.shields.io/badge/Docker-ready-2496ED?style=flat-square&logo=docker&logoColor=white)](https://www.docker.com/) -

- Features • - Installation • - Documentation • - Development • - Contributing -

- -
- -> \[!NOTE] -> -> ⚠️ **Alpha Pre-Release: Expect Breaking Changes** ⚠️ - -# The Dimensional Framework - -Dimensional is the open-source, universal operating system for generalist robotics. On DimOS, developers -can design, build, and run physical ("dimensional") applications that run on any humanoid, quadruped, -drone, or wheeled embodiment. - -**Programming physical robots is now as simple as programming digital software**: Composable, Modular, Repeatable. - -Core Features: -- **Navigation:** Production navigation stack for any robot with lidar: SLAM, terrain analysis, collision - avoidance, route planning, exploration. -- **Dashboard:** The DimOS command center gives developers the tooling to debug, visualize, compose, and - test dimensional applications in real-time. Control your robot via waypoint, agent query, keyboard, - VR, more. -- **Modules:** Standalone components (equivalent to ROS nodes) that publish and subscribe to typed - In/Out streams that communicate over DimOS transports. The primary components of Dimensional. -- **Agents (experimental):** DimOS agents understand physical space, subscribe to sensor streams, and call - **physical** tools. Emergence appears when agents have physical agency. -- **MCP (experimental):** Vibecode robots by giving your AI editor (Cursor, Claude Code) MCP access to run - physical commands (move forward 1 meter, jump, etc.). -- **Manipulation (unreleased)** Classical (OMPL, IK, GraspGen), Agentive (TAMP), and VLA-native manipulation stack runs out-of-the-box on any DimOS supported arm embodiment. -- **Transport/Middleware:** DimOS native Python transport supports LCM, DDS, and SHM, plus ROS 2. -- **Robot integrations:** We integrate with the majority of hardware OEMs and are moving fast to cover - them all. Supported and/or immediate roadmap: - - | Category | Platforms | - | --- | --- | - | Quadrupeds | Unitree Go2, Unitree B1, AGIBOT D1 Max/Pro, Dobot Rover | - | Drones | DJI Mavic 2, Holybro x500 | - | Humanoids | Unitree G1, Booster K1, AGIBOT X2, ABIBOT A2 | - | Arms | OpenARMs, xARM 6/7, AgileX Piper, HighTorque Pantera | - -# Getting Started - -## Installation - -Supported/tested matrix: - -| Platform | Status | Tested | Required System deps | -| --- | --- | --- | --- | -| Linux | supported | Ubuntu 22.04, 24.04 | See below | -| macOS | experimental beta | not CI-tested | `brew install gnu-sed gcc portaudio git-lfs libjpeg-turbo python; export ARCHFLAGS="-arch $(uname -m)"` | - -Note: macOS is usable but expect inconsistent/flaky behavior (rather than hard errors/crashes). Setting `ARCHFLAGS` is likely optional, but some systems it is required to avoid a `clang` error. - -```sh -sudo apt-get update -sudo apt-get install -y curl g++ portaudio19-dev git-lfs libturbojpeg python3-dev -# install uv for python -curl -LsSf https://astral.sh/uv/install.sh | sh && export PATH="$HOME/.local/bin:$PATH" -``` - -Option 1: Install in a virtualenv - -```sh - -uv venv && . .venv/bin/activate -uv pip install 'dimos[base,unitree]' -# replay recorded data to test that the system is working -# IMPORTANT: First replay run will show a black rerun window while 2.4 GB downloads from LFS -dimos --replay run unitree-go2 -``` - -Option 2: Run without installing - -```sh -uvx --from 'dimos[base,unitree]' dimos --replay run unitree-go2 -``` - -### Test Installation - -#### Control a robot in a simulation (no robot required) - - -```sh -export DISPLAY=:1 # Or DISPLAY=:0 if getting GLFW/OpenGL X11 errors -# ignore the warp warnings -dimos --viewer-backend rerun-web --simulation run unitree-go2 -``` - -#### Control a real robot (Unitree Go2 over WebRTC) - -```sh -export ROBOT_IP= -dimos --viewer-backend rerun-web run unitree-go2 -``` - -After running dimOS open http://localhost:7779 to control robot movement. - -#### Dimensional Agents - -> \[!NOTE] -> -> **Experimental Beta: Potential unstoppable robot sentience** - -```sh -export OPENAI_API_KEY= -dimos --viewer-backend rerun-web run unitree-go2-agentic -``` - -After running that, open a new terminal and run the following to start giving instructions to the agent. -```sh -# activate the venv in this new terminal -source .venv/bin/activate - -# then tell the agent "explore the room" -# then tell it to go to something, ex: "go to the door" -humancli -``` - -# The Dimensional Library + -### Modules +[Hardware](#hardware) • +[Installation](#installation) • +[Development](#development) • +[Multi Language](#multi-language-support) • +[ROS](#ros-interop) -Modules are subsystems on a robot that operate autonomously and communicate with other subsystems using standardized messages. See below a simple robot connection module that sends streams of continuous `cmd_vel` to the robot and recieves `color_image` to a simple `Listener` module. + -```py -import threading, time, numpy as np -from dimos.core import In, Module, Out, rpc, autoconnect -from dimos.msgs.geometry_msgs import Twist -from dimos.msgs.sensor_msgs import Image, ImageFormat +
-class RobotConnection(Module): - cmd_vel: In[Twist] - color_image: Out[Image] +# Intro + +Our goal is to provide an easy-to-install, modern framework for general robotics. You should be up and running in minutes. + + + + + + + + + + + + + + + + + + +
+ Navigation + + Det +
+

Navigation and Mapping

+ ros and non ros
Watch video + 		+

Perception

+ bla bla perception
Watch video +
+ Agents + + Sensor Integrations +
+

Agentic Control, MCP

+ "hey Claude, go to the kitchen"
Watch video + 		+

Sensor Integrations

+ Livox Mid360, Zed +
+ + +# Hardware + + + + + + + + + + + + + + + + + +
+

Quadruped

+ + 		+

Humanoid

+ + 		+

Arm

+ + 		+

Drone

+ + 		+

Misc

+ +
+ 🟩 Unitree Go2 pro/air
+ 		+ 🟧 Unitree G1
+ 		+ 🟨 Xarm
+ 🟨 Piper
+ 		+ 🟧 Mavlink
+ 🟥 DJI SDK
+ 		+ 🟨 Force Torque Sensor
+
+
+
+🟩 stable 🟨 beta 🟧 alpha 🟥 experimental - @rpc - def start(self): - threading.Thread(target=self._image_loop, daemon=True).start() +
- def _image_loop(self): - while True: - img = Image.from_numpy( - np.zeros((120, 160, 3), np.uint8), - format=ImageFormat.RGB, - frame_id="camera_optical", - ) - self.color_image.publish(img) - time.sleep(0.2) +[New Hardware Integration Guide](docs/hardware/integration_guide.md) -class Listener(Module): - color_image: In[Image] +# Installation - @rpc - def start(self): - self.color_image.subscribe(lambda img: print(f"image {img.width}x{img.height}")) +### Step 1: System Install -if __name__ == "__main__": - autoconnect( - RobotConnection.blueprint(), - Listener.blueprint(), - ).build().loop() -``` +To set up your system dependencies, follow one of these guides: -### Blueprints +- 🟩 [NixOS / General Linux](docs/installation/nix.md) +- 🟥 [macOS](docs/installation/osx.md) +- 🟩 [Ubuntu 24.04](docs/installation/ubuntu.md) +- 🟨 [Docker](docs/installation/docker.md) -Blueprints are how robots are constructed on Dimensional; instructions for how to construct and wire modules. You compose them with -`autoconnect(...)`, which connects streams by `(name, type)` and returns a `Blueprint`. +### Step 2: Python Install -Blueprints can be composed, remapped, and have transports overridden if `autoconnect()` fails due to conflicting variable names or `In[]` and `Out[]` message types. +Now install the Python package. -A blueprint example that connects the image stream from a robot to an LLM Agent for reasoning and action execution. -```py -from dimos.core import autoconnect, LCMTransport -from dimos.msgs.sensor_msgs import Image -from dimos.robot.unitree.go2.connection import go2_connection -from dimos.agents.agent import agent +Check the [hardware section](#hardware) above to choose the right `extras` and `blueprint` for your platform. -blueprint = autoconnect( - go2_connection(), - agent(), -).transports({("color_image", Image): LCMTransport("/color_image", Image)}) +**Use DimOS as a library / UI** -# Run the blueprint -if __name__ == "__main__": - blueprint.build().loop() +```bash +pip install dimos[your_platform] +dimos run your_platform_blueprint ``` -# Development +**Develop DimOS** -```sh -GIT_LFS_SKIP_SMUDGE=1 git clone -b dev https://github.com/dimensionalOS/dimos.git +```bash +git clone https://github.com/dimensionalOS/dimos/ dimos cd dimos +uv venv -p 3.12 +source .venv/bin/activate +uv sync --all-extras +mypy dimos +pytest dimos +dimos --replay run unitree-go2 ``` -Then pick one of two development paths: +### Step 3 - Profit -Option A: Devcontainer -```sh -./bin/dev -``` +DimOS Demo -Option B: Editable install with uv -```sh -uv venv && . .venv/bin/activate -uv pip install -e '.[base,dev]' -``` - -For system deps, Nix setups, and testing, see `/docs/development/README.md`. +# Development -### Monitoring & Debugging +## API -DimOS comes with a number of monitoring tools: -- Run `lcmspy` to see how fast messages are being published on streams. -- Run `agentspy` to see the agent's status over time. -- If you suspect there is a bug within DimOS itself, you can enable extreme logging by prefixing the dimos command with `DIMOS_LOG_LEVEL=DEBUG RERUN_SAVE=1 `. Ex: `DIMOS_LOG_LEVEL=DEBUG RERUN_SAVE=1 dimos --replay run unitree-go2` +- [Modules](docs/api/modules.md) +- [LCM](docs/api/lcm.md) +- [Blueprints](docs/api/blueprints.md) +- [Transports](docs/api/transports.md) +- [Data Streams](docs/api/data_streams/README.md) +- [Configuration](docs/api/configuration.md) +- [Visualization](docs/api/visualization.md) +## Multi Language Support -# Documentation +Python is our glue and prototyping language, but we support many languages via LCM interop. -Concepts: -- [Modules](/docs/usage/modules.md): The building blocks of DimOS, modules run in parallel and are singleton python classes. -- [Streams](/docs/usage/sensor_streams/index.md): How modules communicate, a Pub / Sub system. -- [Blueprints](/dimos/core/README_BLUEPRINTS.md): a way to group modules together and define their connections to each other. -- [RPC](/dimos/core/README_BLUEPRINTS.md#calling-the-methods-of-other-modules): how one module can call a method on another module (arguments get serialized to JSON-like binary data). -- [Skills](/dimos/core/README_BLUEPRINTS.md#defining-skills): An RPC function, except it can be called by an AI agent (a tool for an AI). +Check our language interop examples: +- [C++](examples/language-interop/cpp/) +- [Lua](examples/language-interop/lua/) +- [TypeScript](examples/language-interop/ts/) -## Contributing +## ROS interop -We welcome contributions! See our [Bounty List](https://docs.google.com/spreadsheets/d/1tzYTPvhO7Lou21cU6avSWTQOhACl5H8trSvhtYtsk8U/edit?usp=sharing) for open requests for contributions. If you would like to suggest a feature or sponsor a bounty, open an issue. +For researchers, we can talk to ROS directly via [ROS Transports](docs/api/transports.md), or host dockerized ROS deployments as first-class DimOS modules, allowing you easy installation and portability From 182179d0ab5271e85ef8a2cc0cbc4dfaa23f3458 Mon Sep 17 00:00:00 2001 From: Ivan Nikolic Date: Sun, 15 Feb 2026 21:15:51 +0800 Subject: [PATCH 098/140] .. --- README.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/README.md b/README.md index 87b927d0f1..974b7f51ed 100644 --- a/README.md +++ b/README.md @@ -34,37 +34,37 @@ Our goal is to provide an easy-to-install, modern framework for general robotics From 3c3be83bd4c20d4fe1e3bc5267c834a11a4ddc58 Mon Sep 17 00:00:00 2001 From: Ivan Nikolic Date: Sun, 15 Feb 2026 22:17:20 +0800 Subject: [PATCH 099/140] docs: add Go2 non-ROS navigation docs, update README, pull agent docs - Add Go2 native navigation documentation with pipeline step images - Update README with shields badges, hardware table, nav links - Pull docs/agents and dimos/utils/docs from main - Add hardware integration guide placeholder - Rename sensor_streams to data_streams --- README.md | 14 +- dimos/msgs/sensor_msgs/PointCloud2.py | 4 +- dimos/utils/docs/doclinks.md | 96 ++++++ dimos/utils/docs/doclinks.py | 6 +- dimos/utils/docs/test_doclinks.py | 12 +- .../agents/docs/assets/codeblocks_example.svg | 47 +++ docs/agents/docs/assets/pikchr_basic.svg | 12 + docs/agents/docs/assets/pikchr_branch.svg | 16 + docs/agents/docs/assets/pikchr_explicit.svg | 8 + docs/agents/docs/assets/pikchr_labels.svg | 5 + docs/agents/docs/assets/pikchr_sizing.svg | 13 + docs/agents/docs/codeblocks.md | 314 ++++++++++++++++++ docs/agents/docs/doclinks.md | 21 ++ docs/agents/docs/index.md | 192 +++++++++++ .../navigation/native/assets/1-lidar.png | 3 + .../navigation/native/assets/2-globalmap.png | 3 + .../native/assets/3-globalcostmap.png | 3 + .../navigation/native/assets/4-navcostmap.png | 3 + .../navigation/native/assets/5-all.png | 3 + .../native/assets/go2nav_dataflow.svg | 19 ++ .../navigation/native/assets/noros_nav.gif | 3 + docs/capabilities/navigation/native/index.md | 153 +++++++++ docs/capabilities/navigation/readme.md | 6 +- docs/hardware/integration_guide.md | 3 + docs/{hardware => platforms}/dog/go2/index.md | 0 25 files changed, 940 insertions(+), 19 deletions(-) create mode 100644 dimos/utils/docs/doclinks.md create mode 100644 docs/agents/docs/assets/codeblocks_example.svg create mode 100644 docs/agents/docs/assets/pikchr_basic.svg create mode 100644 docs/agents/docs/assets/pikchr_branch.svg create mode 100644 docs/agents/docs/assets/pikchr_explicit.svg create mode 100644 docs/agents/docs/assets/pikchr_labels.svg create mode 100644 docs/agents/docs/assets/pikchr_sizing.svg create mode 100644 docs/agents/docs/codeblocks.md create mode 100644 docs/agents/docs/doclinks.md create mode 100644 docs/agents/docs/index.md create mode 100644 docs/capabilities/navigation/native/assets/1-lidar.png create mode 100644 docs/capabilities/navigation/native/assets/2-globalmap.png create mode 100644 docs/capabilities/navigation/native/assets/3-globalcostmap.png create mode 100644 docs/capabilities/navigation/native/assets/4-navcostmap.png create mode 100644 docs/capabilities/navigation/native/assets/5-all.png create mode 100644 docs/capabilities/navigation/native/assets/go2nav_dataflow.svg create mode 100644 docs/capabilities/navigation/native/assets/noros_nav.gif create mode 100644 docs/capabilities/navigation/native/index.md create mode 100644 docs/hardware/integration_guide.md rename docs/{hardware => platforms}/dog/go2/index.md (100%) diff --git a/README.md b/README.md index 974b7f51ed..ff520daa5f 100644 --- a/README.md +++ b/README.md @@ -71,7 +71,7 @@ Our goal is to provide an easy-to-install, modern framework for general robotics
- Navigation + Navigation - Det + Perception
-

Navigation and Mapping

+

Navigation and Mapping

ros and non ros
Watch video 		-

Perception

+

Perception

bla bla perception
Watch video
- Agents + Agents - Sensor Integrations + Sensor Integrations
-

Agentic Control, MCP

+

Agentic Control, MCP

"hey Claude, go to the kitchen"
Watch video 		-

Sensor Integrations

+

Sensor Integrations

Livox Mid360, Zed
-# Hardware +# Platforms @@ -99,18 +99,18 @@ Our goal is to provide an easy-to-install, modern framework for general robotics
- 🟩 Unitree Go2 pro/air
+ 🟩 Unitree Go2 pro/air
 - 🟧 Unitree G1
+ 🟧 Unitree G1
 - 🟨 Xarm
- 🟨 Piper
+ 🟨 Xarm
+ 🟨 Piper
 - 🟧 Mavlink
- 🟥 DJI SDK
+ 🟧 Mavlink
+ 🟥 DJI SDK
 🟨 Force Torque Sensor
diff --git a/dimos/msgs/sensor_msgs/PointCloud2.py b/dimos/msgs/sensor_msgs/PointCloud2.py index 39a0146e4c..bd89c0a0cb 100644 --- a/dimos/msgs/sensor_msgs/PointCloud2.py +++ b/dimos/msgs/sensor_msgs/PointCloud2.py @@ -609,7 +609,7 @@ def __len__(self) -> int: def to_rerun( self, voxel_size: float = 0.05, - colormap: str | None = "turbo", + colormap: str | None = None, colors: list[int] | None = None, mode: str = "boxes", size: float | None = None, @@ -636,6 +636,8 @@ def to_rerun( if len(points) == 0: return rr.Points3D([]) if mode == "points" else rr.Boxes3D(centers=[]) + if colors is None and colormap is None: + colormap = "turbo" # Default colormap if no colors provided # Determine colors point_colors = None if colormap is not None: diff --git a/dimos/utils/docs/doclinks.md b/dimos/utils/docs/doclinks.md new file mode 100644 index 0000000000..dce2e67fec --- /dev/null +++ b/dimos/utils/docs/doclinks.md @@ -0,0 +1,96 @@ +# doclinks + +A Markdown link resolver that automatically fills in correct file paths for code references in documentation. + +## What it does + +When writing docs, you can use placeholder links like: + + +```markdown +See [`service/spec.py`]() for the implementation. +``` + + +Running `doclinks` resolves these to actual paths: + + +```markdown +See [`service/spec.py`](/dimos/protocol/service/spec.py) for the implementation. +``` + + +## Features + + +- **Code file links**: `[`filename.py`]()` resolves to the file's path +- **Symbol line linking**: If another backticked term appears on the same line, it finds that symbol in the file and adds `#L`: + ```markdown + See `Configurable` in [`config.py`]() + → [`config.py`](/path/config.py#L42) + ``` +- **Doc-to-doc links**: `[Modules](.md)` resolves to `modules.md` or `modules/index.md` + +- **Multiple link modes**: absolute, relative, or GitHub URLs +- **Watch mode**: Automatically re-process on file changes +- **Ignore regions**: Skip sections with `` comments + +## Usage + +```bash +# Process a single file +doclinks docs/guide.md + +# Process a directory recursively +doclinks docs/ + +# Relative links (from doc location) +doclinks --link-mode relative docs/ + +# GitHub links +doclinks --link-mode github \ + --github-url https://github.com/org/repo docs/ + +# Dry run (preview changes) +doclinks --dry-run docs/ + +# CI check (exit 1 if changes needed) +doclinks --check docs/ + +# Watch mode (auto-update on changes) +doclinks --watch docs/ +``` + +## Options + +| Option | Description | +|--------------------|-------------------------------------------------| +| `--root PATH` | Repository root (default: auto-detect git root) | +| `--link-mode MODE` | `absolute` (default), `relative`, or `github` | +| `--github-url URL` | Base GitHub URL (required for github mode) | +| `--github-ref REF` | Branch/ref for GitHub links (default: `main`) | +| `--dry-run` | Show changes without modifying files | +| `--check` | Exit with error if changes needed (for CI) | +| `--watch` | Watch for changes and re-process | + +## Link patterns + + +| Pattern | Description | +|----------------------|------------------------------------------------| +| `[`file.py`]()` | Code file reference (empty or any link) | +| `[`path/file.py`]()` | Code file with partial path for disambiguation | +| `[`file.py`](#L42)` | Preserves existing line fragments | +| `[Doc Name](.md)` | Doc-to-doc link (resolves by name) | + + +## How resolution works + +The tool builds an index of all files in the repo. For `/dimos/protocol/service/spec.py`, it creates lookup entries for: + +- `spec.py` +- `service/spec.py` +- `protocol/service/spec.py` +- `dimos/protocol/service/spec.py` + +Use longer paths when multiple files share the same name. diff --git a/dimos/utils/docs/doclinks.py b/dimos/utils/docs/doclinks.py index c04fe7ef16..3f0af10a7b 100644 --- a/dimos/utils/docs/doclinks.py +++ b/dimos/utils/docs/doclinks.py @@ -106,8 +106,8 @@ def build_doc_index(root: Path) -> dict[str, list[Path]]: """ Build an index mapping lowercase doc names to .md file paths. - For docs/usage/modules.md, creates entry: - - "modules" -> [Path("docs/usage/modules.md")] + For docs/concepts/modules.md, creates entry: + - "modules" -> [Path("docs/concepts/modules.md")] Also indexes directory index files: - "modules" -> [Path("docs/modules/index.md")] (if modules/index.md exists) @@ -529,7 +529,7 @@ def process_file(md_path: Path, quiet: bool = False) -> tuple[bool, list[str]]: watch_paths = args.paths if args.paths else [str(root / "docs")] - class MarkdownHandler(FileSystemEventHandler): # type: ignore[misc] + class MarkdownHandler(FileSystemEventHandler): def on_modified(self, event: Any) -> None: if not event.is_directory and event.src_path.endswith(".md"): process_file(Path(event.src_path)) diff --git a/dimos/utils/docs/test_doclinks.py b/dimos/utils/docs/test_doclinks.py index f1303a2245..7313ec3676 100644 --- a/dimos/utils/docs/test_doclinks.py +++ b/dimos/utils/docs/test_doclinks.py @@ -256,7 +256,7 @@ def test_github_mode(self, file_index): def test_relative_mode(self, file_index): """Should generate relative paths in relative mode.""" content = "See [`service/spec.py`]()" - doc_path = REPO_ROOT / "docs/usage/test.md" + doc_path = REPO_ROOT / "docs/concepts/test.md" new_content, _changes, _errors = process_markdown( content, @@ -277,7 +277,7 @@ def test_indexes_by_stem(self, doc_index): """Should index docs by lowercase stem.""" assert "configuration" in doc_index assert "modules" in doc_index - assert "blueprints" in doc_index + assert "development" in doc_index def test_case_insensitive(self, doc_index): """Should use lowercase keys.""" @@ -349,8 +349,8 @@ def test_doc_link_github_mode(self, file_index, doc_index): def test_doc_link_relative_mode(self, file_index, doc_index): """Should generate relative paths for doc links.""" - content = "See [Blueprints](.md)" - doc_path = REPO_ROOT / "docs/usage/test.md" + content = "See [Development](.md)" + doc_path = REPO_ROOT / "docs/concepts/test.md" new_content, _changes, errors = process_markdown( content, @@ -364,8 +364,8 @@ def test_doc_link_relative_mode(self, file_index, doc_index): ) assert len(errors) == 0 - # Should be relative path from docs/usage/ to target doc - assert "[Blueprints](blueprints.md)" in new_content + # Should be relative path from docs/concepts/ to docs/ + assert "../" in new_content def test_doc_not_found_error(self, file_index, doc_index): """Should error when doc doesn't exist.""" diff --git a/docs/agents/docs/assets/codeblocks_example.svg b/docs/agents/docs/assets/codeblocks_example.svg new file mode 100644 index 0000000000..3ba6c37a4b --- /dev/null +++ b/docs/agents/docs/assets/codeblocks_example.svg @@ -0,0 +1,47 @@ + + + + + + + + +A + +A + + + +B + +B + + + +A->B + + + + + +C + +C + + + +A->C + + + + + +B->C + + + + + diff --git a/docs/agents/docs/assets/pikchr_basic.svg b/docs/agents/docs/assets/pikchr_basic.svg new file mode 100644 index 0000000000..5410d35577 --- /dev/null +++ b/docs/agents/docs/assets/pikchr_basic.svg @@ -0,0 +1,12 @@ + + +Step 1 + + + +Step 2 + + + +Step 3 + diff --git a/docs/agents/docs/assets/pikchr_branch.svg b/docs/agents/docs/assets/pikchr_branch.svg new file mode 100644 index 0000000000..e7b2b86596 --- /dev/null +++ b/docs/agents/docs/assets/pikchr_branch.svg @@ -0,0 +1,16 @@ + + +Input + + + +Process + + + +Path A + + + +Path B + diff --git a/docs/agents/docs/assets/pikchr_explicit.svg b/docs/agents/docs/assets/pikchr_explicit.svg new file mode 100644 index 0000000000..a6a913fcb4 --- /dev/null +++ b/docs/agents/docs/assets/pikchr_explicit.svg @@ -0,0 +1,8 @@ + + +Step 1 + + + +Step 2 + diff --git a/docs/agents/docs/assets/pikchr_labels.svg b/docs/agents/docs/assets/pikchr_labels.svg new file mode 100644 index 0000000000..b11fe64bca --- /dev/null +++ b/docs/agents/docs/assets/pikchr_labels.svg @@ -0,0 +1,5 @@ + + +Box +label below + diff --git a/docs/agents/docs/assets/pikchr_sizing.svg b/docs/agents/docs/assets/pikchr_sizing.svg new file mode 100644 index 0000000000..3a0c433cb1 --- /dev/null +++ b/docs/agents/docs/assets/pikchr_sizing.svg @@ -0,0 +1,13 @@ + + +short + + + +.subscribe() + + + +two lines +of text + diff --git a/docs/agents/docs/codeblocks.md b/docs/agents/docs/codeblocks.md new file mode 100644 index 0000000000..323f1c0c50 --- /dev/null +++ b/docs/agents/docs/codeblocks.md @@ -0,0 +1,314 @@ +# Executable Code Blocks + +We use [md-babel-py](https://github.com/leshy/md-babel-py/) to execute code blocks in markdown and insert results. + +## Golden Rule + +**All code blocks must be executable.** Never write illustrative/pseudo code blocks. If you're showing an API usage pattern, create a minimal working example that actually runs. This ensures documentation stays correct as the codebase evolves. + +## Running + +```sh skip +md-babel-py run document.md # edit in-place +md-babel-py run document.md --stdout # preview to stdout +md-babel-py run document.md --dry-run # show what would run +``` + +## Supported Languages + +Python, Shell (sh), Node.js, plus visualization: Matplotlib, Graphviz, Pikchr, Asymptote, OpenSCAD, Diagon. + +## Code Block Flags + +Add flags after the language identifier: + +| Flag | Effect | +|------|--------| +| `session=NAME` | Share state between blocks with same session name | +| `output=path.png` | Write output to file instead of inline | +| `no-result` | Execute but don't insert result | +| `skip` | Don't execute this block | +| `expected-error` | Block is expected to fail | + +## Examples + +# md-babel-py + +Execute code blocks in markdown files and insert the results. + +![Demo](assets/screencast.gif) + +**Use cases:** +- Keep documentation examples up-to-date automatically +- Validate code snippets in docs actually work +- Generate diagrams and charts from code in markdown +- Literate programming with executable documentation + +## Languages + +### Shell + +```sh +echo "cwd: $(pwd)" +``` + + +``` +cwd: /work +``` + +### Python + +```python session=example +a = "hello world" +print(a) +``` + + +``` +hello world +``` + +Sessions preserve state between code blocks: + +```python session=example +print(a, "again") +``` + + +``` +hello world again +``` + +### Node.js + +```node +console.log("Hello from Node.js"); +console.log(`Node version: ${process.version}`); +``` + + +``` +Hello from Node.js +Node version: v22.21.1 +``` + +### Matplotlib + +```python output=assets/matplotlib-demo.svg +import matplotlib.pyplot as plt +import numpy as np +plt.style.use('dark_background') +x = np.linspace(0, 4 * np.pi, 200) +plt.figure(figsize=(8, 4)) +plt.plot(x, np.sin(x), label='sin(x)', linewidth=2) +plt.plot(x, np.cos(x), label='cos(x)', linewidth=2) +plt.xlabel('x') +plt.ylabel('y') +plt.legend() +plt.grid(alpha=0.3) +plt.savefig('{output}', transparent=True) +``` + + +![output](assets/matplotlib-demo.svg) + +### Pikchr + +SQLite's diagram language: + +
+diagram source + +```pikchr fold output=assets/pikchr-demo.svg +color = white +fill = none +linewid = 0.4in + +# Input file +In: file "README.md" fit +arrow + +# Processing +Parse: box "Parse" rad 5px fit +arrow +Exec: box "Execute" rad 5px fit + +# Fan out to languages +arrow from Exec.e right 0.3in then up 0.4in then right 0.3in +Sh: oval "Shell" fit +arrow from Exec.e right 0.3in then right 0.3in +Node: oval "Node" fit +arrow from Exec.e right 0.3in then down 0.4in then right 0.3in +Py: oval "Python" fit + +# Merge back +X: dot at (Py.e.x + 0.3in, Node.e.y) invisible +line from Sh.e right until even with X then down to X +line from Node.e to X +line from Py.e right until even with X then up to X +Out: file "README.md" fit with .w at (X.x + 0.3in, X.y) +arrow from X to Out.w +``` + +
+ + +![output](assets/pikchr-demo.svg) + +### Asymptote + +Vector graphics: + +```asymptote output=assets/histogram.svg +import graph; +import stats; + +size(400,200,IgnoreAspect); +defaultpen(white); + +int n=10000; +real[] a=new real[n]; +for(int i=0; i < n; ++i) a[i]=Gaussrand(); + +draw(graph(Gaussian,min(a),max(a)),orange); + +int N=bins(a); + +histogram(a,min(a),max(a),N,normalize=true,low=0,rgb(0.4,0.6,0.8),rgb(0.2,0.4,0.6),bars=true); + +xaxis("$x$",BottomTop,LeftTicks,p=white); +yaxis("$dP/dx$",LeftRight,RightTicks(trailingzero),p=white); +``` + + +![output](assets/histogram.svg) + +### Graphviz + +```dot output=assets/graph.svg +A -> B -> C +A -> C +``` + + +![output](assets/graph.svg) + +### OpenSCAD + +```openscad output=assets/cube-sphere.png +cube([10, 10, 10]); +sphere(r=7); +``` + + +![output](assets/cube-sphere.png) + +### Diagon + +ASCII art diagrams: + +```diagon mode=Math +1 + 1/2 + sum(i,0,10) +``` + + +``` + 10 + ___ + 1 ╲ +1 + ─ + ╱ i + 2 ‾‾‾ + 0 +``` + +```diagon mode=GraphDAG +A -> B -> C +A -> C +``` + + +``` +┌───┐ +│A │ +└┬─┬┘ + │┌▽┐ + ││B│ + │└┬┘ +┌▽─▽┐ +│C │ +└───┘ +``` + +## Install + +### Nix (recommended) + +```sh skip +# Run directly from GitHub +nix run github:leshy/md-babel-py -- run README.md --stdout + +# Or clone and run locally +nix run . -- run README.md --stdout +``` + +### Docker + +```sh skip +# Pull from Docker Hub +docker run -v $(pwd):/work lesh/md-babel-py:main run /work/README.md --stdout + +# Or build locally via Nix +nix build .#docker # builds tarball to ./result +docker load < result # loads image from tarball +docker run -v $(pwd):/work md-babel-py:latest run /work/file.md --stdout +``` + +### pipx + +```sh skip +pipx install md-babel-py +# or: uv pip install md-babel-py +md-babel-py run README.md --stdout +``` + +If not using nix or docker, evaluators require system dependencies: + +| Language | System packages | +|-----------|-----------------------------| +| python | python3 | +| node | nodejs | +| dot | graphviz | +| asymptote | asymptote, texlive, dvisvgm | +| pikchr | pikchr | +| openscad | openscad, xvfb, imagemagick | +| diagon | diagon | + +```sh skip +# Arch Linux +sudo pacman -S python nodejs graphviz asymptote texlive-basic openscad xorg-server-xvfb imagemagick + +# Debian/Ubuntu +sudo apt-get install python3 nodejs graphviz asymptote texlive xvfb imagemagick openscad +``` + +Note: pikchr and diagon may need to be built from source. Use Docker or Nix for full evaluator support. + +## Usage + +```sh skip +# Edit file in-place +md-babel-py run document.md + +# Output to separate file +md-babel-py run document.md --output result.md + +# Print to stdout +md-babel-py run document.md --stdout + +# Only run specific languages +md-babel-py run document.md --lang python,sh + +# Dry run - show what would execute +md-babel-py run document.md --dry-run +``` diff --git a/docs/agents/docs/doclinks.md b/docs/agents/docs/doclinks.md new file mode 100644 index 0000000000..d5533c5983 --- /dev/null +++ b/docs/agents/docs/doclinks.md @@ -0,0 +1,21 @@ +When writing or editing markdown documentation, use `doclinks` tool to resolve file references. + +Full documentation if needed: [`utils/docs/doclinks.md`](/dimos/utils/docs/doclinks.md) + +## Syntax + + +| Pattern | Example | +|-------------|-----------------------------------------------------| +| Code file | `[`service/spec.py`]()` → resolves path | +| With symbol | `Configurable` in `[`spec.py`]()` → adds `#L` | +| Doc link | `[Configuration](.md)` → resolves to doc | + + +## Usage + +```bash +doclinks docs/guide.md # single file +doclinks docs/ # directory +doclinks --dry-run ... # preview only +``` diff --git a/docs/agents/docs/index.md b/docs/agents/docs/index.md new file mode 100644 index 0000000000..bec2ce79e6 --- /dev/null +++ b/docs/agents/docs/index.md @@ -0,0 +1,192 @@ + +# Code Blocks + +**All code blocks must be executable.** +Never write illustrative/pseudo code blocks. +If you're showing an API usage pattern, create a minimal working example that actually runs. This ensures documentation stays correct as the codebase evolves. + +After writing a code block in your markdown file, you can run it by executing +`md-babel-py run document.md` + +more information on this tool is in [codeblocks](/docs/agents/docs_agent/codeblocks.md) + + +# Code or Docs Links + +After adding a link to a doc run + +`doclinks document.md` + +### Code file references +```markdown +See [`service/spec.py`](/dimos/protocol/service/spec.py) for the implementation. +``` + +After running doclinks, becomes: +```markdown +See [`service/spec.py`](/dimos/protocol/service/spec.py) for the implementation. +``` + +### Symbol auto-linking +Mention a symbol on the same line to auto-link to its line number: +```markdown +The `Configurable` class is defined in [`service/spec.py`](/dimos/protocol/service/spec.py#L22). +``` + +Becomes: +```markdown +The `Configurable` class is defined in [`service/spec.py`](/dimos/protocol/service/spec.py#L22). +``` +### Doc-to-doc references +Use `.md` as the link target: +```markdown +See [Configuration](/docs/api/configuration.md) for more details. +``` + +Becomes: +```markdown +See [Configuration](/docs/concepts/configuration.md) for more details. +``` + +More information on this in [doclinks](/docs/agents/docs_agent/doclinks.md) + + +# Pikchr + +[Pikchr](https://pikchr.org/) is a diagram language from SQLite. Use it for flowcharts and architecture diagrams. + +**Important:** Always wrap pikchr blocks in `
` tags so the source is collapsed by default on GitHub. The rendered SVG stays visible outside the fold. Code blocks (Python, etc.) should NOT be folded—they're meant to be read. + +## Basic syntax + +
+diagram source + +```pikchr fold output=assets/pikchr_basic.svg +color = white +fill = none + +A: box "Step 1" rad 5px fit wid 170% ht 170% +arrow right 0.3in +B: box "Step 2" rad 5px fit wid 170% ht 170% +arrow right 0.3in +C: box "Step 3" rad 5px fit wid 170% ht 170% +``` + +
+ + +![output](assets/pikchr_basic.svg) + +## Box sizing + +Use `fit` with percentage scaling to auto-size boxes with padding: + +
+diagram source + +```pikchr fold output=assets/pikchr_sizing.svg +color = white +fill = none + +# fit wid 170% ht 170% = auto-size + padding +A: box "short" rad 5px fit wid 170% ht 170% +arrow right 0.3in +B: box ".subscribe()" rad 5px fit wid 170% ht 170% +arrow right 0.3in +C: box "two lines" "of text" rad 5px fit wid 170% ht 170% +``` + +
+ + +![output](assets/pikchr_sizing.svg) + +The pattern `fit wid 170% ht 170%` means: auto-size to text, then scale width by 170% and height by 170%. + +For explicit sizing (when you need consistent box sizes): + +
+diagram source + +```pikchr fold output=assets/pikchr_explicit.svg +color = white +fill = none + +A: box "Step 1" rad 5px fit wid 170% ht 170% +arrow right 0.3in +B: box "Step 2" rad 5px fit wid 170% ht 170% +``` + +
+ + +![output](assets/pikchr_explicit.svg) + +## Common settings + +Always start with: + +``` +color = white # text color +fill = none # transparent box fill +``` + +## Branching paths + +
+diagram source + +```pikchr fold output=assets/pikchr_branch.svg +color = white +fill = none + +A: box "Input" rad 5px fit wid 170% ht 170% +arrow +B: box "Process" rad 5px fit wid 170% ht 170% + +# Branch up +arrow from B.e right 0.3in then up 0.35in then right 0.3in +C: box "Path A" rad 5px fit wid 170% ht 170% + +# Branch down +arrow from B.e right 0.3in then down 0.35in then right 0.3in +D: box "Path B" rad 5px fit wid 170% ht 170% +``` + +
+ + +![output](assets/pikchr_branch.svg) + +**Tip:** For tree/hierarchy diagrams, prefer left-to-right layout (root on left, children branching right). This reads more naturally and avoids awkward vertical stacking. + +## Adding labels + +
+diagram source + +```pikchr fold output=assets/pikchr_labels.svg +color = white +fill = none + +A: box "Box" rad 5px fit wid 170% ht 170% +text "label below" at (A.x, A.y - 0.4in) +``` + +
+ + +![output](assets/pikchr_labels.svg) + +## Reference + +| Element | Syntax | +|---------|--------| +| Box | `box "text" rad 5px wid Xin ht Yin` | +| Arrow | `arrow right 0.3in` | +| Oval | `oval "text" wid Xin ht Yin` | +| Text | `text "label" at (X, Y)` | +| Named point | `A: box ...` then reference `A.e`, `A.n`, `A.x`, `A.y` | + +See [pikchr.org/home/doc/trunk/doc/userman.md](https://pikchr.org/home/doc/trunk/doc/userman.md) for full documentation. diff --git a/docs/capabilities/navigation/native/assets/1-lidar.png b/docs/capabilities/navigation/native/assets/1-lidar.png new file mode 100644 index 0000000000..6584ee90cb --- /dev/null +++ b/docs/capabilities/navigation/native/assets/1-lidar.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:2d76742ada18d20dc0e3a3be04159d3412e7df6acee8596ff37916f0f269d3e0 +size 597386 diff --git a/docs/capabilities/navigation/native/assets/2-globalmap.png b/docs/capabilities/navigation/native/assets/2-globalmap.png new file mode 100644 index 0000000000..55541a8fcb --- /dev/null +++ b/docs/capabilities/navigation/native/assets/2-globalmap.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:bc2f27ec2dcc4048acde6b53229c7596b3a7f6ed6afad30c4cd062cf5751bd24 +size 1104485 diff --git a/docs/capabilities/navigation/native/assets/3-globalcostmap.png b/docs/capabilities/navigation/native/assets/3-globalcostmap.png new file mode 100644 index 0000000000..907d0b0448 --- /dev/null +++ b/docs/capabilities/navigation/native/assets/3-globalcostmap.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:d1f9e6c142b220f1a4be7b08950f628a2d34e26caba8a1f5c100726bec6c88ef +size 793366 diff --git a/docs/capabilities/navigation/native/assets/4-navcostmap.png b/docs/capabilities/navigation/native/assets/4-navcostmap.png new file mode 100644 index 0000000000..6c40bce0e0 --- /dev/null +++ b/docs/capabilities/navigation/native/assets/4-navcostmap.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:9ee4332e3d92162ddf41a0137c2ab5b6a885d758aa5a27037e413cdd4d946436 +size 741912 diff --git a/docs/capabilities/navigation/native/assets/5-all.png b/docs/capabilities/navigation/native/assets/5-all.png new file mode 100644 index 0000000000..655be72c1c --- /dev/null +++ b/docs/capabilities/navigation/native/assets/5-all.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:1a777d315beac6f4773adcb5c27384fd983720083941b4f62060958ddf6c16d2 +size 1209867 diff --git a/docs/capabilities/navigation/native/assets/go2nav_dataflow.svg b/docs/capabilities/navigation/native/assets/go2nav_dataflow.svg new file mode 100644 index 0000000000..fa352c68b9 --- /dev/null +++ b/docs/capabilities/navigation/native/assets/go2nav_dataflow.svg @@ -0,0 +1,19 @@ + + +Go2 + + +PointCloud2 + +VoxelGridMapper + + +PointCloud2 + +CostMapper + + +OccupancyGrid + +Navigation + diff --git a/docs/capabilities/navigation/native/assets/noros_nav.gif b/docs/capabilities/navigation/native/assets/noros_nav.gif new file mode 100644 index 0000000000..ab47bb9cb5 --- /dev/null +++ b/docs/capabilities/navigation/native/assets/noros_nav.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:60f842cd2fda539338443b3c501197fbb875f5c5f3883ba3ffdd17005e9bd786 +size 612786 diff --git a/docs/capabilities/navigation/native/index.md b/docs/capabilities/navigation/native/index.md new file mode 100644 index 0000000000..1dc3222d93 --- /dev/null +++ b/docs/capabilities/navigation/native/index.md @@ -0,0 +1,153 @@ +# Go2 Non-ROS Navigation + + + +The Go2 navigation stack runs entirely without ROS. It uses a **column-carving voxel map** strategy: each new LiDAR frame replaces the corresponding region of the global map entirely, ensuring the map always reflects the latest observations. + +## Data Flow + +
+diagram source + +
Pikchr + +```pikchr fold output=assets/go2nav_dataflow.svg +color = white +fill = none + +Go2: box "Go2" rad 5px fit wid 170% ht 170% +arrow right 0.5in "PointCloud2" above italic +Vox: box "VoxelGridMapper" rad 5px fit wid 170% ht 170% +arrow right 0.5in "PointCloud2" above italic +Cost: box "CostMapper" rad 5px fit wid 170% ht 170% +arrow right 0.5in "OccupancyGrid" above italic +Nav: box "Navigation" rad 5px fit wid 170% ht 170% +``` + +
+ + +![output](assets/go2nav_dataflow.svg) + +
+ +## Pipeline Steps + +### 1. LiDAR Frame — `GO2Connection` + +The Livox Mid-360 LiDAR on the Go2 produces a raw 3D point cloud each frame. Points are color-coded by height — blue is ground level, red/orange are walls and obstacles. + +![LiDAR frame](assets/1-lidar.png) + +### 2. Global Voxel Map — `VoxelGridMapper` + +Each incoming frame is quantized into 3D voxels and spliced into the global map via column carving. The map grows as the robot explores, with previously visited areas updated in-place whenever the robot returns. + +![Global map](assets/2-globalmap.png) + +### 3. Global Costmap — `CostMapper` + +The 3D voxel map is projected down to a 2D occupancy grid. Terrain slope is analyzed via Sobel gradients — flat areas (light) are traversable, steep height changes (dark) are obstacles. + +![Global costmap](assets/3-globalcostmap.png) + +### 4. Navigation Costmap — `ReplanningAStarPlanner` + +The planner overlays cost gradients and computes a path (green line) from the robot's position to the goal. The purple/magenta heatmap shows the inflated obstacle costs used for path planning. + +![Navigation costmap with path](assets/4-navcostmap.png) + +### 5. All Layers Combined + +All visualization layers shown together — 3D voxel map, 2D costmap, and the planned path overlaid in a single view. + +![All layers](assets/5-all.png) + +--- + +## Voxel Mapping & Column Carving + +The [`VoxelGridMapper`](/dimos/mapping/voxels.py) maintains a sparse 3D occupancy grid using Open3D's `VoxelBlockGrid` backed by a hash map. Each voxel is a 5cm cube by default. + +### How frames are added + +1. Incoming points are quantized to voxel coordinates: `vox = floor(point / voxel_size)` +2. The (X, Y) footprint of the new frame is extracted +3. **All existing voxels** sharing those (X, Y) coordinates are erased — the entire Z-column is removed +4. New voxels are inserted + +```python skip +# Column carving: erase all existing voxels sharing (X,Y) with new data +xy_keys = new_keys[:, :2] # extract (X,Y) footprint +xy_hashmap.insert(xy_keys, ...) # build lookup +_, found_mask = xy_hashmap.find(existing_xy) # find overlapping columns +self._voxel_hashmap.erase(existing[found_mask]) # erase old +self._voxel_hashmap.activate(new_keys) # insert new +``` + +### Why column carving? + +The robot's LiDAR sees a cone of space from its current position. Within that cone, any previously mapped voxels are now stale — the sensor has a fresh observation. By erasing entire Z-columns in the footprint, we guarantee: + +- No ghost obstacles from previous passes +- Dynamic objects (people, doors) get cleared automatically +- The latest observation always wins + +The hash map provides O(1) insert/erase/lookup, so this is efficient even with millions of voxels. The grid runs on **CUDA** by default for speed, with CPU fallback. + +## Cost Mapping + +The [`CostMapper`](/dimos/mapping/costmapper.py) converts the 3D voxel map into a 2D navigation grid. The default algorithm (`height_cost`) works as follows: + +1. **Height maps**: For each (X, Y) cell, find min and max Z across all voxels +2. **Pass-under detection**: If the vertical gap exceeds `can_pass_under` (default 0.6m), the robot can fit underneath — use ground height instead of obstacle height +3. **Slope analysis**: Apply Sobel filter to the height map to compute terrain gradient +4. **Cost assignment**: `cost = (gradient × resolution / can_climb) × 100`, clamped to [0, 100] + +| Cost | Meaning | +|------|---------| +| 0 | Flat, easy to traverse | +| 50 | Moderate slope (~7.5cm rise per cell) | +| 100 | Steep or impassable (≥15cm rise per cell) | +| -1 | Unknown (no observations) | + +## Blueprint Composition + +The navigation stack is composed in the [`unitree_go2`](/dimos/robot/unitree/go2/blueprints/__init__.py) blueprint: + +```python skip +unitree_go2 = autoconnect( + unitree_go2_basic, # robot connection + visualization + voxel_mapper(voxel_size=0.1), # 3D voxel mapping + cost_mapper(), # 2D costmap generation + replanning_a_star_planner(), # path planning + wavefront_frontier_explorer(), # exploration +).global_config(n_dask_workers=6, robot_model="unitree_go2") +``` + +Modules are auto-wired by matching stream names and types: +- `GO2Connection.pointcloud` → `VoxelGridMapper.lidar` (both `PointCloud2`) +- `VoxelGridMapper.global_map` → `CostMapper.global_map` (both `PointCloud2`) +- `CostMapper.global_costmap` → planner and explorer (both `OccupancyGrid`) + +## Configuration + +### Voxel Mapper + +| Parameter | Default | Description | +|-----------|---------|-------------| +| `voxel_size` | 0.05 | Voxel cube size in meters | +| `block_count` | 2,000,000 | Max voxels in hash map | +| `device` | `CUDA:0` | Compute device (`CUDA:0` or `CPU:0`) | +| `carve_columns` | `true` | Enable column carving (disable for append-only mapping) | +| `publish_interval` | 0 | Seconds between map publishes (0 = every frame) | + +### Cost Mapper (height_cost) + +| Parameter | Default | Description | +|-----------|---------|-------------| +| `resolution` | 0.05 | 2D grid cell size in meters | +| `can_pass_under` | 0.6 | Min gap height the robot can fit through (m) | +| `can_climb` | 0.15 | Height change that maps to cost 100 (m) | +| `ignore_noise` | 0.05 | Height changes below this are zeroed (m) | +| `smoothing` | 1.0 | Gaussian sigma for height map smoothing | diff --git a/docs/capabilities/navigation/readme.md b/docs/capabilities/navigation/readme.md index 0c6ff9efdd..af26c07f94 100644 --- a/docs/capabilities/navigation/readme.md +++ b/docs/capabilities/navigation/readme.md @@ -1,8 +1,10 @@ # Navigation -## Non ROS - +## Non-ROS +- [Go2 Navigation](native/index.md) — column-carving voxel mapping + slope-based costmap ## ROS + +See [ROS Transports](/docs/api/transports.md) for bridging DimOS streams to ROS topics. diff --git a/docs/hardware/integration_guide.md b/docs/hardware/integration_guide.md new file mode 100644 index 0000000000..805e6ad418 --- /dev/null +++ b/docs/hardware/integration_guide.md @@ -0,0 +1,3 @@ +# New Hardware Integration Guide + +TODO: Document how to add support for new hardware platforms. diff --git a/docs/hardware/dog/go2/index.md b/docs/platforms/dog/go2/index.md similarity index 100% rename from docs/hardware/dog/go2/index.md rename to docs/platforms/dog/go2/index.md From 12abb4176b3fbb53773acd66e894df20eaad383f Mon Sep 17 00:00:00 2001 From: Ivan Nikolic Date: Sun, 15 Feb 2026 22:42:32 +0800 Subject: [PATCH 100/140] ... --- docs/capabilities/navigation/native/index.md | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/docs/capabilities/navigation/native/index.md b/docs/capabilities/navigation/native/index.md index 1dc3222d93..1e45f85132 100644 --- a/docs/capabilities/navigation/native/index.md +++ b/docs/capabilities/navigation/native/index.md @@ -35,25 +35,27 @@ Nav: box "Navigation" rad 5px fit wid 170% ht 170% ### 1. LiDAR Frame — `GO2Connection` -The Livox Mid-360 LiDAR on the Go2 produces a raw 3D point cloud each frame. Points are color-coded by height — blue is ground level, red/orange are walls and obstacles. +We don't connect to the LiDAR directly — instead we use Unitree's WebRTC client (via [legion's webrtc driver](https://github.com/legion1581/unitree_webrtc_connect)), which streams a heavily preprocessed 5cm voxel grid rather than raw point cloud data. This allows us to support stock, unjailbroken Go2 Air and Pro models out of the box. ![LiDAR frame](assets/1-lidar.png) ### 2. Global Voxel Map — `VoxelGridMapper` -Each incoming frame is quantized into 3D voxels and spliced into the global map via column carving. The map grows as the robot explores, with previously visited areas updated in-place whenever the robot returns. +Each incoming frame is spliced into the global map via column carving. The map grows as the robot explores, with previously visited areas updated in-place whenever the robot returns. We don't have proper loop closure and stable odometry, we trust the data go2 reports, which is surprisingly stable but does drift eventually. ![Global map](assets/2-globalmap.png) ### 3. Global Costmap — `CostMapper` -The 3D voxel map is projected down to a 2D occupancy grid. Terrain slope is analyzed via Sobel gradients — flat areas (light) are traversable, steep height changes (dark) are obstacles. +The 3D voxel map is projected down to a 2D occupancy grid. We map the slope of terrain in order to conclude traversability — flat areas (light) are traversable, steep height changes (dark) are obstacles. ![Global costmap](assets/3-globalcostmap.png) ### 4. Navigation Costmap — `ReplanningAStarPlanner` -The planner overlays cost gradients and computes a path (green line) from the robot's position to the goal. The purple/magenta heatmap shows the inflated obstacle costs used for path planning. +The planner will process the terrain gradient and compute it's own algo-relevant costmap, prioritizing safe free paths, while be willing to path aggressively through tight spaces if it has to + +We run the planner in a constant loop so it will dynamically react to obstacles encountered. ![Navigation costmap with path](assets/4-navcostmap.png) From df3aeccc8eabc305f1ed220425c4d7bda370977a Mon Sep 17 00:00:00 2001 From: Ivan Nikolic Date: Sun, 15 Feb 2026 22:46:07 +0800 Subject: [PATCH 101/140] fix graph --- docs/capabilities/navigation/native/index.md | 52 ++++++++------------ 1 file changed, 21 insertions(+), 31 deletions(-) diff --git a/docs/capabilities/navigation/native/index.md b/docs/capabilities/navigation/native/index.md index 1e45f85132..fd869e5754 100644 --- a/docs/capabilities/navigation/native/index.md +++ b/docs/capabilities/navigation/native/index.md @@ -9,8 +9,6 @@ The Go2 navigation stack runs entirely without ROS. It uses a **column-carving v
diagram source -
Pikchr - ```pikchr fold output=assets/go2nav_dataflow.svg color = white fill = none @@ -29,8 +27,6 @@ Nav: box "Navigation" rad 5px fit wid 170% ht 170% ![output](assets/go2nav_dataflow.svg) -
- ## Pipeline Steps ### 1. LiDAR Frame — `GO2Connection` @@ -47,7 +43,19 @@ Each incoming frame is spliced into the global map via column carving. The map g ### 3. Global Costmap — `CostMapper` -The 3D voxel map is projected down to a 2D occupancy grid. We map the slope of terrain in order to conclude traversability — flat areas (light) are traversable, steep height changes (dark) are obstacles. +The [`CostMapper`](/dimos/mapping/costmapper.py) converts the 3D voxel map into a 2D occupancy grid. The default algorithm (`height_cost`) works as follows: + +1. **Height maps**: For each (X, Y) cell, find min and max Z across all voxels +2. **Pass-under detection**: If the vertical gap exceeds `can_pass_under` (default 0.6m), the robot can fit underneath — use ground height instead of obstacle height +3. **Slope analysis**: Apply Sobel filter to the height map to compute terrain gradient +4. **Cost assignment**: `cost = (gradient × resolution / can_climb) × 100`, clamped to [0, 100] + +| Cost | Meaning | +|------|---------| +| 0 | Flat, easy to traverse | +| 50 | Moderate slope (~7.5cm rise per cell) | +| 100 | Steep or impassable (≥15cm rise per cell) | +| -1 | Unknown (no observations) | ![Global costmap](assets/3-globalcostmap.png) @@ -71,6 +79,14 @@ All visualization layers shown together — 3D voxel map, 2D costmap, and the pl The [`VoxelGridMapper`](/dimos/mapping/voxels.py) maintains a sparse 3D occupancy grid using Open3D's `VoxelBlockGrid` backed by a hash map. Each voxel is a 5cm cube by default. +The robot's LiDAR sees a cone of space from its current position. Within that cone, any previously mapped voxels are now stale — the sensor has a fresh observation. By erasing entire Z-columns in the footprint, we guarantee: + +- No ghost obstacles from previous passes +- Dynamic objects (people, doors) get cleared automatically +- The latest observation always wins + +The hash map provides O(1) insert/erase/lookup, so this is efficient even with millions of voxels. The grid runs on **CUDA** by default for speed, with CPU fallback. + ### How frames are added 1. Incoming points are quantized to voxel coordinates: `vox = floor(point / voxel_size)` @@ -87,32 +103,6 @@ self._voxel_hashmap.erase(existing[found_mask]) # erase old self._voxel_hashmap.activate(new_keys) # insert new ``` -### Why column carving? - -The robot's LiDAR sees a cone of space from its current position. Within that cone, any previously mapped voxels are now stale — the sensor has a fresh observation. By erasing entire Z-columns in the footprint, we guarantee: - -- No ghost obstacles from previous passes -- Dynamic objects (people, doors) get cleared automatically -- The latest observation always wins - -The hash map provides O(1) insert/erase/lookup, so this is efficient even with millions of voxels. The grid runs on **CUDA** by default for speed, with CPU fallback. - -## Cost Mapping - -The [`CostMapper`](/dimos/mapping/costmapper.py) converts the 3D voxel map into a 2D navigation grid. The default algorithm (`height_cost`) works as follows: - -1. **Height maps**: For each (X, Y) cell, find min and max Z across all voxels -2. **Pass-under detection**: If the vertical gap exceeds `can_pass_under` (default 0.6m), the robot can fit underneath — use ground height instead of obstacle height -3. **Slope analysis**: Apply Sobel filter to the height map to compute terrain gradient -4. **Cost assignment**: `cost = (gradient × resolution / can_climb) × 100`, clamped to [0, 100] - -| Cost | Meaning | -|------|---------| -| 0 | Flat, easy to traverse | -| 50 | Moderate slope (~7.5cm rise per cell) | -| 100 | Steep or impassable (≥15cm rise per cell) | -| -1 | Unknown (no observations) | - ## Blueprint Composition The navigation stack is composed in the [`unitree_go2`](/dimos/robot/unitree/go2/blueprints/__init__.py) blueprint: From 702eb6835c177e01e43c01a0c4ce7538a08fe8e8 Mon Sep 17 00:00:00 2001 From: Ivan Nikolic Date: Sun, 15 Feb 2026 23:06:36 +0800 Subject: [PATCH 102/140] native nav docs wrap --- docs/capabilities/navigation/native/index.md | 115 +++++++------------ 1 file changed, 44 insertions(+), 71 deletions(-) diff --git a/docs/capabilities/navigation/native/index.md b/docs/capabilities/navigation/native/index.md index fd869e5754..b4d6892f6a 100644 --- a/docs/capabilities/navigation/native/index.md +++ b/docs/capabilities/navigation/native/index.md @@ -37,25 +37,55 @@ We don't connect to the LiDAR directly — instead we use Unitree's WebRTC clien ### 2. Global Voxel Map — `VoxelGridMapper` -Each incoming frame is spliced into the global map via column carving. The map grows as the robot explores, with previously visited areas updated in-place whenever the robot returns. We don't have proper loop closure and stable odometry, we trust the data go2 reports, which is surprisingly stable but does drift eventually. +The [`VoxelGridMapper`](/dimos/mapping/voxels.py) maintains a sparse 3D occupancy grid using Open3D's `VoxelBlockGrid` backed by a hash map. Each voxel is a 5cm cube by default. + +Each incoming LiDAR frame is spliced into the global map via column carving. We consider any previously mapped voxels in the space of a received LiDAR frame stale — the sensor has a fresh observation. By erasing entire Z-columns in the footprint, we guarantee: + +- No ghost obstacles from previous passes +- Dynamic objects (people, doors) get cleared automatically +- The latest observation always wins + +We don't have proper loop closure and stable odometry, we trust the data go2 reports, which is surprisingly stable but does drift eventually, You will reliably map and nav through very large spaces (500sqm in our tests) but you won't go down the street to a super market. + +Voxel hash map provides O(1) insert/erase/lookup, so this is efficient even with millions of voxels. The grid runs on **CUDA** by default for speed, with CPU fallback. + +#### Configuration + +| Parameter | Default | Description | +|--------------------|-----------|---------------------------------------------------------| +| `voxel_size` | 0.05 | Voxel cube size in meters | +| `block_count` | 2,000,000 | Max voxels in hash map | +| `device` | `CUDA:0` | Compute device (`CUDA:0` or `CPU:0`) | +| `carve_columns` | `true` | Enable column carving (disable for append-only mapping) | +| `publish_interval` | 0 | Seconds between map publishes (0 = every frame) | ![Global map](assets/2-globalmap.png) ### 3. Global Costmap — `CostMapper` -The [`CostMapper`](/dimos/mapping/costmapper.py) converts the 3D voxel map into a 2D occupancy grid. The default algorithm (`height_cost`) works as follows: +The [`CostMapper`](/dimos/mapping/costmapper.py) converts the 3D voxel map into a 2D occupancy grid. The default algorithm (`height_cost`) maps rate of change of Z, with some smoothing. + +algo settings are in [`occupancy.py`](/dimos/mapping/pointclouds/occupancy.py) and can be configured per robot + -1. **Height maps**: For each (X, Y) cell, find min and max Z across all voxels -2. **Pass-under detection**: If the vertical gap exceeds `can_pass_under` (default 0.6m), the robot can fit underneath — use ground height instead of obstacle height -3. **Slope analysis**: Apply Sobel filter to the height map to compute terrain gradient -4. **Cost assignment**: `cost = (gradient × resolution / can_climb) × 100`, clamped to [0, 100] +#### Configuration + +```python +@dataclass(frozen=True) +class HeightCostConfig(OccupancyConfig): + """Config for height-cost based occupancy (terrain slope analysis).""" + can_pass_under: float = 0.6 + can_climb: float = 0.15 + ignore_noise: float = 0.05 + smoothing: float = 1.0 +``` -| Cost | Meaning | -|------|---------| -| 0 | Flat, easy to traverse | -| 50 | Moderate slope (~7.5cm rise per cell) | -| 100 | Steep or impassable (≥15cm rise per cell) | -| -1 | Unknown (no observations) | +| Cost | Meaning | +|------|----------------------------------------------------------| +| 0 | Flat, easy to traverse | +| 50 | Moderate slope (~7.5cm rise per cell in case of go2) | +| 100 | Steep or impassable (≥15cm rise per cell in case of go2) | +| -1 | Unknown (no observations) | ![Global costmap](assets/3-globalcostmap.png) @@ -73,36 +103,6 @@ All visualization layers shown together — 3D voxel map, 2D costmap, and the pl ![All layers](assets/5-all.png) ---- - -## Voxel Mapping & Column Carving - -The [`VoxelGridMapper`](/dimos/mapping/voxels.py) maintains a sparse 3D occupancy grid using Open3D's `VoxelBlockGrid` backed by a hash map. Each voxel is a 5cm cube by default. - -The robot's LiDAR sees a cone of space from its current position. Within that cone, any previously mapped voxels are now stale — the sensor has a fresh observation. By erasing entire Z-columns in the footprint, we guarantee: - -- No ghost obstacles from previous passes -- Dynamic objects (people, doors) get cleared automatically -- The latest observation always wins - -The hash map provides O(1) insert/erase/lookup, so this is efficient even with millions of voxels. The grid runs on **CUDA** by default for speed, with CPU fallback. - -### How frames are added - -1. Incoming points are quantized to voxel coordinates: `vox = floor(point / voxel_size)` -2. The (X, Y) footprint of the new frame is extracted -3. **All existing voxels** sharing those (X, Y) coordinates are erased — the entire Z-column is removed -4. New voxels are inserted - -```python skip -# Column carving: erase all existing voxels sharing (X,Y) with new data -xy_keys = new_keys[:, :2] # extract (X,Y) footprint -xy_hashmap.insert(xy_keys, ...) # build lookup -_, found_mask = xy_hashmap.find(existing_xy) # find overlapping columns -self._voxel_hashmap.erase(existing[found_mask]) # erase old -self._voxel_hashmap.activate(new_keys) # insert new -``` - ## Blueprint Composition The navigation stack is composed in the [`unitree_go2`](/dimos/robot/unitree/go2/blueprints/__init__.py) blueprint: @@ -110,36 +110,9 @@ The navigation stack is composed in the [`unitree_go2`](/dimos/robot/unitree/go2 ```python skip unitree_go2 = autoconnect( unitree_go2_basic, # robot connection + visualization - voxel_mapper(voxel_size=0.1), # 3D voxel mapping - cost_mapper(), # 2D costmap generation + voxel_mapper(voxel_size=0.1), # 3D voxel mapping - Voxel Mapper config goes here + cost_mapper(), # 2D costmap generation - Costmapper config goes here replanning_a_star_planner(), # path planning wavefront_frontier_explorer(), # exploration ).global_config(n_dask_workers=6, robot_model="unitree_go2") ``` - -Modules are auto-wired by matching stream names and types: -- `GO2Connection.pointcloud` → `VoxelGridMapper.lidar` (both `PointCloud2`) -- `VoxelGridMapper.global_map` → `CostMapper.global_map` (both `PointCloud2`) -- `CostMapper.global_costmap` → planner and explorer (both `OccupancyGrid`) - -## Configuration - -### Voxel Mapper - -| Parameter | Default | Description | -|-----------|---------|-------------| -| `voxel_size` | 0.05 | Voxel cube size in meters | -| `block_count` | 2,000,000 | Max voxels in hash map | -| `device` | `CUDA:0` | Compute device (`CUDA:0` or `CPU:0`) | -| `carve_columns` | `true` | Enable column carving (disable for append-only mapping) | -| `publish_interval` | 0 | Seconds between map publishes (0 = every frame) | - -### Cost Mapper (height_cost) - -| Parameter | Default | Description | -|-----------|---------|-------------| -| `resolution` | 0.05 | 2D grid cell size in meters | -| `can_pass_under` | 0.6 | Min gap height the robot can fit through (m) | -| `can_climb` | 0.15 | Height change that maps to cost 100 (m) | -| `ignore_noise` | 0.05 | Height changes below this are zeroed (m) | -| `smoothing` | 1.0 | Gaussian sigma for height map smoothing | From 961b0b4b425de03064898f2024c9a3d6f26942de Mon Sep 17 00:00:00 2001 From: Ivan Nikolic Date: Sun, 15 Feb 2026 23:17:40 +0800 Subject: [PATCH 103/140] nav wrap --- .../native/assets/go2nav_dataflow.svg | 40 ++++++++++--------- docs/capabilities/navigation/native/index.md | 22 ++++++++-- 2 files changed, 41 insertions(+), 21 deletions(-) diff --git a/docs/capabilities/navigation/native/assets/go2nav_dataflow.svg b/docs/capabilities/navigation/native/assets/go2nav_dataflow.svg index fa352c68b9..616c6cf92f 100644 --- a/docs/capabilities/navigation/native/assets/go2nav_dataflow.svg +++ b/docs/capabilities/navigation/native/assets/go2nav_dataflow.svg @@ -1,19 +1,23 @@ - - -Go2 - - -PointCloud2 - -VoxelGridMapper - - -PointCloud2 - -CostMapper - - -OccupancyGrid - -Navigation + + +Go2 + + + +VoxelGridMapper + + + +CostMapper + + + +Navigation +PointCloud2 +PointCloud2 +OccupancyGrid + + + +Twist diff --git a/docs/capabilities/navigation/native/index.md b/docs/capabilities/navigation/native/index.md index b4d6892f6a..02874ab6ee 100644 --- a/docs/capabilities/navigation/native/index.md +++ b/docs/capabilities/navigation/native/index.md @@ -9,17 +9,33 @@ The Go2 navigation stack runs entirely without ROS. It uses a **column-carving v
diagram source +
Pikchr + ```pikchr fold output=assets/go2nav_dataflow.svg color = white fill = none Go2: box "Go2" rad 5px fit wid 170% ht 170% -arrow right 0.5in "PointCloud2" above italic +arrow right 0.5in Vox: box "VoxelGridMapper" rad 5px fit wid 170% ht 170% -arrow right 0.5in "PointCloud2" above italic +arrow right 0.5in Cost: box "CostMapper" rad 5px fit wid 170% ht 170% -arrow right 0.5in "OccupancyGrid" above italic +arrow right 0.5in Nav: box "Navigation" rad 5px fit wid 170% ht 170% + +M1: dot at 1/2 way between Go2.e and Vox.w invisible +text "PointCloud2" italic at (M1.x, Go2.n.y + 0.15in) + +M2: dot at 1/2 way between Vox.e and Cost.w invisible +text "PointCloud2" italic at (M2.x, Vox.n.y + 0.15in) + +M3: dot at 1/2 way between Cost.e and Nav.w invisible +text "OccupancyGrid" italic at (M3.x, Cost.n.y + 0.15in) + +line dashed from Nav.s down 0.3in then left until even with Go2.s then to Go2.s +arrow dashed from Go2.s + (0.01in, 0.01in) to Go2.s +M4: dot at 1/2 way between Go2.s and Nav.s invisible +text "Twist" italic at (M4.x, Nav.s.y - 0.45in) ```
From 0fc417a076d2c19a2e52f91d818582dbc68cdf50 Mon Sep 17 00:00:00 2001 From: Ivan Nikolic Date: Sun, 15 Feb 2026 23:19:41 +0800 Subject: [PATCH 104/140] docs: fix pikchr diagram - labels above/below, dashed Twist arrow --- .../navigation/native/assets/go2nav_dataflow.svg | 5 ++--- docs/capabilities/navigation/native/index.md | 3 +-- 2 files changed, 3 insertions(+), 5 deletions(-) diff --git a/docs/capabilities/navigation/native/assets/go2nav_dataflow.svg b/docs/capabilities/navigation/native/assets/go2nav_dataflow.svg index 616c6cf92f..94bb3e39ee 100644 --- a/docs/capabilities/navigation/native/assets/go2nav_dataflow.svg +++ b/docs/capabilities/navigation/native/assets/go2nav_dataflow.svg @@ -16,8 +16,7 @@ PointCloud2 PointCloud2 OccupancyGrid - - - + + Twist
diff --git a/docs/capabilities/navigation/native/index.md b/docs/capabilities/navigation/native/index.md index 02874ab6ee..510050e825 100644 --- a/docs/capabilities/navigation/native/index.md +++ b/docs/capabilities/navigation/native/index.md @@ -32,8 +32,7 @@ text "PointCloud2" italic at (M2.x, Vox.n.y + 0.15in) M3: dot at 1/2 way between Cost.e and Nav.w invisible text "OccupancyGrid" italic at (M3.x, Cost.n.y + 0.15in) -line dashed from Nav.s down 0.3in then left until even with Go2.s then to Go2.s -arrow dashed from Go2.s + (0.01in, 0.01in) to Go2.s +arrow dashed from Nav.s down 0.3in then left until even with Go2.s then to Go2.s M4: dot at 1/2 way between Go2.s and Nav.s invisible text "Twist" italic at (M4.x, Nav.s.y - 0.45in) ``` From 7ef33c9a24bee5e8b422cea03ed0e8f70e3a2ff4 Mon Sep 17 00:00:00 2001 From: Ivan Nikolic Date: Sun, 15 Feb 2026 23:19:55 +0800 Subject: [PATCH 105/140] diagram fixed --- docs/capabilities/navigation/native/index.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/docs/capabilities/navigation/native/index.md b/docs/capabilities/navigation/native/index.md index 510050e825..34091ac11e 100644 --- a/docs/capabilities/navigation/native/index.md +++ b/docs/capabilities/navigation/native/index.md @@ -9,8 +9,6 @@ The Go2 navigation stack runs entirely without ROS. It uses a **column-carving v
diagram source -
Pikchr - ```pikchr fold output=assets/go2nav_dataflow.svg color = white fill = none From 08d265d8c082d6102dae5a5cb89da8dd5d178876 Mon Sep 17 00:00:00 2001 From: Ivan Nikolic Date: Mon, 16 Feb 2026 00:10:14 +0800 Subject: [PATCH 106/140] .. --- docs/capabilities/navigation/native/index.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/docs/capabilities/navigation/native/index.md b/docs/capabilities/navigation/native/index.md index 34091ac11e..631c957460 100644 --- a/docs/capabilities/navigation/native/index.md +++ b/docs/capabilities/navigation/native/index.md @@ -52,15 +52,16 @@ We don't connect to the LiDAR directly — instead we use Unitree's WebRTC clien The [`VoxelGridMapper`](/dimos/mapping/voxels.py) maintains a sparse 3D occupancy grid using Open3D's `VoxelBlockGrid` backed by a hash map. Each voxel is a 5cm cube by default. -Each incoming LiDAR frame is spliced into the global map via column carving. We consider any previously mapped voxels in the space of a received LiDAR frame stale — the sensor has a fresh observation. By erasing entire Z-columns in the footprint, we guarantee: +Voxel hash map provides O(1) insert/erase/lookup, so this is efficient even with millions of voxels. The grid runs on **CUDA** by default for speed, with CPU fallback. + +Each incoming LiDAR frame is spliced into the global map via column carving. We consider any previously mapped voxels in the space of a received LiDAR frame stale, by erasing entire Z-columns in the footprint, we guarantee: - No ghost obstacles from previous passes - Dynamic objects (people, doors) get cleared automatically - The latest observation always wins -We don't have proper loop closure and stable odometry, we trust the data go2 reports, which is surprisingly stable but does drift eventually, You will reliably map and nav through very large spaces (500sqm in our tests) but you won't go down the street to a super market. +We don't have proper loop closure and stable odometry, we trust the data go2 odom reports, which is surprisingly stable but does drift eventually, You will reliably map and nav through very large spaces (500sqm in our tests) but you won't go down the street to a super market. -Voxel hash map provides O(1) insert/erase/lookup, so this is efficient even with millions of voxels. The grid runs on **CUDA** by default for speed, with CPU fallback. #### Configuration From a658f5b0575534fbb6e838a617a8723b9f08b754 Mon Sep 17 00:00:00 2001 From: Ivan Nikolic Date: Mon, 16 Feb 2026 00:14:16 +0800 Subject: [PATCH 107/140] .. --- docs/capabilities/navigation/native/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/capabilities/navigation/native/index.md b/docs/capabilities/navigation/native/index.md index 631c957460..cc9ab0910c 100644 --- a/docs/capabilities/navigation/native/index.md +++ b/docs/capabilities/navigation/native/index.md @@ -113,7 +113,7 @@ We run the planner in a constant loop so it will dynamically react to obstacles ### 5. All Layers Combined -All visualization layers shown together — 3D voxel map, 2D costmap, and the planned path overlaid in a single view. +All visualization layers shown together ![All layers](assets/5-all.png) From e714310cd2777a1f665360e1d613295796815121 Mon Sep 17 00:00:00 2001 From: Ivan Nikolic Date: Mon, 16 Feb 2026 00:27:30 +0800 Subject: [PATCH 108/140] .. --- docs/capabilities/navigation/native/index.md | 13 ++++++------- 1 file changed, 6 insertions(+), 7 deletions(-) diff --git a/docs/capabilities/navigation/native/index.md b/docs/capabilities/navigation/native/index.md index cc9ab0910c..ab78cdc2e8 100644 --- a/docs/capabilities/navigation/native/index.md +++ b/docs/capabilities/navigation/native/index.md @@ -34,7 +34,6 @@ arrow dashed from Nav.s down 0.3in then left until even with Go2.s then to Go2.s M4: dot at 1/2 way between Go2.s and Nav.s invisible text "Twist" italic at (M4.x, Nav.s.y - 0.45in) ``` -
@@ -42,11 +41,11 @@ text "Twist" italic at (M4.x, Nav.s.y - 0.45in) ## Pipeline Steps -### 1. LiDAR Frame — `GO2Connection` +### 1. LiDAR Frame — [`GO2Connection`](../../../../dimos/robot/unitree/go2/connection.py) We don't connect to the LiDAR directly — instead we use Unitree's WebRTC client (via [legion's webrtc driver](https://github.com/legion1581/unitree_webrtc_connect)), which streams a heavily preprocessed 5cm voxel grid rather than raw point cloud data. This allows us to support stock, unjailbroken Go2 Air and Pro models out of the box. -![LiDAR frame](assets/1-lidar.png) + ### 2. Global Voxel Map — `VoxelGridMapper` @@ -73,7 +72,7 @@ We don't have proper loop closure and stable odometry, we trust the data go2 odo | `carve_columns` | `true` | Enable column carving (disable for append-only mapping) | | `publish_interval` | 0 | Seconds between map publishes (0 = every frame) | -![Global map](assets/2-globalmap.png) + ### 3. Global Costmap — `CostMapper` @@ -101,7 +100,7 @@ class HeightCostConfig(OccupancyConfig): | 100 | Steep or impassable (≥15cm rise per cell in case of go2) | | -1 | Unknown (no observations) | -![Global costmap](assets/3-globalcostmap.png) + ### 4. Navigation Costmap — `ReplanningAStarPlanner` @@ -109,13 +108,13 @@ The planner will process the terrain gradient and compute it's own algo-relevant We run the planner in a constant loop so it will dynamically react to obstacles encountered. -![Navigation costmap with path](assets/4-navcostmap.png) + ### 5. All Layers Combined All visualization layers shown together -![All layers](assets/5-all.png) + ## Blueprint Composition From d950dfb05b38de35716f84a42db12a2ab3053a1a Mon Sep 17 00:00:00 2001 From: Ivan Nikolic Date: Mon, 16 Feb 2026 00:29:45 +0800 Subject: [PATCH 109/140] .. --- docs/capabilities/navigation/native/index.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/docs/capabilities/navigation/native/index.md b/docs/capabilities/navigation/native/index.md index ab78cdc2e8..d11b4185a5 100644 --- a/docs/capabilities/navigation/native/index.md +++ b/docs/capabilities/navigation/native/index.md @@ -41,13 +41,13 @@ text "Twist" italic at (M4.x, Nav.s.y - 0.45in) ## Pipeline Steps -### 1. LiDAR Frame — [`GO2Connection`](../../../../dimos/robot/unitree/go2/connection.py) +### 1. LiDAR Frame — [`GO2Connection`](/dimos/robot/unitree/go2/connection.py) We don't connect to the LiDAR directly — instead we use Unitree's WebRTC client (via [legion's webrtc driver](https://github.com/legion1581/unitree_webrtc_connect)), which streams a heavily preprocessed 5cm voxel grid rather than raw point cloud data. This allows us to support stock, unjailbroken Go2 Air and Pro models out of the box. - +![LiDAR frame](assets/1-lidar.png) -### 2. Global Voxel Map — `VoxelGridMapper` +### 2. Global Voxel Map — [`VoxelGridMapper`](/dimos/mapping/voxels.py) The [`VoxelGridMapper`](/dimos/mapping/voxels.py) maintains a sparse 3D occupancy grid using Open3D's `VoxelBlockGrid` backed by a hash map. Each voxel is a 5cm cube by default. @@ -72,7 +72,7 @@ We don't have proper loop closure and stable odometry, we trust the data go2 odo | `carve_columns` | `true` | Enable column carving (disable for append-only mapping) | | `publish_interval` | 0 | Seconds between map publishes (0 = every frame) | - +![Global map](assets/2-globalmap.png) ### 3. Global Costmap — `CostMapper` @@ -100,21 +100,21 @@ class HeightCostConfig(OccupancyConfig): | 100 | Steep or impassable (≥15cm rise per cell in case of go2) | | -1 | Unknown (no observations) | - +![Global costmap](assets/3-globalcostmap.png) -### 4. Navigation Costmap — `ReplanningAStarPlanner` +### 4. Navigation Costmap — [`ReplanningAStarPlanner`](/dimos/navigation/replanning_a_star/module.py) The planner will process the terrain gradient and compute it's own algo-relevant costmap, prioritizing safe free paths, while be willing to path aggressively through tight spaces if it has to We run the planner in a constant loop so it will dynamically react to obstacles encountered. - +![Navigation costmap with path](assets/4-navcostmap.png) ### 5. All Layers Combined All visualization layers shown together - +![All layers](assets/5-all.png) ## Blueprint Composition From f5ff030f2847bcca7aeddb04f7061b041a96e19a Mon Sep 17 00:00:00 2001 From: Ivan Nikolic Date: Mon, 16 Feb 2026 00:31:16 +0800 Subject: [PATCH 110/140] docs: link CostMapper heading to source file in nav docs --- docs/capabilities/navigation/native/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/capabilities/navigation/native/index.md b/docs/capabilities/navigation/native/index.md index d11b4185a5..e1bfac58e3 100644 --- a/docs/capabilities/navigation/native/index.md +++ b/docs/capabilities/navigation/native/index.md @@ -74,7 +74,7 @@ We don't have proper loop closure and stable odometry, we trust the data go2 odo ![Global map](assets/2-globalmap.png) -### 3. Global Costmap — `CostMapper` +### 3. Global Costmap — [`CostMapper`](/dimos/mapping/costmapper.py) The [`CostMapper`](/dimos/mapping/costmapper.py) converts the 3D voxel map into a 2D occupancy grid. The default algorithm (`height_cost`) maps rate of change of Z, with some smoothing. From 86d25b87e028802eb72c6c54cd1f4f0431844417 Mon Sep 17 00:00:00 2001 From: Ivan Nikolic Date: Mon, 16 Feb 2026 00:36:21 +0800 Subject: [PATCH 111/140] .. --- .../native/assets/go2_blueprint.svg | 188 ++++++++++++++++++ docs/capabilities/navigation/native/index.md | 29 ++- 2 files changed, 213 insertions(+), 4 deletions(-) create mode 100644 docs/capabilities/navigation/native/assets/go2_blueprint.svg diff --git a/docs/capabilities/navigation/native/assets/go2_blueprint.svg b/docs/capabilities/navigation/native/assets/go2_blueprint.svg new file mode 100644 index 0000000000..51b0e7c40f --- /dev/null +++ b/docs/capabilities/navigation/native/assets/go2_blueprint.svg @@ -0,0 +1,188 @@ + + + + + + +modules + +cluster_mapping + +mapping + + +cluster_navigation + +navigation + + +cluster_robot + +robot + + +cluster_visualization + +visualization + + + +CostMapper + +CostMapper + + + +chan_global_costmap_OccupancyGrid + + + +global_costmap:OccupancyGrid + + + +CostMapper->chan_global_costmap_OccupancyGrid + + + + +VoxelGridMapper + +VoxelGridMapper + + + +chan_global_map_PointCloud2 + + + +global_map:PointCloud2 + + + +VoxelGridMapper->chan_global_map_PointCloud2 + + + + +ReplanningAStarPlanner + +ReplanningAStarPlanner + + + +chan_cmd_vel_Twist + + + +cmd_vel:Twist + + + +ReplanningAStarPlanner->chan_cmd_vel_Twist + + + + +chan_goal_reached_Bool + + + +goal_reached:Bool + + + +ReplanningAStarPlanner->chan_goal_reached_Bool + + + + +WavefrontFrontierExplorer + +WavefrontFrontierExplorer + + + +chan_goal_request_PoseStamped + + + +goal_request:PoseStamped + + + +WavefrontFrontierExplorer->chan_goal_request_PoseStamped + + + + +GO2Connection + +GO2Connection + + + +chan_lidar_PointCloud2 + + + +lidar:PointCloud2 + + + +GO2Connection->chan_lidar_PointCloud2 + + + + +RerunBridgeModule + +RerunBridgeModule + + + +chan_cmd_vel_Twist->GO2Connection + + + + + +chan_global_costmap_OccupancyGrid->ReplanningAStarPlanner + + + + + +chan_global_costmap_OccupancyGrid->WavefrontFrontierExplorer + + + + + +chan_global_map_PointCloud2->CostMapper + + + + + +chan_goal_reached_Bool->WavefrontFrontierExplorer + + + + + +chan_goal_request_PoseStamped->ReplanningAStarPlanner + + + + + +chan_lidar_PointCloud2->VoxelGridMapper + + + + + diff --git a/docs/capabilities/navigation/native/index.md b/docs/capabilities/navigation/native/index.md index e1bfac58e3..11fc984706 100644 --- a/docs/capabilities/navigation/native/index.md +++ b/docs/capabilities/navigation/native/index.md @@ -9,6 +9,8 @@ The Go2 navigation stack runs entirely without ROS. It uses a **column-carving v
diagram source +
Pikchr + ```pikchr fold output=assets/go2nav_dataflow.svg color = white fill = none @@ -34,10 +36,12 @@ arrow dashed from Nav.s down 0.3in then left until even with Go2.s then to Go2.s M4: dot at 1/2 way between Go2.s and Nav.s invisible text "Twist" italic at (M4.x, Nav.s.y - 0.45in) ``` +
![output](assets/go2nav_dataflow.svg) +
## Pipeline Steps @@ -83,7 +87,7 @@ algo settings are in [`occupancy.py`](/dimos/mapping/pointclouds/occupancy.py) a #### Configuration -```python +```python skip @dataclass(frozen=True) class HeightCostConfig(OccupancyConfig): """Config for height-cost based occupancy (terrain slope analysis).""" @@ -120,12 +124,29 @@ All visualization layers shown together The navigation stack is composed in the [`unitree_go2`](/dimos/robot/unitree/go2/blueprints/__init__.py) blueprint: -```python skip +
Python + +```python fold output=assets/go2_blueprint.svg +from dimos.core.blueprints import autoconnect +from dimos.core.introspection import to_svg +from dimos.mapping.costmapper import cost_mapper +from dimos.mapping.voxels import voxel_mapper +from dimos.navigation.frontier_exploration import wavefront_frontier_explorer +from dimos.navigation.replanning_a_star.module import replanning_a_star_planner +from dimos.robot.unitree.go2.blueprints.basic.unitree_go2_basic import unitree_go2_basic + unitree_go2 = autoconnect( unitree_go2_basic, # robot connection + visualization - voxel_mapper(voxel_size=0.1), # 3D voxel mapping - Voxel Mapper config goes here - cost_mapper(), # 2D costmap generation - Costmapper config goes here + voxel_mapper(voxel_size=0.05), # 3D voxel mapping + cost_mapper(), # 2D costmap generation replanning_a_star_planner(), # path planning wavefront_frontier_explorer(), # exploration ).global_config(n_dask_workers=6, robot_model="unitree_go2") + +to_svg(unitree_go2, "assets/go2_blueprint.svg") ``` + +
+ + +![output](assets/go2_blueprint.svg) From 3835c500db25e2a8c243f3f7a9319338c54c23de Mon Sep 17 00:00:00 2001 From: Ivan Nikolic Date: Mon, 16 Feb 2026 00:37:18 +0800 Subject: [PATCH 112/140] .. --- docs/capabilities/navigation/native/index.md | 4 ---- 1 file changed, 4 deletions(-) diff --git a/docs/capabilities/navigation/native/index.md b/docs/capabilities/navigation/native/index.md index 11fc984706..700c5f99a7 100644 --- a/docs/capabilities/navigation/native/index.md +++ b/docs/capabilities/navigation/native/index.md @@ -124,8 +124,6 @@ All visualization layers shown together The navigation stack is composed in the [`unitree_go2`](/dimos/robot/unitree/go2/blueprints/__init__.py) blueprint: -
Python - ```python fold output=assets/go2_blueprint.svg from dimos.core.blueprints import autoconnect from dimos.core.introspection import to_svg @@ -146,7 +144,5 @@ unitree_go2 = autoconnect( to_svg(unitree_go2, "assets/go2_blueprint.svg") ``` -
- ![output](assets/go2_blueprint.svg) From 9b237699e6cd1daddf2c513cc95b967a17383953 Mon Sep 17 00:00:00 2001 From: Ivan Nikolic Date: Mon, 16 Feb 2026 00:38:27 +0800 Subject: [PATCH 113/140] .. --- docs/capabilities/navigation/native/index.md | 4 ---- 1 file changed, 4 deletions(-) diff --git a/docs/capabilities/navigation/native/index.md b/docs/capabilities/navigation/native/index.md index 700c5f99a7..115c6f0ee2 100644 --- a/docs/capabilities/navigation/native/index.md +++ b/docs/capabilities/navigation/native/index.md @@ -9,8 +9,6 @@ The Go2 navigation stack runs entirely without ROS. It uses a **column-carving v
diagram source -
Pikchr - ```pikchr fold output=assets/go2nav_dataflow.svg color = white fill = none @@ -41,8 +39,6 @@ text "Twist" italic at (M4.x, Nav.s.y - 0.45in) ![output](assets/go2nav_dataflow.svg) -
- ## Pipeline Steps ### 1. LiDAR Frame — [`GO2Connection`](/dimos/robot/unitree/go2/connection.py) From 6f7f5cb80cc827c9596e859c5a9fb52da2426101 Mon Sep 17 00:00:00 2001 From: Ivan Nikolic Date: Mon, 16 Feb 2026 12:37:26 +0800 Subject: [PATCH 114/140] .. --- README.md | 14 ++-- assets/readme/spacer.png | 3 + docs/api/transports/dds.md | 26 ++++++ .../{transports.md => transports/index.md} | 0 docs/development/README.md | 34 -------- docs/installation/nix.md | 80 ++++++++++++++++++- .../platforms/{dog => quadruped}/go2/index.md | 0 docs/todo.md | 1 + 8 files changed, 116 insertions(+), 42 deletions(-) create mode 100644 assets/readme/spacer.png create mode 100644 docs/api/transports/dds.md rename docs/api/{transports.md => transports/index.md} (100%) rename docs/platforms/{dog => quadruped}/go2/index.md (100%) create mode 100644 docs/todo.md diff --git a/README.md b/README.md index ff520daa5f..e39446efc2 100644 --- a/README.md +++ b/README.md @@ -99,21 +99,21 @@ Our goal is to provide an easy-to-install, modern framework for general robotics
- 🟩 Unitree Go2 pro/air
+ 🟩 Unitree Go2 pro/air
 - 🟧 Unitree G1
+ 🟥 Unitree G1
 - 🟨 Xarm
- 🟨 Piper
+ 🟥 Xarm
+ 🟥 Piper
 - 🟧 Mavlink
- 🟥 DJI SDK
+ 🟥 Mavlink
+ 🟥 DJI SDK
 - 🟨 Force Torque Sensor
+ 🟥 Force Torque Sensor
diff --git a/assets/readme/spacer.png b/assets/readme/spacer.png new file mode 100644 index 0000000000..8745fc9687 --- /dev/null +++ b/assets/readme/spacer.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:4a16ec40112698cf02b9abd3d18c8db65ce40f48f2c61076b45de58695f16532 +size 66 diff --git a/docs/api/transports/dds.md b/docs/api/transports/dds.md new file mode 100644 index 0000000000..1aec0bafe5 --- /dev/null +++ b/docs/api/transports/dds.md @@ -0,0 +1,26 @@ +# Installing DDS Transport Libs on Ubuntu + +The `dds` extra provides DDS (Data Distribution Service) transport support via [Eclipse Cyclone DDS](https://cyclonedds.io/docs/cyclonedds-python/latest/). This requires installing system libraries before the Python package can be built. + +```bash +# Install the CycloneDDS development library +sudo apt install cyclonedds-dev + +# Create a compatibility directory structure +# (required because Ubuntu's multiarch layout doesn't match the expected CMake layout) +sudo mkdir -p /opt/cyclonedds/{lib,bin,include} +sudo ln -sf /usr/lib/x86_64-linux-gnu/libddsc.so* /opt/cyclonedds/lib/ +sudo ln -sf /usr/lib/x86_64-linux-gnu/libcycloneddsidl.so* /opt/cyclonedds/lib/ +sudo ln -sf /usr/bin/idlc /opt/cyclonedds/bin/ +sudo ln -sf /usr/bin/ddsperf /opt/cyclonedds/bin/ +sudo ln -sf /usr/include/dds /opt/cyclonedds/include/ + +# Install with the dds extra +CYCLONEDDS_HOME=/opt/cyclonedds uv pip install -e '.[dds]' +``` + +To install all extras including DDS: + +```bash +CYCLONEDDS_HOME=/opt/cyclonedds uv sync --extra dds +``` diff --git a/docs/api/transports.md b/docs/api/transports/index.md similarity index 100% rename from docs/api/transports.md rename to docs/api/transports/index.md diff --git a/docs/development/README.md b/docs/development/README.md index c7d903e690..48a3ab8d79 100644 --- a/docs/development/README.md +++ b/docs/development/README.md @@ -71,38 +71,6 @@ uv add git+https://github.com/openai/CLIP.git uv add git+https://github.com/facebookresearch/detectron2.git ``` -### Optional: DDS Transport Support - -The `dds` extra provides DDS (Data Distribution Service) transport support via [Eclipse Cyclone DDS](https://cyclonedds.io/docs/cyclonedds-python/latest/). This requires installing system libraries before the Python package can be built. - -**Ubuntu/Debian:** - -```bash -# Install the CycloneDDS development library -sudo apt install cyclonedds-dev - -# Create a compatibility directory structure -# (required because Ubuntu's multiarch layout doesn't match the expected CMake layout) -sudo mkdir -p /opt/cyclonedds/{lib,bin,include} -sudo ln -sf /usr/lib/x86_64-linux-gnu/libddsc.so* /opt/cyclonedds/lib/ -sudo ln -sf /usr/lib/x86_64-linux-gnu/libcycloneddsidl.so* /opt/cyclonedds/lib/ -sudo ln -sf /usr/bin/idlc /opt/cyclonedds/bin/ -sudo ln -sf /usr/bin/ddsperf /opt/cyclonedds/bin/ -sudo ln -sf /usr/include/dds /opt/cyclonedds/include/ - -# Install with the dds extra -CYCLONEDDS_HOME=/opt/cyclonedds uv pip install -e '.[dds]' -``` - -To install all extras including DDS: - -```bash -CYCLONEDDS_HOME=/opt/cyclonedds uv sync --extra dds -``` - - - - ## Setup Option B: Nix Flake + direnv ### Why pick this option? (pros/cons/when-to-use) diff --git a/docs/installation/nix.md b/docs/installation/nix.md index 342a8c5191..fa4b8010ab 100644 --- a/docs/installation/nix.md +++ b/docs/installation/nix.md @@ -1 +1,79 @@ -# nix install +# System Dependancies Install + +## Nix install (all linux) +You need to have [nix](https://nixos.org/) installed and [flakes](https://nixos.wiki/wiki/Flakes) enabled, + +[official install docs](https://nixos.org/download/) recomended, but here is a quickstart: + +```sh +# Install Nix https://nixos.org/download/ +curl --proto '=https' --tlsv1.2 -sSf -L https://install.determinate.systems/nix | sh -s -- install +. /nix/var/nix/profiles/default/etc/profile.d/nix-daemon.sh + +# make sure nix-flakes are enabled +mkdir -p "$HOME/.config/nix"; echo "experimental-features = nix-command flakes" >> "$HOME/.config/nix/nix.conf" +``` + +## Ubuntu 22.04 or 24.04 +```sh +sudo apt-get update +sudo apt-get install -y curl g++ portaudio19-dev git-lfs libturbojpeg python3-dev pre-commit + +# install uv +curl -LsSf https://astral.sh/uv/install.sh | sh && export PATH="$HOME/.local/bin:$PATH" +``` + +## macOS 12.6 or newer +```sh +# install homebrew +/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)" +# install dependencies +brew install gnu-sed gcc portaudio git-lfs libjpeg-turbo python pre-commit + +# install uv +curl -LsSf https://astral.sh/uv/install.sh | sh && export PATH="$HOME/.local/bin:$PATH" +``` + +# DimOS as a library + +```sh +mkdir myproject +cd myproject + +uv venv --python "3.12" +source .env/bin/activate + +# if on nixos you can pull our flake +wget https://raw.githubusercontent.com/dimensionalOS/dimos/refs/heads/main/flake.nix +wget https://raw.githubusercontent.com/dimensionalOS/dimos/refs/heads/main/flake.lock + +# this will just pull everything (big checkout) +# depending on what you are working on you might not need everything, +# check your respectative platform guides +uv pip install dimos[misc,sim,visualization,agents,web,perception,unitree,manipulation,cpu,dev] +``` + +# Developing on DimOS +```sh +# this allows getting large files on-demand (and not pulling all immediately) +export GIT_LFS_SKIP_SMUDGE=1 +git clone -b dev https://github.com/dimensionalOS/dimos.git +cd dimos + +# create venv +uv venv --python 3.12 + +source .env/bin/activate + +uv sync --all-extras + +# type check +uv run mypy dimos + +# tests (around a minute to run) +uv run pytest dimos +``` + +# direnv + +[Direnv](https://direnv.net/) is super convinient for auto-entering your nix env of uv venv diff --git a/docs/platforms/dog/go2/index.md b/docs/platforms/quadruped/go2/index.md similarity index 100% rename from docs/platforms/dog/go2/index.md rename to docs/platforms/quadruped/go2/index.md diff --git a/docs/todo.md b/docs/todo.md new file mode 100644 index 0000000000..464090415c --- /dev/null +++ b/docs/todo.md @@ -0,0 +1 @@ +# TODO From 0f4bf5ebf904e2d6c789e2051d39b55e27413567 Mon Sep 17 00:00:00 2001 From: Ivan Nikolic Date: Thu, 19 Feb 2026 14:42:50 +0800 Subject: [PATCH 115/140] agents doc --- docs/agents/index.md | 19 +++++++++++++++++++ 1 file changed, 19 insertions(+) create mode 100644 docs/agents/index.md diff --git a/docs/agents/index.md b/docs/agents/index.md new file mode 100644 index 0000000000..ec9d66e886 --- /dev/null +++ b/docs/agents/index.md @@ -0,0 +1,19 @@ +# For Agents + +These docs are mostly for coding agents + +```sh +tree . -P '*.md' --prune +``` + + +``` +. +├── docs +│   ├── codeblocks.md +│   ├── doclinks.md +│   └── index.md +└── index.md + +2 directories, 4 files +``` From ed6de87ea90947a81ce30de6db12856b180bfa37 Mon Sep 17 00:00:00 2001 From: Ivan Nikolic Date: Thu, 19 Feb 2026 14:46:43 +0800 Subject: [PATCH 116/140] API renamed to usage --- docs/api/README.md | 12 ------------ 1 file changed, 12 deletions(-) delete mode 100644 docs/api/README.md diff --git a/docs/api/README.md b/docs/api/README.md deleted file mode 100644 index 30831610bb..0000000000 --- a/docs/api/README.md +++ /dev/null @@ -1,12 +0,0 @@ -# Concepts - -This page explains general concepts. - -## Table of Contents - -- [Modules](/docs/usage/modules.md): The primary units of deployment in DimOS, modules run in parallel and are python classes. -- [Streams](/docs/usage/data_streams/README.md): How modules communicate, a Pub / Sub system. -- [Blueprints](/docs/usage/blueprints.md): a way to group modules together and define their connections to each other. -- [RPC](/docs/usage/blueprints.md#calling-the-methods-of-other-modules): how one module can call a method on another module (arguments get serialized to JSON-like binary data). -- [Skills](/docs/usage/blueprints.md#defining-skills): An RPC function, except it can be called by an AI agent (a tool for an AI). -- Agents: AI that has an objective, access to stream data, and is capable of calling skills as tools. From 9d80ad6e63c738c7cb053d9796753e92f5a074c8 Mon Sep 17 00:00:00 2001 From: s Date: Wed, 18 Feb 2026 23:44:25 -0800 Subject: [PATCH 117/140] docs: fix README API section links to correct docs/usage/ paths (#1297) All documentation lives under docs/usage/, not docs/api/. Fixed: - Modules, LCM, Blueprints, Configuration, Visualization links - Transports link (now points to docs/usage/transports/index.md) - Data Streams links (both in feature grid and API section) - ROS interop section transport link --- README.md | 20 ++++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/README.md b/README.md index e39446efc2..5b50d72cb1 100644 --- a/README.md +++ b/README.md @@ -55,7 +55,7 @@ Our goal is to provide an easy-to-install, modern framework for general robotics Agents - Sensor Integrations + Sensor Integrations @@ -64,7 +64,7 @@ Our goal is to provide an easy-to-install, modern framework for general robotics "hey Claude, go to the kitchen"
Watch video -

Sensor Integrations

+

Sensor Integrations

Livox Mid360, Zed @@ -170,13 +170,13 @@ dimos --replay run unitree-go2 ## API -- [Modules](docs/api/modules.md) -- [LCM](docs/api/lcm.md) -- [Blueprints](docs/api/blueprints.md) -- [Transports](docs/api/transports.md) -- [Data Streams](docs/api/data_streams/README.md) -- [Configuration](docs/api/configuration.md) -- [Visualization](docs/api/visualization.md) +- [Modules](docs/usage/modules.md) +- [LCM](docs/usage/lcm.md) +- [Blueprints](docs/usage/blueprints.md) +- [Transports](docs/usage/transports/index.md) +- [Data Streams](docs/usage/data_streams/README.md) +- [Configuration](docs/usage/configuration.md) +- [Visualization](docs/usage/visualization.md) ## Multi Language Support @@ -189,4 +189,4 @@ Check our language interop examples: ## ROS interop -For researchers, we can talk to ROS directly via [ROS Transports](docs/api/transports.md), or host dockerized ROS deployments as first-class DimOS modules, allowing you easy installation and portability +For researchers, we can talk to ROS directly via [ROS Transports](docs/usage/transports/index.md), or host dockerized ROS deployments as first-class DimOS modules, allowing you easy installation and portability From 067cd162df802019b86e624e3d7988107839f38d Mon Sep 17 00:00:00 2001 From: leshy Date: Thu, 19 Feb 2026 09:50:20 +0200 Subject: [PATCH 118/140] Update docs/installation/nix.md Co-authored-by: greptile-apps[bot] <165735046+greptile-apps[bot]@users.noreply.github.com> --- docs/installation/nix.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/installation/nix.md b/docs/installation/nix.md index fa4b8010ab..abf72b9348 100644 --- a/docs/installation/nix.md +++ b/docs/installation/nix.md @@ -41,7 +41,7 @@ mkdir myproject cd myproject uv venv --python "3.12" -source .env/bin/activate +source .venv/bin/activate # if on nixos you can pull our flake wget https://raw.githubusercontent.com/dimensionalOS/dimos/refs/heads/main/flake.nix From d8fd6a2d5d2d759b24e1ef0f93c93745249e9382 Mon Sep 17 00:00:00 2001 From: s Date: Wed, 18 Feb 2026 23:57:05 -0800 Subject: [PATCH 119/140] Fix virtual environment activation path in nix.md --- docs/installation/nix.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/installation/nix.md b/docs/installation/nix.md index abf72b9348..3b2906ad73 100644 --- a/docs/installation/nix.md +++ b/docs/installation/nix.md @@ -63,7 +63,7 @@ cd dimos # create venv uv venv --python 3.12 -source .env/bin/activate +source .venv/bin/activate uv sync --all-extras From e4b7f810ff5a8bd710a1497fc2e1bd6b3700fbf4 Mon Sep 17 00:00:00 2001 From: s Date: Wed, 18 Feb 2026 23:57:52 -0800 Subject: [PATCH 120/140] docs: fix all broken links in README (#1298) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - #hardware anchor → #platforms (matches actual heading) --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 5b50d72cb1..da47dd870e 100644 --- a/README.md +++ b/README.md @@ -71,7 +71,7 @@ Our goal is to provide an easy-to-install, modern framework for general robotics -# Platforms +# Hardware From f028d2aa1d5aea68ce076b8398a941e04aaf0e22 Mon Sep 17 00:00:00 2001 From: s Date: Thu, 19 Feb 2026 00:26:09 -0800 Subject: [PATCH 121/140] docs(readme): link drone and mavlink entries to dimos/robot/drone (#1299) --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index da47dd870e..2ddcfebac0 100644 --- a/README.md +++ b/README.md @@ -109,8 +109,8 @@ Our goal is to provide an easy-to-install, modern framework for general robotics 🟥 Piper
 @@ -102,11 +102,11 @@ Our goal is to provide an easy-to-install, modern framework for general robotics 🟩 Unitree Go2 pro/air
@@ -64,8 +64,8 @@ Our goal is to provide an easy-to-install, modern framework for general robotics "hey Robot, go find the kitchen"
Watch video
- 🟥 Mavlink
- 🟥 DJI SDK
+ 🟥 Mavlink
+ 🟥 DJI SDK
 🟥 Force Torque Sensor
From c47c0b305db5031c52ff3cc4d02229064c197d3e Mon Sep 17 00:00:00 2001 From: Ivan Nikolic Date: Thu, 19 Feb 2026 16:29:13 +0800 Subject: [PATCH 122/140] per os install instructions --- docs/installation/nix.md | 55 +++++++++++++++-------------- docs/installation/osx.md | 70 +++++++++++++++++++++++++++++++++++++ docs/installation/ubuntu.md | 69 +++++++++++++++++++++++++++++++++++- 3 files changed, 167 insertions(+), 27 deletions(-) diff --git a/docs/installation/nix.md b/docs/installation/nix.md index fa4b8010ab..51be0fc412 100644 --- a/docs/installation/nix.md +++ b/docs/installation/nix.md @@ -1,6 +1,5 @@ -# System Dependancies Install +# Nix install (required for nix managed dimos) -## Nix install (all linux) You need to have [nix](https://nixos.org/) installed and [flakes](https://nixos.wiki/wiki/Flakes) enabled, [official install docs](https://nixos.org/download/) recomended, but here is a quickstart: @@ -14,39 +13,39 @@ curl --proto '=https' --tlsv1.2 -sSf -L https://install.determinate.systems/nix mkdir -p "$HOME/.config/nix"; echo "experimental-features = nix-command flakes" >> "$HOME/.config/nix/nix.conf" ``` -## Ubuntu 22.04 or 24.04 -```sh -sudo apt-get update -sudo apt-get install -y curl g++ portaudio19-dev git-lfs libturbojpeg python3-dev pre-commit +# Install Direnv (optional) -# install uv -curl -LsSf https://astral.sh/uv/install.sh | sh && export PATH="$HOME/.local/bin:$PATH" -``` +[direnv](https://direnv.net) is a convinient helper that allows you to automatically enter your nix and python env once you cd into the project dir. -## macOS 12.6 or newer -```sh -# install homebrew -/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)" -# install dependencies -brew install gnu-sed gcc portaudio git-lfs libjpeg-turbo python pre-commit +You can skip this step if you intend to type `nix develop` by hand -# install uv -curl -LsSf https://astral.sh/uv/install.sh | sh && export PATH="$HOME/.local/bin:$PATH" +Following [direnv install docs](https://direnv.net/docs/installation.html) is recommended (many distros have native package support) + +but a quick oneliner binary install is +```sh +curl -sfL https://direnv.net/install.sh | bash ``` -# DimOS as a library +# Using DimOS as a library ```sh mkdir myproject cd myproject -uv venv --python "3.12" -source .env/bin/activate - -# if on nixos you can pull our flake +# pull our nix flake wget https://raw.githubusercontent.com/dimensionalOS/dimos/refs/heads/main/flake.nix wget https://raw.githubusercontent.com/dimensionalOS/dimos/refs/heads/main/flake.lock +# if using direnv (recommended) +wget https://raw.githubusercontent.com/dimensionalOS/dimos/refs/heads/main/.envrc.nix -o .envrc +direnv allow + +# if using nix develop directly instead of direnv, +# nix develop + +uv venv --python "3.12" +source .venv/bin/activate + # this will just pull everything (big checkout) # depending on what you are working on you might not need everything, # check your respectative platform guides @@ -54,12 +53,20 @@ uv pip install dimos[misc,sim,visualization,agents,web,perception,unitree,manipu ``` # Developing on DimOS + ```sh # this allows getting large files on-demand (and not pulling all immediately) export GIT_LFS_SKIP_SMUDGE=1 git clone -b dev https://github.com/dimensionalOS/dimos.git cd dimos +# if using direnv (recommended) +cp .envrc.nix .envrc +direnv allow + +# if using nix develop directly instead of direnv, +# nix develop + # create venv uv venv --python 3.12 @@ -73,7 +80,3 @@ uv run mypy dimos # tests (around a minute to run) uv run pytest dimos ``` - -# direnv - -[Direnv](https://direnv.net/) is super convinient for auto-entering your nix env of uv venv diff --git a/docs/installation/osx.md b/docs/installation/osx.md index 4ead4ccec5..bc4c4cef52 100644 --- a/docs/installation/osx.md +++ b/docs/installation/osx.md @@ -1 +1,71 @@ # osx install + +## macOS 12.6 or newer +```sh +# install homebrew +/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)" +# install dependencies +brew install gnu-sed gcc portaudio git-lfs libjpeg-turbo python pre-commit + +# install uv +curl -LsSf https://astral.sh/uv/install.sh | sh && export PATH="$HOME/.local/bin:$PATH" +``` + +# Install Direnv (optional) + +[direnv](https://direnv.net) is a convinient helper that allows you to automatically enter your nix and python env once you cd into the project dir. + +You can skip this step if you intend to type `nix develop` by hand + +Following [direnv install docs](https://direnv.net/docs/installation.html) is recommended (many distros have native package support) + +but a quick oneliner binary install is +```sh +curl -sfL https://direnv.net/install.sh | bash +``` + +# Using DimOS as a library + +```sh +mkdir myproject +cd myproject + +uv venv --python "3.12" + +# if using direnv (recommended) +wget https://raw.githubusercontent.com/dimensionalOS/dimos/refs/heads/main/.envrc.venv -o .envrc +direnv allow +# if not using direnv +# source .env/bin/activate + +# this will just pull everything (big checkout) +# depending on what you are working on you might not need everything, +# check your respectative platform guides +uv pip install dimos[misc,sim,visualization,agents,web,perception,unitree,manipulation,cpu,dev] +``` + +# Developing on DimOS + +```sh +# this allows getting large files on-demand (and not pulling all immediately) +export GIT_LFS_SKIP_SMUDGE=1 +git clone -b dev https://github.com/dimensionalOS/dimos.git +cd dimos + +# create venv +uv venv --python 3.12 + +# if using direnv (recommended) +direnv allow + +# if not using direnv +# source .env/bin/activate + +uv sync --all-extras + +# type check +uv run mypy dimos + +# tests (around a minute to run) +uv run pytest dimos +``` diff --git a/docs/installation/ubuntu.md b/docs/installation/ubuntu.md index 2d64abe69c..ede577d86a 100644 --- a/docs/installation/ubuntu.md +++ b/docs/installation/ubuntu.md @@ -1 +1,68 @@ -# Ubuntu install +# System Dependancies Install (Ubuntu 22.04 or 24.04) + +```sh +sudo apt-get update +sudo apt-get install -y curl g++ portaudio19-dev git-lfs libturbojpeg python3-dev pre-commit + +# install uv +curl -LsSf https://astral.sh/uv/install.sh | sh && export PATH="$HOME/.local/bin:$PATH" +``` + +# Install Direnv (optional) + +[direnv](https://direnv.net) is a convinient helper that allows you to automatically enter your python env once you cd into the project dir. + +You can skip this step if you intend to type `nix develop` by hand + +Following [direnv install docs](https://direnv.net/docs/installation.html) is recommended (many distros have native package support) + +but a quick oneliner binary install is +```sh +curl -sfL https://direnv.net/install.sh | bash +``` + +# Using DimOS as a library + +```sh +mkdir myproject +cd myproject + +uv venv --python "3.12" + +# if using direnv (recommended) +wget https://raw.githubusercontent.com/dimensionalOS/dimos/refs/heads/main/.envrc.venv -o .envrc +direnv allow +# if not using direnv +# source .env/bin/activate + +# this will just pull everything (big checkout) +# depending on what you are working on you might not need everything, +# check your respectative platform guides +uv pip install dimos[misc,sim,visualization,agents,web,perception,unitree,manipulation,cpu,dev] +``` + +# Developing on DimOS + +```sh +# this allows getting large files on-demand (and not pulling all immediately) +export GIT_LFS_SKIP_SMUDGE=1 +git clone -b dev https://github.com/dimensionalOS/dimos.git +cd dimos + +# create venv +uv venv --python 3.12 + +# if using direnv (recommended) +direnv allow + +# if not using direnv +# source .env/bin/activate + +uv sync --all-extras + +# type check +uv run mypy dimos + +# tests (around a minute to run) +uv run pytest dimos +``` From 8d19348b2889105f971f7500ce21b4f3d1e5c2cc Mon Sep 17 00:00:00 2001 From: s Date: Thu, 19 Feb 2026 00:35:09 -0800 Subject: [PATCH 123/140] Update video links and text in README --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 2ddcfebac0..97ef549557 100644 --- a/README.md +++ b/README.md @@ -43,7 +43,7 @@ Our goal is to provide an easy-to-install, modern framework for general robotics

Navigation and Mapping

- ros and non ros
Watch video + ros and non ros
Watch video

Perception

@@ -61,7 +61,7 @@ Our goal is to provide an easy-to-install, modern framework for general robotics

Agentic Control, MCP

- "hey Claude, go to the kitchen"
Watch video + "hey Robot, go find the kitchen"
Watch video

Sensor Integrations

From e72a3b606f2452d1512bb285c0a071138ba21a57 Mon Sep 17 00:00:00 2001 From: Ivan Nikolic Date: Thu, 19 Feb 2026 16:38:40 +0800 Subject: [PATCH 124/140] main readme install update --- README.md | 17 ++++++++++------- 1 file changed, 10 insertions(+), 7 deletions(-) diff --git a/README.md b/README.md index 2ddcfebac0..6c9b2b1e11 100644 --- a/README.md +++ b/README.md @@ -145,20 +145,23 @@ Check the [hardware section](#hardware) above to choose the right `extras` and ` **Use DimOS as a library / UI** ```bash -pip install dimos[your_platform] +uv pip install dimos[your_hardware_platform] dimos run your_platform_blueprint ``` **Develop DimOS** -```bash -git clone https://github.com/dimensionalOS/dimos/ dimos +```sh +export GIT_LFS_SKIP_SMUDGE=1 +git clone -b dev https://github.com/dimensionalOS/dimos.git cd dimos -uv venv -p 3.12 -source .venv/bin/activate + +uv venv --python 3.12 +source .env/bin/activate + uv sync --all-extras -mypy dimos -pytest dimos + +# Play a recording of unitree go2 run dimos --replay run unitree-go2 ``` From a357721502ee31a08ed16315003e80fe82fb4049 Mon Sep 17 00:00:00 2001 From: Ivan Nikolic Date: Thu, 19 Feb 2026 16:42:23 +0800 Subject: [PATCH 125/140] typos/small fixes for install --- docs/installation/nix.md | 15 ++++++--------- docs/installation/osx.md | 14 +++++++------- docs/installation/ubuntu.md | 16 ++++++++-------- 3 files changed, 21 insertions(+), 24 deletions(-) diff --git a/docs/installation/nix.md b/docs/installation/nix.md index 2798f08f08..f0e1d03089 100644 --- a/docs/installation/nix.md +++ b/docs/installation/nix.md @@ -2,7 +2,7 @@ You need to have [nix](https://nixos.org/) installed and [flakes](https://nixos.wiki/wiki/Flakes) enabled, -[official install docs](https://nixos.org/download/) recomended, but here is a quickstart: +[official install docs](https://nixos.org/download/) recommended, but here is a quickstart: ```sh # Install Nix https://nixos.org/download/ @@ -15,11 +15,11 @@ mkdir -p "$HOME/.config/nix"; echo "experimental-features = nix-command flakes" # Install Direnv (optional) -[direnv](https://direnv.net) is a convinient helper that allows you to automatically enter your nix and python env once you cd into the project dir. +[direnv](https://direnv.net) is a convenient helper that allows you to automatically enter your nix and python env once you cd into the project dir. -You can skip this step if you intend to type `nix develop` by hand +You can skip this step if you intend to type `nix develop` by hand. -Following [direnv install docs](https://direnv.net/docs/installation.html) is recommended (many distros have native package support) +Following [direnv install docs](https://direnv.net/docs/installation.html) is recommended (many distros have native package support) but a quick oneliner binary install is ```sh @@ -32,15 +32,12 @@ curl -sfL https://direnv.net/install.sh | bash mkdir myproject cd myproject -uv venv --python "3.12" -source .venv/bin/activate - # if on nixos you can pull our flake wget https://raw.githubusercontent.com/dimensionalOS/dimos/refs/heads/main/flake.nix wget https://raw.githubusercontent.com/dimensionalOS/dimos/refs/heads/main/flake.lock # if using direnv (recommended) -wget https://raw.githubusercontent.com/dimensionalOS/dimos/refs/heads/main/.envrc.nix -o .envrc +wget https://raw.githubusercontent.com/dimensionalOS/dimos/refs/heads/main/.envrc.nix -O .envrc direnv allow # if using nix develop directly instead of direnv, @@ -51,7 +48,7 @@ source .venv/bin/activate # this will just pull everything (big checkout) # depending on what you are working on you might not need everything, -# check your respectative platform guides +# check your respective platform guides uv pip install dimos[misc,sim,visualization,agents,web,perception,unitree,manipulation,cpu,dev] ``` diff --git a/docs/installation/osx.md b/docs/installation/osx.md index bc4c4cef52..7555c178f2 100644 --- a/docs/installation/osx.md +++ b/docs/installation/osx.md @@ -13,11 +13,11 @@ curl -LsSf https://astral.sh/uv/install.sh | sh && export PATH="$HOME/.local/bin # Install Direnv (optional) -[direnv](https://direnv.net) is a convinient helper that allows you to automatically enter your nix and python env once you cd into the project dir. +[direnv](https://direnv.net) is a convenient helper that allows you to automatically enter your python env once you cd into the project dir. -You can skip this step if you intend to type `nix develop` by hand +You can skip this step if you intend to activate manually. -Following [direnv install docs](https://direnv.net/docs/installation.html) is recommended (many distros have native package support) +Following [direnv install docs](https://direnv.net/docs/installation.html) is recommended (many distros have native package support) but a quick oneliner binary install is ```sh @@ -33,14 +33,14 @@ cd myproject uv venv --python "3.12" # if using direnv (recommended) -wget https://raw.githubusercontent.com/dimensionalOS/dimos/refs/heads/main/.envrc.venv -o .envrc +wget https://raw.githubusercontent.com/dimensionalOS/dimos/refs/heads/main/.envrc.venv -O .envrc direnv allow # if not using direnv -# source .env/bin/activate +# source .venv/bin/activate # this will just pull everything (big checkout) # depending on what you are working on you might not need everything, -# check your respectative platform guides +# check your respective platform guides uv pip install dimos[misc,sim,visualization,agents,web,perception,unitree,manipulation,cpu,dev] ``` @@ -59,7 +59,7 @@ uv venv --python 3.12 direnv allow # if not using direnv -# source .env/bin/activate +# source .venv/bin/activate uv sync --all-extras diff --git a/docs/installation/ubuntu.md b/docs/installation/ubuntu.md index ede577d86a..af4a8b8d07 100644 --- a/docs/installation/ubuntu.md +++ b/docs/installation/ubuntu.md @@ -1,4 +1,4 @@ -# System Dependancies Install (Ubuntu 22.04 or 24.04) +# System Dependencies Install (Ubuntu 22.04 or 24.04) ```sh sudo apt-get update @@ -10,11 +10,11 @@ curl -LsSf https://astral.sh/uv/install.sh | sh && export PATH="$HOME/.local/bin # Install Direnv (optional) -[direnv](https://direnv.net) is a convinient helper that allows you to automatically enter your python env once you cd into the project dir. +[direnv](https://direnv.net) is a convenient helper that allows you to automatically enter your python env once you cd into the project dir. -You can skip this step if you intend to type `nix develop` by hand +You can skip this step if you intend to activate manually. -Following [direnv install docs](https://direnv.net/docs/installation.html) is recommended (many distros have native package support) +Following [direnv install docs](https://direnv.net/docs/installation.html) is recommended (many distros have native package support) but a quick oneliner binary install is ```sh @@ -30,14 +30,14 @@ cd myproject uv venv --python "3.12" # if using direnv (recommended) -wget https://raw.githubusercontent.com/dimensionalOS/dimos/refs/heads/main/.envrc.venv -o .envrc +wget https://raw.githubusercontent.com/dimensionalOS/dimos/refs/heads/main/.envrc.venv -O .envrc direnv allow # if not using direnv -# source .env/bin/activate +# source .venv/bin/activate # this will just pull everything (big checkout) # depending on what you are working on you might not need everything, -# check your respectative platform guides +# check your respective platform guides uv pip install dimos[misc,sim,visualization,agents,web,perception,unitree,manipulation,cpu,dev] ``` @@ -56,7 +56,7 @@ uv venv --python 3.12 direnv allow # if not using direnv -# source .env/bin/activate +# source .venv/bin/activate uv sync --all-extras From d49a6a0957d34595ca34e4f5caa8eb974af6b4a1 Mon Sep 17 00:00:00 2001 From: Ivan Nikolic Date: Thu, 19 Feb 2026 16:45:54 +0800 Subject: [PATCH 126/140] typos, small fixes for main readme --- README.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/README.md b/README.md index 6c9b2b1e11..edc3068eab 100644 --- a/README.md +++ b/README.md @@ -43,11 +43,11 @@ Our goal is to provide an easy-to-install, modern framework for general robotics

Navigation and Mapping

- ros and non ros
Watch video + ROS and Native
Watch video

Perception

- bla bla perception
Watch video + Detectors, 3d projections, VLMs, Audio processing
Watch video
- 🟥 Unitree G1
+ 🟥 Unitree G1
 - 🟥 Xarm
- 🟥 Piper
+ 🟥 Xarm
+ 🟥 Piper
 🟥 Mavlink
@@ -132,7 +132,7 @@ Our goal is to provide an easy-to-install, modern framework for general robotics To set up your system dependencies, follow one of these guides: - 🟩 [NixOS / General Linux](docs/installation/nix.md) -- 🟥 [macOS](docs/installation/osx.md) +- 🟧 [macOS](docs/installation/osx.md) - 🟩 [Ubuntu 24.04](docs/installation/ubuntu.md) - 🟨 [Docker](docs/installation/docker.md) @@ -157,7 +157,7 @@ git clone -b dev https://github.com/dimensionalOS/dimos.git cd dimos uv venv --python 3.12 -source .env/bin/activate +source .venv/bin/activate uv sync --all-extras From 56e412476db6234a93f046ce9fde5649f2ed8167 Mon Sep 17 00:00:00 2001 From: s Date: Thu, 19 Feb 2026 02:31:47 -0800 Subject: [PATCH 127/140] Update installation instructions and remove guide link Removed outdated hardware integration guide link and updated Ubuntu version in installation instructions. --- README.md | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/README.md b/README.md index ce0070ed0a..93713456bd 100644 --- a/README.md +++ b/README.md @@ -123,8 +123,6 @@ Our goal is to provide an easy-to-install, modern framework for general robotics -[New Hardware Integration Guide](docs/hardware/integration_guide.md) - # Installation ### Step 1: System Install @@ -133,7 +131,7 @@ To set up your system dependencies, follow one of these guides: - 🟩 [NixOS / General Linux](docs/installation/nix.md) - 🟧 [macOS](docs/installation/osx.md) -- 🟩 [Ubuntu 24.04](docs/installation/ubuntu.md) +- 🟩 [Ubuntu 22.04 / 24.04](docs/installation/ubuntu.md) - 🟨 [Docker](docs/installation/docker.md) ### Step 2: Python Install From ae8057e450ad3b84e088b33507a7b527b7b10e7e Mon Sep 17 00:00:00 2001 From: stash Date: Thu, 19 Feb 2026 03:28:39 -0800 Subject: [PATCH 128/140] Added new gifs, spatial memory --- README.md | 8 ++++---- assets/readme/agentic_control.gif | 3 +++ assets/readme/spatial_memory.gif | 3 +++ 3 files changed, 10 insertions(+), 4 deletions(-) create mode 100644 assets/readme/agentic_control.gif create mode 100644 assets/readme/spatial_memory.gif diff --git a/README.md b/README.md index 93713456bd..bbc1a2d24e 100644 --- a/README.md +++ b/README.md @@ -52,10 +52,10 @@ Our goal is to provide an easy-to-install, modern framework for general robotics
- Agents + Agents - Sensor Integrations + Spatial Memory
-

Sensor Integrations

- Livox Mid360, Zed +

Spatial Memory

+ Spatio-temporal RAG, Dynamic memory, Object localization and permanence
Watch video
diff --git a/assets/readme/agentic_control.gif b/assets/readme/agentic_control.gif new file mode 100644 index 0000000000..92793fbc5c --- /dev/null +++ b/assets/readme/agentic_control.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:1772440c8af78805e3ae774d8cc86e5d1efe67071abd5584c82cfe09d952cfe8 +size 2409350 diff --git a/assets/readme/spatial_memory.gif b/assets/readme/spatial_memory.gif new file mode 100644 index 0000000000..93d8f654a6 --- /dev/null +++ b/assets/readme/spatial_memory.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:b853f5faf40bcf9784c624c31faef52423150c6beadd2c30169d5376f9116eaa +size 4727168 From ba43126016f4a8ea3a4c3b873c86ddaa1b0fa654 Mon Sep 17 00:00:00 2001 From: stash Date: Thu, 19 Feb 2026 04:01:03 -0800 Subject: [PATCH 129/140] updated gifs --- assets/readme/agentic_control.gif | 4 ++-- assets/readme/spatial_memory.gif | 4 ++-- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/assets/readme/agentic_control.gif b/assets/readme/agentic_control.gif index 92793fbc5c..f9f5970441 100644 --- a/assets/readme/agentic_control.gif +++ b/assets/readme/agentic_control.gif @@ -1,3 +1,3 @@ version https://git-lfs.github.com/spec/v1 -oid sha256:1772440c8af78805e3ae774d8cc86e5d1efe67071abd5584c82cfe09d952cfe8 -size 2409350 +oid sha256:eb0411de5e5967be8773d5d95e692a6a5859f75bb400164451a3b383b1025fb4 +size 2416274 diff --git a/assets/readme/spatial_memory.gif b/assets/readme/spatial_memory.gif index 93d8f654a6..070c65270b 100644 --- a/assets/readme/spatial_memory.gif +++ b/assets/readme/spatial_memory.gif @@ -1,3 +1,3 @@ version https://git-lfs.github.com/spec/v1 -oid sha256:b853f5faf40bcf9784c624c31faef52423150c6beadd2c30169d5376f9116eaa -size 4727168 +oid sha256:50b9cb7898ae8d238a088252fd96d2278a1be96a0dbb761839bc58c99c17f7a7 +size 4655580 From b05f71450e3c4e4e5f9beb0bc7b57979f0f6fa0d Mon Sep 17 00:00:00 2001 From: s Date: Thu, 19 Feb 2026 04:52:49 -0800 Subject: [PATCH 130/140] docs(readme): nav description, quickstart with real examples, remove dead perception link (#1301) * docs(readme): nav description, quickstart with real examples, remove dead perception link * fix: revert perception description, only remove dead video link --- README.md | 37 ++++++++++++++++++++++++++++++------- 1 file changed, 30 insertions(+), 7 deletions(-) diff --git a/README.md b/README.md index bbc1a2d24e..c239b34976 100644 --- a/README.md +++ b/README.md @@ -43,11 +43,11 @@ Our goal is to provide an easy-to-install, modern framework for general robotics

Navigation and Mapping

- ROS and Native
Watch video + SLAM, dynamic obstacle avoidance, route planning, and autonomous exploration — supported on native DimOS and ROS
Watch video

Perception

- Detectors, 3d projections, VLMs, Audio processing
Watch video + Detectors, 3d projections, VLMs, Audio processing @@ -140,11 +140,34 @@ Now install the Python package. Check the [hardware section](#hardware) above to choose the right `extras` and `blueprint` for your platform. -**Use DimOS as a library / UI** +**Quickstart** ```bash -uv pip install dimos[your_hardware_platform] -dimos run your_platform_blueprint +# Install with Unitree support +uv pip install dimos[base,unitree] + +# Replay a recorded Go2 session (no hardware needed) +# NOTE: First run will show a black rerun window while ~2.4 GB downloads from LFS +dimos --replay run unitree-go2 +``` + +```bash +# Install with simulation support +uv pip install dimos[base,unitree,sim] + +# Run Go2 in MuJoCo simulation +export DISPLAY=:1 # Or DISPLAY=:0 if getting GLFW/OpenGL X11 errors +# ignore the warp warnings +dimos --simulation run unitree-go2 + +# Run G1 humanoid in simulation +dimos --simulation run unitree-g1-sim +``` + +```bash +# Control a real robot (Unitree Go2 over WebRTC) +export ROBOT_IP= +dimos run unitree-go2 ``` **Develop DimOS** @@ -159,8 +182,8 @@ source .venv/bin/activate uv sync --all-extras -# Play a recording of unitree go2 run -dimos --replay run unitree-go2 +# Run in simulation +dimos --simulation run unitree-g1-sim ``` ### Step 3 - Profit From 611114fda941501e85d358d0a479e7789aa9982b Mon Sep 17 00:00:00 2001 From: s Date: Thu, 19 Feb 2026 04:59:41 -0800 Subject: [PATCH 131/140] Revise Python installation and development instructions Updated installation instructions and quickstart section for clarity and added emphasis on development. --- README.md | 16 +++++----------- 1 file changed, 5 insertions(+), 11 deletions(-) diff --git a/README.md b/README.md index c239b34976..f192ad70ef 100644 --- a/README.md +++ b/README.md @@ -134,16 +134,11 @@ To set up your system dependencies, follow one of these guides: - 🟩 [Ubuntu 22.04 / 24.04](docs/installation/ubuntu.md) - 🟨 [Docker](docs/installation/docker.md) -### Step 2: Python Install +### Step 2: Python Library & Editable Installs -Now install the Python package. - -Check the [hardware section](#hardware) above to choose the right `extras` and `blueprint` for your platform. - -**Quickstart** +**DimOS Quickstart** ```bash -# Install with Unitree support uv pip install dimos[base,unitree] # Replay a recorded Go2 session (no hardware needed) @@ -157,7 +152,6 @@ uv pip install dimos[base,unitree,sim] # Run Go2 in MuJoCo simulation export DISPLAY=:1 # Or DISPLAY=:0 if getting GLFW/OpenGL X11 errors -# ignore the warp warnings dimos --simulation run unitree-go2 # Run G1 humanoid in simulation @@ -170,7 +164,7 @@ export ROBOT_IP= dimos run unitree-go2 ``` -**Develop DimOS** +**Develop on DimOS** ```sh export GIT_LFS_SKIP_SMUDGE=1 @@ -182,8 +176,8 @@ source .venv/bin/activate uv sync --all-extras -# Run in simulation -dimos --simulation run unitree-g1-sim +# Run full test suite +pytest -s dimos/ ``` ### Step 3 - Profit From febaee0118820547f3baeca5fc61d1cf5f30301e Mon Sep 17 00:00:00 2001 From: stash Date: Thu, 19 Feb 2026 05:13:56 -0800 Subject: [PATCH 132/140] readme changes --- README.md | 13 ++++++------- 1 file changed, 6 insertions(+), 7 deletions(-) diff --git a/README.md b/README.md index f192ad70ef..d5957525ad 100644 --- a/README.md +++ b/README.md @@ -125,18 +125,17 @@ Our goal is to provide an easy-to-install, modern framework for general robotics # Installation -### Step 1: System Install +## Step 1: System Install To set up your system dependencies, follow one of these guides: +- 🟩 [Ubuntu 22.04 / 24.04](docs/installation/ubuntu.md) - 🟩 [NixOS / General Linux](docs/installation/nix.md) - 🟧 [macOS](docs/installation/osx.md) -- 🟩 [Ubuntu 22.04 / 24.04](docs/installation/ubuntu.md) -- 🟨 [Docker](docs/installation/docker.md) -### Step 2: Python Library & Editable Installs +## Step 2: Python Installs -**DimOS Quickstart** +### Quickstart ```bash uv pip install dimos[base,unitree] @@ -164,7 +163,7 @@ export ROBOT_IP= dimos run unitree-go2 ``` -**Develop on DimOS** +### Develop on DimOS ```sh export GIT_LFS_SKIP_SMUDGE=1 @@ -177,7 +176,7 @@ source .venv/bin/activate uv sync --all-extras # Run full test suite -pytest -s dimos/ +uv run pytest dimos ``` ### Step 3 - Profit From 18582e04f6eccbb0a8404d914008b5aaebaf1505 Mon Sep 17 00:00:00 2001 From: s Date: Thu, 19 Feb 2026 05:38:54 -0800 Subject: [PATCH 133/140] Revise README title and introduction for clarity Updated the title and description to reflect the agentive nature of the operating system. --- README.md | 10 ++++++++-- 1 file changed, 8 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index d5957525ad..6d7484ff41 100644 --- a/README.md +++ b/README.md @@ -4,7 +4,7 @@ ![Dimensional](assets/dimensional-dark.svg#gh-dark-mode-only) ![Dimensional](assets/dimensional-light.svg#gh-light-mode-only) -

Operating System for Generalist Robotics

+

The Agentive Operating System for Generalist Robotics

[![Discord](https://img.shields.io/discord/1341146487186391173?style=flat-square&logo=discord&logoColor=white&label=Discord&color=5865F2)](https://discord.gg/dimos) [![Stars](https://img.shields.io/github/stars/dimensionalOS/dimos?style=flat-square)](https://github.com/dimensionalOS/dimos/stargazers) @@ -23,13 +23,19 @@ [Multi Language](#multi-language-support) • [ROS](#ros-interop) +> \[!NOTE] +> +> ⚠️ **Alpha Pre-Release: Expect Breaking Changes** ⚠️ +
# Intro -Our goal is to provide an easy-to-install, modern framework for general robotics. You should be up and running in minutes. +Dimensional is the modern framework and agentive operating system for generalist robotics. + +With a simple install and no ROS required, design, build, and run physical applications on any humanoid, quadruped, drone, or wheeled embodiment entirely in python. From 59363fb1b4939335f7a4248088d936f34eefbacd Mon Sep 17 00:00:00 2001 From: s Date: Thu, 19 Feb 2026 05:40:28 -0800 Subject: [PATCH 134/140] Readme updates --- README.md | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/README.md b/README.md index 6d7484ff41..64cb055cf6 100644 --- a/README.md +++ b/README.md @@ -23,9 +23,7 @@ [Multi Language](#multi-language-support) • [ROS](#ros-interop) -> \[!NOTE] -> -> ⚠️ **Alpha Pre-Release: Expect Breaking Changes** ⚠️ +⚠️ **Alpha Pre-Release: Expect Breaking Changes** ⚠️ From baf236f3aff4a90abd64eabc203516c85467422e Mon Sep 17 00:00:00 2001 From: s Date: Thu, 19 Feb 2026 05:42:40 -0800 Subject: [PATCH 135/140] Update README.md --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 64cb055cf6..72613227cd 100644 --- a/README.md +++ b/README.md @@ -47,7 +47,7 @@ With a simple install and no ROS required, design, build, and run physical appli

Navigation and Mapping

- SLAM, dynamic obstacle avoidance, route planning, and autonomous exploration — supported on native DimOS and ROS
Watch video + SLAM, dynamic obstacle avoidance, route planning, and autonomous exploration — via both DimOS native and ROS
Watch video

Perception

From a0046012809eb055590f08b9e0d207dcc13f6cbc Mon Sep 17 00:00:00 2001 From: s Date: Thu, 19 Feb 2026 05:55:01 -0800 Subject: [PATCH 136/140] Readme updates --- README.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 72613227cd..e5e68a85ce 100644 --- a/README.md +++ b/README.md @@ -31,10 +31,11 @@ # Intro -Dimensional is the modern framework and agentive operating system for generalist robotics. +Dimensional is the modern framework and agentive operating system for generalist robotics. We are setting the next-generation SDK standard, integrating with the majority of robot manufacturers. -With a simple install and no ROS required, design, build, and run physical applications on any humanoid, quadruped, drone, or wheeled embodiment entirely in python. +With a simple install and no ROS required, build physical applications entirely in python that runs on any humanoid, quadruped, or drone. +Dimensional is agent native -- "vibecode" your robots in natural language and build (local & hosted) multi-agent systems that work seamlessly with your hardware, able to subscribe to lidar, cameras, spatial memory, and more.
@@ -110,7 +111,7 @@ With a simple install and no ROS required, design, build, and run physical appli 🟥 Xarm
- 🟥 Piper
+ 🟥 AgileX Piper
 🟥 Mavlink
From c13606808b22cccf9e2736faaa6d9eea05eb6528 Mon Sep 17 00:00:00 2001 From: s Date: Thu, 19 Feb 2026 06:34:37 -0800 Subject: [PATCH 137/140] Readme updates --- README.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index e5e68a85ce..071ba991f8 100644 --- a/README.md +++ b/README.md @@ -31,11 +31,11 @@ # Intro -Dimensional is the modern framework and agentive operating system for generalist robotics. We are setting the next-generation SDK standard, integrating with the majority of robot manufacturers. +Dimensional is the modern operating system for generalist robotics. We are setting the next-generation SDK standard, integrating with the majority of robot manufacturers. -With a simple install and no ROS required, build physical applications entirely in python that runs on any humanoid, quadruped, or drone. +With a simple install and no ROS required, build physical applications entirely in python that run on any humanoid, quadruped, or drone. -Dimensional is agent native -- "vibecode" your robots in natural language and build (local & hosted) multi-agent systems that work seamlessly with your hardware, able to subscribe to lidar, cameras, spatial memory, and more. +Dimensional is agent native -- "vibecode" your robots in natural language and build (local & hosted) multi-agent systems that work seamlessly with your hardware. Agents run as native modules — subscribing to any embedded stream, from perception (lidar, camera) and spatial memory down to control loops and motor drivers.
@@ -65,7 +65,7 @@ Dimensional is agent native -- "vibecode" your robots in natural language and bu
-

Agentic Control, MCP

+

Agentive Control, MCP

"hey Robot, go find the kitchen"
Watch video 		From 46fd43981a1397d4c2faa92ed8d6fcbd84239022 Mon Sep 17 00:00:00 2001 From: spomichter <12108168+spomichter@users.noreply.github.com> Date: Thu, 19 Feb 2026 14:35:43 +0000 Subject: [PATCH 138/140] CI code cleanup --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 071ba991f8..0d1c91f5d4 100644 --- a/README.md +++ b/README.md @@ -35,7 +35,7 @@ Dimensional is the modern operating system for generalist robotics. We are setti With a simple install and no ROS required, build physical applications entirely in python that run on any humanoid, quadruped, or drone. -Dimensional is agent native -- "vibecode" your robots in natural language and build (local & hosted) multi-agent systems that work seamlessly with your hardware. Agents run as native modules — subscribing to any embedded stream, from perception (lidar, camera) and spatial memory down to control loops and motor drivers. +Dimensional is agent native -- "vibecode" your robots in natural language and build (local & hosted) multi-agent systems that work seamlessly with your hardware. Agents run as native modules — subscribing to any embedded stream, from perception (lidar, camera) and spatial memory down to control loops and motor drivers.
From a455e0c9f3a3b1131781ca8a0dc3cb5f0b30ccf5 Mon Sep 17 00:00:00 2001 From: s Date: Thu, 19 Feb 2026 06:42:08 -0800 Subject: [PATCH 139/140] docs(readme): add Unitree B1 to quadruped hardware table (#1302) --- README.md | 1 + 1 file changed, 1 insertion(+) diff --git a/README.md b/README.md index 0d1c91f5d4..3f0d25949b 100644 --- a/README.md +++ b/README.md @@ -105,6 +105,7 @@ Dimensional is agent native -- "vibecode" your robots in natural language and bu
🟩 Unitree Go2 pro/air
+ 🟥 Unitree B1
 🟥 Unitree G1
From f5250d8564535e518dc059e45b6507e478e4fdb2 Mon Sep 17 00:00:00 2001 From: s Date: Thu, 19 Feb 2026 06:50:40 -0800 Subject: [PATCH 140/140] =?UTF-8?q?docs(transports):=20fix=20broken=20imag?= =?UTF-8?q?e=20paths=20=E2=80=94=20assets/=20=E2=86=92=20../assets/=20(#13?= =?UTF-8?q?03)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/usage/transports/index.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/usage/transports/index.md b/docs/usage/transports/index.md index 4c80776531..748cf03aa1 100644 --- a/docs/usage/transports/index.md +++ b/docs/usage/transports/index.md @@ -9,7 +9,7 @@ Transports connect **module streams** across **process boundaries** and/or **net Each edge in the graph is a **transported stream** (potentially different protocols). Each node is a **module**: -![go2_nav](assets/go2_nav.svg) +![go2_nav](../assets/go2_nav.svg) ## What the transport layer guarantees (and what it doesn’t) @@ -37,7 +37,7 @@ Quick view on performance of our pubsub backends: python -m pytest -svm tool -k "not bytes" dimos/protocol/pubsub/benchmark/test_benchmark.py ``` -![Benchmark results](assets/pubsub_benchmark.png) +![Benchmark results](../assets/pubsub_benchmark.png) --- @@ -45,7 +45,7 @@ python -m pytest -svm tool -k "not bytes" dimos/protocol/pubsub/benchmark/test_b
Pikchr -```pikchr output=assets/abstraction_layers.svg fold +```pikchr output=../assets/abstraction_layers.svg fold color = white fill = none linewid = 0.5in @@ -71,7 +71,7 @@ text "pub/sub API" at P.s + (0, -0.2in)
-![output](assets/abstraction_layers.svg) +![output](../assets/abstraction_layers.svg) We’ll go through these layers top-down. @@ -168,7 +168,7 @@ See [Modules](modules.md) for more on module architecture. `lcmspy` shows topic frequency/bandwidth stats: -![lcmspy](assets/lcmspy.png) +![lcmspy](../assets/lcmspy.png) `dimos topic echo /topic` listens on typed channels like `/topic#pkg.Msg` and decodes automatically: