Kb/feature/add tactile sensing and haptic feedback

.github/workflows/ci.yml

@@ -11,13 +11,13 @@ jobs:
     steps:
       - uses: actions/checkout@v4
 
+      - name: Install system deps
+        run: sudo apt-get update && sudo apt-get install -y libudev-dev pkg-config liblgpio-dev
+
       - uses: prefix-dev/setup-pixi@v0.9.4
         with:
           cache: ${{ !env.ACT }}
 
-      - name: Install system deps for AHControl (Rust)
-        run: sudo apt-get update && sudo apt-get install -y libudev-dev pkg-config
-
       - name: Run pre-commit
         run: pixi run pre-commit run --all-files
 

.gitignore

@@ -13,3 +13,8 @@ target/
 Demo/out/
 out/
 *.code-workspace
+
+# Log, CSV, and HTML plot files
+*.log
+*.csv
+*.html

FORK.md

@@ -22,6 +22,10 @@ GitHub Actions for lint (pre-commit), SDK, PythonExample, Demo, and AHControl te
 
 Pixi task `pixi run check-devices` lists webcam indices and serial ports. Use before running demos to verify device paths.
 
+## Tactile Sensing and Haptic Feedback
+
+FSR tactile sensing via the Waveshare ADS1256 24-bit ADC HAT, and PWM-driven haptic feedback via a QYF-740 coin motor. Includes real-time terminal/GUI display, CSV logging, and offline Bokeh visualisation. See [src/amazinghand_sensors/README.md](src/amazinghand_sensors/README.md).
+
 ## Other Changes
 
 Pixi for dependency management; unit tests for SDK, PythonExample, Demo, and AHControl; Dora/MuJoCo simulation demos; pre-commit hooks.

docs/BOM.md

@@ -0,0 +1,24 @@
+# Bill of Materials (BOM)
+
+## Required Components
+
+| Component | Link |
+|---|---|
+| Camera | https://www.amazon.com/dp/B0CLRJZG8D |
+| AD/DA Expansion Hat | https://www.amazon.com/dp/B09Q8Y5F7Y |
+| Haptic Motors | https://www.amazon.com/dp/B0FX9HW33Z |
+| Pressure Sensors (FSR) | https://www.amazon.com/dp/B0FGD267GK |
+| Resistor Kit | https://www.amazon.com/dp/B016NXK6QK |
+
+> **Note:** FSR voltage divider uses a **5.1 kΩ** resistor in series with each pressure sensor.
+
+---
+
+## Nice to Have
+
+| Component | Link |
+|---|---|
+| Silicone Flexible Jumper Wires (Nice Quality) | https://www.amazon.com/dp/B0DNPS4RVQ |
+| Dual Male Jumper Wires | https://www.amazon.com/dp/B09P52PLK4 |
+| Breadboard | https://www.amazon.com/dp/B07DL13RZH |
+| Generic Jumper Wires | https://www.amazon.com/dp/B01EV70C78 |

docs/DEVELOPMENT.md

@@ -42,7 +42,26 @@ 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.
+Raspberry Pi support is experimental and focuses on the haptic/tactile demos.
+
+On Raspberry Pi OS (Debian-based), install system GPIO dependencies first:
+
+```bash
+sudo apt-get update
+sudo apt-get install liblgpio-dev
+```
+
+Then create the pixi environment from the repository root:
+
+```bash
+pixi install
+```
+
+You can now run the haptic/tactile sensor test (from the repo root):
+
+```bash
+pixi run python -m amazinghand_sensors.haptic_test
+```
 
 ## Run Demos
 

pixi.toml

@@ -10,6 +10,8 @@ platforms = ["linux-64", "win-64", "linux-aarch64", "osx-arm64"]
 python = "3.12.*"
 pip = "*"
 rust = "*"
+pyside6 = "*"
+swig = "*"
 
 [target.win-64.dependencies]
 # Provides activation that runs vcvars64, putting MSVC link.exe on PATH so Rust finds it (not Git's link)
@@ -39,6 +41,15 @@ mujoco = ">=3.3.2"
 onshape-to-robot = ">=1.7.5"
 qpsolvers = { version = ">=4.7.1", extras = ["quadprog"] }
 pyserial = ">=3.5"
+# Demo/Sensors — tactile sensing, haptic feedback, visualisation
+lgpio      = "*"
+spidev     = "*"
+loguru     = "*"
+pyqtgraph  = "*"
+bokeh      = "*"
+pandas     = "*"
+gitpython  = "*"
+gpiozero   = "*"
 
 [tasks]
 

pyproject.toml

@@ -36,3 +36,4 @@ pythonpath = ["src"]
 
 [tool.setuptools.package-data]
 amazinghand = ["config/*.toml", "config/calibration/*.toml"]
+amazinghand_sensors = ["config.toml", "images/*"]

src/amazinghand_sensors/README.md

