diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 32b0326..6bd370e 100644 --- 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 index 81426e7..bf3928f 100644 --- 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,13 +47,9 @@ 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) @@ -59,6 +57,7 @@ The dataflow `build` steps install HandTracking and AHSimulation in editable mod - 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 index 997c671..d503567 100644 --- 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 index 777f9ac..2f12ee7 100644 --- 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 index f19e23e..7673b29 100644 --- 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 index 26eec93..302560b 100644 --- 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 new file mode 100644 index 0000000..285e95a --- /dev/null +++ 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 index a86af6b..2bbc1b3 100644 --- a/pixi.lock +++ b/pixi.lock @@ -333,6 +333,8 @@ environments: - conda: https://conda.anaconda.org/conda-forge/win-64/vc-14.3-h41ae7f8_34.conda - conda: https://conda.anaconda.org/conda-forge/win-64/vc14_runtime-14.44.35208-h818238b_34.conda - conda: https://conda.anaconda.org/conda-forge/win-64/vcomp14-14.44.35208-h818238b_34.conda + - conda: https://conda.anaconda.org/conda-forge/win-64/vs2022_win-64-19.44.35207-ha74f236_34.conda + - conda: https://conda.anaconda.org/conda-forge/noarch/vswhere-3.1.7-h40126e0_1.conda - conda: https://conda.anaconda.org/conda-forge/noarch/wheel-0.46.3-pyhd8ed1ab_0.conda - pypi: https://files.pythonhosted.org/packages/18/a6/907a406bb7d359e6a63f99c313846d9eec4f7e6f7437809e03aa00fa3074/absl_py-2.4.0-py3-none-any.whl - pypi: https://files.pythonhosted.org/packages/3a/2a/7cc015f5b9f5db42b7d48157e23356022889fc354a2813c15934b7cb5c0e/attrs-25.4.0-py3-none-any.whl @@ -3458,6 +3460,30 @@ packages: - setuptools>=68 ; extra == 'test' - time-machine>=2.10 ; platform_python_implementation == 'CPython' and extra == 'test' requires_python: '>=3.8' +- conda: https://conda.anaconda.org/conda-forge/win-64/vs2022_win-64-19.44.35207-ha74f236_34.conda + sha256: 05bc657625b58159bcea039a35cc89d1f8baf54bf4060019c2b559a03ba4a45e + md5: 1d699ffd41c140b98e199ddd9787e1e1 + depends: + - vswhere + constrains: + - vs_win-64 2022.14 + track_features: + - vc14 + license: BSD-3-Clause + license_family: BSD + purls: [] + size: 23060 + timestamp: 1767320175868 +- conda: https://conda.anaconda.org/conda-forge/noarch/vswhere-3.1.7-h40126e0_1.conda + sha256: b72270395326dc56de9bd6ca82f63791b3c8c9e2b98e25242a9869a4ca821895 + md5: f622897afff347b715d046178ad745a5 + depends: + - __win + license: MIT + license_family: MIT + purls: [] + size: 238764 + timestamp: 1745560912727 - conda: https://conda.anaconda.org/conda-forge/noarch/wheel-0.46.3-pyhd8ed1ab_0.conda sha256: d6cf2f0ebd5e09120c28ecba450556ce553752652d91795442f0e70f837126ae md5: bdbd7385b4a67025ac2dba4ef8cb6a8f diff --git a/pixi.toml b/pixi.toml index 6af5bad..f7a784c 100644 --- 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" +