hardware-fork · Juliaj · Mar 1, 2026 · Feb 27, 2026
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -27,8 +27,5 @@ jobs:
       - name: Demo unit tests
         run: pixi run test-demo
 
-      - name: Demo AHSimulation (mj_mink) unit tests
-        run: pixi run test-demo-mj-mink
-
       - name: AHControl (Rust) unit tests
         run: pixi run test-ahcontrol
diff --git a/Demo/README.md b/Demo/README.md
@@ -2,9 +2,9 @@
 
 ## Running with pixi
 
-Prerequisites: install [Pixi](https://pixi.prefix.dev/latest/installation/). Rust is needed for real hardware demos (AHControl).
+Prerequisites: install [Pixi](https://pixi.prefix.dev/latest/installation/). Rust is needed for real hardware demos (AHControl). Before running real hardware demos, check the serial port in the dataflow YAML: the default is Linux (`/dev/ttyACM0`); on Windows use your COM port (e.g. `COM3`).
 
-From the AmazingHand repository root:
+From the AmazingHand repository root (Git Bash on Windows, or a Unix shell on Linux/macOS):
 
 ```bash
 pixi install
@@ -32,9 +32,11 @@ pixi run dora build Demo/dataflow_tracking_real.yml   # once
 pixi run dora run Demo/dataflow_tracking_real.yml
 ```
 
-The hand config is set in the dataflow YAML (hand_controller `args`): change `--config` and `--serialport` as needed. You can use a legacy file under `AHControl/config/r_hand*.toml` or the repo canonical calibration (e.g. `--config config/calibration/r_hand_team_julia.toml` when running from repo root). See [AHControl](AHControl/README.md) and [canonical_hand_config_design.md](docs/canonical_hand_config_design.md) for details.
+The hand config is set in the dataflow YAML (hand_controller `args`): change `--config` and `--serialport` as needed. You can use a legacy file under `AHControl/config/r_hand*.toml` or the repo canonical calibration (e.g. `--config config/calibration/r_hand_team_julia.toml` when running from repo root). See [AHControl](AHControl/README.md) and [canonical_hand_config_design.md](../docs/canonical_hand_config_design.md) for details.
 
-Linux: add your user to the `dialout` group for serial port access: `sudo usermod -a -G dialout $USER` (log out and back in). If your hand is on a different port (e.g. `/dev/ttyUSB0`), edit `Demo/dataflow_tracking_real.yml` and change the `--serialport` arg.
+Linux: add your user to the `dialout` group for serial port access: `sudo usermod -a -G dialout $USER` (log out and back in). If your hand is on a different port (e.g. `/dev/ttyUSB0`), edit the dataflow YAML and change the `--serialport` arg.
+
+Windows: before running real hardware demos, edit the dataflow YAML (`dataflow_tracking_real.yml`, `dataflow_tracking_real_team_julia.yml`, or `dataflow_tracking_real_2hands.yml`): set `path` to `target/debug/AHControl.exe` (not `AHControl`), and change `--serialport` to your COM port (e.g. `COM3`). Run `pixi run build-ahcontrol` first to build the binary. To find your COM port: `powershell -c "[System.IO.Ports.SerialPort]::getportnames()"` in Git Bash or PowerShell. Use Git Bash or a shell where pixi is available (see [DEVELOPMENT.md](../docs/DEVELOPMENT.md)).
 
 Finger angle control (simulation):
 
@@ -45,20 +47,17 @@ pixi run dora run Demo/dataflow_angle_simu.yml
 
 The dataflow `build` steps install HandTracking and AHSimulation in editable mode and build AHControl when needed.
 
-## How to use (uv):
-- Install Rust: https://www.rust-lang.org/tools/install
-- Install uv: https://docs.astral.sh/uv/getting-started/installation/
-- Install dora-rs: https://dora-rs.ai/docs/guides/Installation/installing
-  - start the daemon: `dora up`
+## How to use (uv)
 
-- Clone this repository and in a console from the directory run:
+Install [Rust](https://www.rust-lang.org/tools/install), [uv](https://docs.astral.sh/uv/getting-started/installation/), and [dora-rs](https://dora-rs.ai/docs/guides/Installation/installing). Clone the repository, start the daemon (`dora up`), and from the Demo directory run:
 - `uv venv --python 3.12`
 - To run the webcam hand tracking demo in simulation only:
   - `dora build dataflow_tracking_simu.yml --uv` (needs to be done only once)
   - `dora run dataflow_tracking_simu.yml --uv`
 - To run the webcam hand tracking demo with real hardware:
   - `dora build dataflow_tracking_real.yml --uv` (needs to be done only once)
   - `dora run dataflow_tracking_real.yml --uv`
+  - On Windows: edit the dataflow YAML for `path` (use `AHControl.exe`) and `--serialport` (use your COM port) as in the pixi section above.
 - To run a simple example to control the finger angles in simulation:
   - `dora build dataflow_angle_simu.yml --uv` (needs to be done only once)
   - `dora run dataflow_angle_simu.yml --uv`

diff --git a/FORK.md b/FORK.md
@@ -1,7 +1,3 @@
-# Fork Notice
+# Differences from Upstream
 
-This repository is a fork of [pollen-robotics/AmazingHand](https://github.com/pollen-robotics/AmazingHand).
-
-We no longer track or merge from upstream. The fork has diverged to meet our engineering needs: refactoring for effective unit testing, maintainability, and integration with our tooling (pixi, cross-platform support). These changes make regular merges impractical.
-
-If you need specific fixes from upstream, port them manually rather than merging.
+See the fork notice in [README.md](README.md). This file is for documenting how this repo differs from [pollen-robotics/AmazingHand](https://github.com/pollen-robotics/AmazingHand) (e.g. layout, tooling, refactors).
diff --git a/PythonExample/README.md b/PythonExample/README.md
@@ -7,26 +7,19 @@ Use Feetech software to set IDs : [https://github.com/Robot-Maker-SAS/FeetechSer
 
 ## Setup Environment
 
-**Install pixi** (if not already installed):
+See [DEVELOPMENT.md](../docs/DEVELOPMENT.md) for Pixi installation and full setup. From the repository root (where `pixi.toml` lives), in Git Bash (Windows) or a Unix shell (Linux/macOS):
 
 ```bash
-curl -fsSL https://pixi.sh/install.sh | bash
-```
-
-Restart your shell or run `source ~/.bashrc` (or the equivalent for your shell) so the `pixi` command is available.
-
-**With pixi (recommended)**
-From the repository root (where `pixi.toml` lives):
-
-```bash
-pixi install   # one time setup
-# Optional: export AMAZINGHAND_PROFILE=team_julia
+pixi install
+export AMAZINGHAND_PROFILE=team_julia   # optional
 pixi run python PythonExample/AmazingHand_FingerTest.py
 ```
 
 To run another script, replace the filename, e.g. `PythonExample/AmazingHand_Hand_FingerMiddlePos.py` or `PythonExample/AmazingHand_Demo.py`.
 
-Set `AMAZINGHAND_PROFILE` to choose a profile (e.g. `team_julia`, `team_krishan`). Profiles and hand calibration live in `config/profiles.toml` and `config/calibration/`; see [canonical_hand_config_design.md](../docs/canonical_hand_config_design.md). The hand must be connected via USB; the profile's `port` must match your system (e.g. `COM3` on Windows, `/dev/ttyACM0` on Linux). If the port is wrong or the device is unplugged, the script will fail with "No such file or directory".
+Profiles and hand calibration live in `config/profiles.toml` and `config/calibration/`; see [canonical_hand_config_design.md](../docs/canonical_hand_config_design.md). The hand must be connected via USB; the profile's `port` must match your system (e.g. `COM3` on Windows, `/dev/ttyACM0` on Linux). To override the port, edit `config/profiles.toml` and change the `port` key in your profile (e.g. `[profile.team_julia]` has `port = "/dev/ttyACM0"`; on Windows use `port = "COM4"` or whatever your device uses).
+
+- To find the COM port on Windows, run `powershell -c "[System.IO.Ports.SerialPort]::getportnames()"` in Git bash shell.
 
 ## Run Python Examples
 
@@ -35,28 +28,10 @@ Set `AMAZINGHAND_PROFILE` to choose a profile (e.g. `team_julia`, `team_krishan`
 Runs a loop of gestures (open/close, spread, point, victory, etc.) on one hand. Which hand is controlled by the profile's `hand_test_id` or `side`, or override with `--side`:
 
 ```bash
-# export AMAZINGHAND_PROFILE=team_julia
 pixi run python PythonExample/AmazingHand_Demo.py
-# Right hand (1) or left hand (2):
-pixi run python PythonExample/AmazingHand_Demo.py --side 1
-```
-
-Set `AMAZINGHAND_PROFILE` (e.g. `team_julia`); the profile loads servo IDs and rest/middle positions from `config/calibration/`. See [canonical_hand_config_design.md](../docs/canonical_hand_config_design.md).
-
-## Run Unit Tests
-
-From the repository root:
-
-```bash
-pixi run test-demo
+pixi run python PythonExample/AmazingHand_Demo.py --side 1   # right (1) or left (2)
 ```
 
-## Pre-commit (optional)
-
-To run lint and tests before each commit, install the git hooks:
-
-```bash
-pixi run pre-commit install
-```
+Set `AMAZINGHAND_PROFILE` first (see Setup). The profile loads servo IDs and rest/middle positions from `config/calibration/`. See [canonical_hand_config_design.md](../docs/canonical_hand_config_design.md).
 
-Hooks are limited to `PythonExample/`. Run manually with `pixi run pre-commit run --all-files`.
+For unit tests and pre-commit, see [maintainer.md](../docs/maintainer.md).
diff --git a/PythonExample/tests/test_common.py b/PythonExample/tests/test_common.py
@@ -1,6 +1,3 @@
-# Original authors: Pollen Robotics, AmazingHand authors.
-# See: https://github.com/pollen-robotics/AmazingHand
-#
 # Copyright (C) 2026 Julia Jia
 #
 # Licensed under the Apache License, Version 2.0 (the "License");

diff --git a/README.md b/README.md
@@ -1,6 +1,5 @@
 Project is licensed under [Apache 2.0](https://www.apache.org/licenses/LICENSE-2.0)
 
-
 Mechanical design is licensed under a:
 [Creative Commons Attribution 4.0 International License][cc-by].
 [![CC BY 4.0][cc-by-image]][cc-by]
@@ -10,7 +9,15 @@ Mechanical design is licensed under a:
 [cc-by-image]: https://licensebuttons.net/l/by/4.0/88x31.png
 [cc-by-shield]: https://img.shields.io/badge/License-CC%20BY-lightgrey.svg
 
+# Fork Notice
+
+This repository is a fork of [pollen-robotics/AmazingHand](https://github.com/pollen-robotics/AmazingHand). We are grateful to Pollen Robotics for the original project.
+
+We no longer sync with upstream. Our fork has evolved for our own needs: refactoring for unit testing, maintainability, and integration with our tooling (pixi, cross-platform support). The codebases have diverged enough that merging upstream is no longer practical.
+
+If you need changes from the original repo, we recommend porting them by hand. For a summary of how this repo differs from upstream, see [FORK.md](FORK.md).
 
+Below is the original readme content. 
 
 # Amazing Hand project
 

diff --git a/docs/DEVELOPMENT.md b/docs/DEVELOPMENT.md
@@ -0,0 +1,97 @@
+# Development Workflow
+
+## Table of Contents
+
+- [Prerequisites](#prerequisites)
+- [Setup (Linux and Windows)](#setup-linux-and-windows)
+- [Setup (Raspberry Pi)](#setup-raspberry-pi)
+- [Run Demos](#run-demos)
+  - [Start Dora Daemon](#start-dora-daemon)
+  - [Run a simple "finger angle" gesture demo in simulation](#run-a-simple-finger-angle-gesture-demo-in-simulation)
+  - [Run Python Example](#run-python-example)
+  - [Run Demo with Physical Hands](#run-demo-with-physical-hands)
+- [Appendix](#appendix)
+  - [Install Microsoft Visual C++ (MSVC) Build Tools](#install-microsoft-visual-c-msvc-build-tools)
+
+## Prerequisites
+
+Install the following tools:
+
+- Install Pixi: https://pixi.prefix.dev/latest/installation/. 
+  - On Windows, to use pixi in Git Bash, add `export PATH="$HOME/.pixi/bin:$PATH"` to `~/.bashrc`, then run `source ~/.bashrc`.
+  - Verify installation: `pixi --version`
+- Rust and cargo are installed via pixi (included in `pixi.toml`).
+
+## Setup (Linux and Windows)
+
+On regular Ubuntu (24.04) or Windows (Windows 11) machine, install the pixi environment (includes all Python dependencies). On Windows, Git Bash is tested.
+
+```bash
+# From repository root
+pixi install
+```
+
+Optionally, verify the installation by running unit tests:
+
+```bash
+pixi run test-python-example 
+pixi run test-demo
+pixi run test-ahcontrol
+```
+
+Windows only (Rust / test-ahcontrol): `pixi.toml` adds `vs2022_win-64` for win-64, which activates the MSVC toolchain (via vcvars64) when you run `pixi shell` or `pixi run`. You must have Visual Studio or Build Tools installed first (see Appendix). If you get a linker error (e.g. "extra operand", "link.exe not found"), install Build Tools per the Appendix, then run `pixi install` to refresh the environment. As a fallback, run `pixi run test-ahcontrol` from "x64 Native Tools Command Prompt for VS" (Start menu).
+
+## Setup (Raspberry Pi)
+Planned and upcoming.
+
+## Run Demos
+
+Tested on Ubuntu 24.04 and Windows 11 (Git Bash).
+
+### Start Dora Daemon
+
+Start the dora daemon using pixi:
+
+```bash
+pixi run dora up
+```
+
+### Run a simple "finger angle" gesture demo in simulation
+
+This runs `AHSimulation/examples/finger_angle_control.py` and streams targets into the MuJoCo viewer nodes. From the repository root:
+
+```bash
+pixi run dora-build-angle-simu   # once
+pixi run dora-run-angle-simu
+```
+
+Note: Dora/MuJoCo demos are tested on Linux and Windows. 
+
+Start an interactive shell in the pixi environment:
+```bash
+pixi shell
+```
+### Run Python Example
+
+See [PythonExample/README.md](../PythonExample/README.md).
+
+### Run Demo with Physical Hands
+
+See [Demo/README.md](../Demo/README.md). On Linux, add your user to the `dialout` group for serial port access. On Windows, edit the dataflow YAML for the COM port and `AHControl.exe` path.
+
+## Appendix
+
+### Install Microsoft Visual C++ (MSVC) Build Tools
+
+Required for building the Rust crate (`test-ahcontrol`) on Windows. The `vs2022_win-64` package in `pixi.toml` activates this toolchain automatically; you must install Build Tools first. Download and install:
+
+1. Download the Build Tools installer from: https://visualstudio.microsoft.com/visual-cpp-build-tools (or direct: https://aka.ms/vs/17/release/vs_BuildTools.exe).
+
+2. Run `vs_BuildTools.exe`. If the Visual Studio Installer is not installed, it will install first.
+
+3. In the installer, select the workload "Desktop development with C++". This includes the MSVC compiler, linker (`link.exe`), and Windows SDK.
+
+4. On the right-hand "Installation details" panel, ensure "MSVC v143 - VS 2022 C++ x64/x86 build tools" and "Windows 10/11 SDK" (or similar) are checked. Click Install.
+
+5. After installation, run `pixi install` (if needed) and `pixi run test-ahcontrol`. The `vs2022_win-64` package locates your install via vswhere and runs vcvars64 so the correct linker is on PATH.
+
diff --git a/pixi.lock b/pixi.lock
diff --git a/pixi.toml b/pixi.toml
@@ -1,7 +1,7 @@
 [workspace]
 name = "amazinghand"
 version = "0.1.0"
-description = "Amazing Hand - Python examples and demos (Pollen Robotics)"
+description = "Amazing Hand - Python examples and demos (hardware-fork/Pollen Robotics)"
 channels = ["conda-forge"]
 # Ubuntu (x86_64), Windows (x64), Raspberry Pi (aarch64)
 platforms = ["linux-64", "win-64", "linux-aarch64", "osx-arm64"]
@@ -11,6 +11,10 @@ python = "3.12.*"
 pip = "*"
 rust = "*"
 
+[target.win-64.dependencies]
+# Provides activation that runs vcvars64, putting MSVC link.exe on PATH so Rust finds it (not Git's link)
+vs2022_win-64 = "*"
+
 [target.linux-64.activation.env]
 # Use system GCC for Rust linking; conda's toolchain can fail with __libc_csu_* symbols on Linux
 CC = "/usr/bin/gcc"
@@ -34,8 +38,17 @@ onshape-to-robot = ">=1.7.5"
 qpsolvers = { version = ">=4.7.1", extras = ["quadprog"] }
 
 [tasks]
-# PYTHONPATH= avoids loading system/ROS pytest plugins when run locally
+
+# Unit test related
+# PYTHONPATH= avoids loading system/ROS pytest plugins when run locally (works in Git Bash and Unix)
 test-python-example = "cd PythonExample && PYTHONPATH= python -m pytest tests/ -v"
 test-demo = "cd Demo && python -m pytest tests/ -v"
-test-demo-mj-mink = "python -m pytest Demo/tests/test_mj_mink.py -v"
 test-ahcontrol = "cargo test --manifest-path Demo/Cargo.toml -p AHControl"
+
+# build related
+build-ahcontrol = "cargo build --release --manifest-path Demo/Cargo.toml -p AHControl"
+
+# dora demos (run from repo root; when used as submodule, use path from parent repo)
+dora-build-angle-simu = "dora build Demo/dataflow_angle_simu.yml"
+dora-run-angle-simu = "dora run Demo/dataflow_angle_simu.yml"
+