@@ -0,0 +1,147 @@
+# AmazingHand — Sensors
+
+## Files
+
+| File | Description |
+|---|---|
+| `config.toml` | Shared config — GPIO pins, SPI settings, sensor channels, logging and visualisation defaults |
+| `ads1256.py` | ADS1256 driver — 24-bit, 8-channel |
+| `tactile_sensing.py` | `TactileSensor` wrapper — reads config.toml and drives the ADS1256 |
+| `tactile_sensing_post_visualize.py` | Offline Bokeh visualisation of logged CSV data |
+| `haptic_coin.py` | `HapticCoin` PWM class for the QYF-740 coin motor |
+
+---
+
+## FSR Tactile Sensing (ADS1256)
+
+### Hardware
+
+- **ADC HAT**: [Waveshare High-Precision AD HAT](https://www.waveshare.com/wiki/High-Precision_AD_HAT)
+  - ADS1256: 24-bit, 8 single-ended channels, SPI
+- **Sensors**: FSR (Force Sensitive Resistors) wired in a voltage-divider circuit with a **5.1 kΩ resistor** in series with each FSR to each ADC input channel.
+
+### FSR Wiring Diagram
+
+![FSR Wiring Diagram](images/fsr_wiring_diagram.png)
+
+### SPI Wiring (BCM pin numbers, set in `config.toml`)
+
+| Signal | BCM | Pi header pin |
+|---|---|---|
+| MOSI (DIN) | GPIO 10 | Pin 19 |
+| MISO (DOUT) | GPIO 9 | Pin 21 |
+| SCLK | GPIO 11 | Pin 23 |
+| CS | GPIO 22 | Pin 15 |
+| RST | GPIO 18 | Pin 12 |
+| DRDY | GPIO 17 | Pin 11 |
+
+Enable SPI on the Pi:
+```bash
+sudo raspi-config  # Interface Options → SPI → Enable
+```
+
+### Install dependencies
+
+```bash
+pixi install
+```
+
+To add a single package interactively:
+
+```bash
+pixi add --pypi lgpio
+```
+
+### Run
+
+**GUI (default):**
+```bash
+pixi run python -m amazinghand_sensors.tactile_sensing
+```
+
+**Terminal only (no GUI window):**
+```bash
+pixi run python -m amazinghand_sensors.tactile_sensing --terminal
+```
+
+See all flags:
+```bash
+pixi run python -m amazinghand_sensors.tactile_sensing --help
+```
+
+### Offline Visualization
+
+Run without arguments to automatically load the **latest** `tactile_*.csv` from the log directory configured in `config.toml` (`[logging] log_dir`):
+
+```bash
+pixi run python -m amazinghand_sensors.tactile_sensing_post_visualize
+```
+
+To visualize a **specific file**, pass it with `--file`:
+
+```bash
+pixi run python -m amazinghand_sensors.tactile_sensing_post_visualize --file LOGS/tactile_20260101_120000.csv
+```
+
+See all flags:
+
+```bash
+pixi run python -m amazinghand_sensors.tactile_sensing_post_visualize --help
+```
+
+CSV schema (long format — one row per channel per sample):
+
+```
+sensor_time, channel, raw, volts, force_norm
+```
+
+### Tuning `fsr_r_fixed`
+
+The `fsr_r_fixed` parameter must match the resistor you place in series with each FSR to form the voltage divider. The build uses **5 100 Ω (5.1 kΩ)**. Larger values increase sensitivity at low force; smaller values increase the measurable force range.
+
+---
+
+## Haptic Coin (QYF-740)
+
+### Pin conflict warning
+
+The ADS1256 tactile sensing stack claims the following BCM GPIO pins.  **Do not assign the HapticCoin to any of these:**
+
+| BCM | Use |
+|---|---|
+| GPIO 8 | SPI0 CE0 (kernel) |
+| GPIO 9 | SPI0 MISO |
+| GPIO 10 | SPI0 MOSI |
+| GPIO 11 | SPI0 SCLK |
+| GPIO 17 | ADS1256 DRDY |
+| GPIO 18 | ADS1256 RST |
+| GPIO 22 | ADS1256 CS |
+| GPIO 23 | ADS1256 CS_DAC |
+
+Safe choices for the PWM output include GPIO 12, 13 (hardware PWM), 24, 25, 26, 27, or 35.
+
+### Wiring — [RPi 5 pinout](https://vilros.com/pages/raspberry-pi-5-pinout)
+
+![Raspberry Pi 5 GPIO Pinout](images/rpi5_pinout.jpg)
+
+| Motor wire | Pi pin |
+|---|---|
+| GND | Pin 6 |
+| VCC | Pin 2 (5 V) |
+| PWM | Pin 35 (GPIO 19) |
+
+### Usage
+
+```python
+from amazinghand_sensors.haptic_coin import HapticCoin
+
+motor = HapticCoin(gpio_pin=19)
+motor.vibrate_once(intensity=0.8, duration_s=0.5)
+motor.cleanup()
+```
+
+Run the example test script as a module so relative imports resolve:
+
+```bash
+pixi run python -m amazinghand_sensors.haptic_test
+```