Documentation update

2026-03-01 19:27:47 +01:00
parent 4ba4dac7ff
commit 76c7a9c23c
1 changed files with 95 additions and 21 deletions
--- a/README.md
+++ b/README.md
@@ -1,26 +1,103 @@
-# Air mouse
+# IMU Air Mouse

-This project is aimed at replacing/open-sourcing the Logitech presenter. It also contains some features not found on the Logitech Spotlight.
+A BLE HID mouse that uses the onboard IMU of a **Seeed XIAO nRF52840 Sense** to move the cursor by tilting and rotating the device in the air. Intended as an open-source replacement for presentation remotes like the Logitech Spotlight, with additional features.
+
+## Features
+
+- **6-DoF gyro + accelerometer** via LSM6DS3 with complementary filter
+- **Hardware tap detection** — single tap = left click, double tap = right click
+- **BLE HID mouse** — works natively on Windows, macOS, Linux, Android, iOS
+- **BLE Battery Service** — charge level visible in OS Bluetooth settings
+- **Web config UI** (`web/index.html`) — configure over BLE from any Chrome/Edge browser, no app install
+- **Flash persistence** — config survives power cycles (LittleFS)
+- **Live IMU stream** — 20 Hz gyro/accel data streamed to the web UI visualiser
+- **Live telemetry** — temperature, uptime, click counts, gyro bias RMS, recal count
+- **Temperature compensation** — gyro drift correction by Δ temperature since last calibration
+- **Auto-recalibration** — recalibrates automatically after 5 minutes of idle
+- **Configurable charge rate** — OFF / 50 mA slow / 100 mA fast via BQ25100 HICHG pin
+- **Boot-loop detection** — 3 rapid reboots trigger safe mode (config service disabled, flash wiped)
+
+## Hardware
+
+| Part | Notes |
+|---|---|
+| Seeed XIAO nRF52840 Sense | nRF52840 + LSM6DS3 IMU onboard |
+| Li-ion battery (10440 / LiPo) | Connected to VBAT + GND pads |
+
+## LED Status
+
+The XIAO has three user LEDs (active LOW — HIGH = off, LOW = on):
+
+| LED | Pattern | Meaning |
+|---|---|---|
+| Blue | Single pulse every 10 s | BLE connected (heartbeat) |
+| Green | Single pulse every 10 s | Advertising / not connected (heartbeat) |
+| Green | Rapid flutter (~10 Hz) | Gyro calibration in progress |
+| Red | Fast blink (continuous) | IMU init failed — hardware fault |
+| Red | 3 slow blinks on boot | Boot-loop detected — entered safe mode |
+| Red | 6 rapid blinks | Battery critically low (< 3.10 V) |
+
+> **Blue** = BLE-related state. **Green** = device activity. **Red** = fault only.
+
+## Web Config UI
+
+Open `web/index.html` in Chrome or Edge (desktop). Requires Web Bluetooth — enable it at `chrome://flags/#enable-web-bluetooth` on Linux.
+
+**Configurable parameters:**
+
+| Parameter | Range | Description |
+|---|---|---|
+| Sensitivity | 100 – 1500 | Cursor speed multiplier |
+| Dead zone | 0.005 – 0.2 rad/s | Noise floor; raise to reduce drift |
+| Accel strength | 0 – 0.5 | Pointer acceleration multiplier |
+| Curve | Linear / Square / √Sqrt | Response shape for input magnitude |
+| Flip X / Y | on/off | Invert horizontal or vertical axis |
+| Charge mode | Off / 50 mA / 100 mA | BQ25100 charge current |
+
+**Commands:**
+
+- **Calibrate Gyro** — recalculates bias offset; hold the device still on a flat surface for ~1 s
+- **Factory Reset** — wipes flash config, restores defaults
+
+## Building
+
+### Requirements
+
+- [PlatformIO](https://platformio.org/) (VS Code extension or CLI)
+- `adafruit-nrfutil` for flashing: `pip install adafruit-nrfutil`
+
+### Flash
+
+```sh
+pio run -t upload
+```
+
+Double-tap the reset button to enter the UF2 bootloader (red LED pulses) if the board doesn't auto-reset.
+
+### Feature flags
+
+All optional features are enabled by `#define` in `source/config.h`. Comment out any line to disable that feature and reduce firmware size / RAM:

-I used a **Seeed Studio XIAO nRF52480 Sense** board, but it required some BSP modification to work with SoftDevice S140 7.3.0. Namely the memory layout:
 ```c
-/* Linker script to configure memory regions. */
+#define FEATURE_CONFIG_SERVICE    // BLE config GATT service
+#define FEATURE_TELEMETRY         // 1 Hz telemetry notifications
+#define FEATURE_IMU_STREAM        // 20 Hz raw IMU stream
+#define FEATURE_TAP_DETECTION     // Hardware tap → click engine
+#define FEATURE_TEMP_COMPENSATION // Gyro drift correction by temperature
+#define FEATURE_AUTO_RECAL        // Auto-recalibrate after 5 min idle
+#define FEATURE_BATTERY_MONITOR   // ADC battery level + BLE Battery Service
+#define FEATURE_BOOT_LOOP_DETECT  // Crash counter → safe mode
+```

-SEARCH_DIR(.)
-GROUP(-lgcc -lc -lnosys)
+## BSP memory layout fix

+The XIAO nRF52840 Sense requires a modified linker script to work with SoftDevice S140 7.3.0. Edit `cores/linker/nrf52840_s140_v7.ld` in the Adafruit nRF52 Arduino core:
+
+```c
 MEMORY
 {
-  FLASH (rx)     : ORIGIN = 0x27000, LENGTH = 0xED000 - 0x27000
-
-  /* SRAM required by Softdevice depend on
-   * - Attribute Table Size (Number of Services and Characteristics)
-   * - Vendor UUID count
-   * - Max ATT MTU
-   * - Concurrent connection peripheral + central + secure links
-   * - Event Len, HVN queue, Write CMD queue
-   */ 
-  RAM (rwx) :  ORIGIN = 0x2000E000, LENGTH = 0x20040000 - 0x2000E000
+  FLASH (rx)  : ORIGIN = 0x27000, LENGTH = 0xED000 - 0x27000
+  RAM   (rwx) : ORIGIN = 0x2000E000, LENGTH = 0x20040000 - 0x2000E000
 }

 SECTIONS
@@ -32,7 +109,7 @@ SECTIONS
    KEEP(*(.svc_data))
    PROVIDE(__stop_svc_data = .);
  } > RAM
-  
+
  .fs_data :
  {
    PROVIDE(__start_fs_data = .);
@@ -41,8 +118,5 @@ SECTIONS
  } > RAM
 } INSERT AFTER .data;

-INCLUDE "nrf52_common.ld"
+INCLUDE "nrf52_common.ld";
 ```
-in `cores/linker/nrf52840_s140_v7.ld`
-
-You can use the `web-config.html` page to configure this device.