# ESP32-C3 BNO055 Orientation HUD & Web Visualizer

An embedded C++ firmware for the **Adafruit QT Py ESP32-C3** that reads real-time absolute spatial orientation from a **Bosch BNO055** 9-DOF IMU sensor operating in hardware sensor fusion (NDOF) mode. 

The application streams Euler orientation data (`Yaw`, `Pitch`, `Roll`) concurrently across two channels:
1. **Serial Terminal HUD:** A live ASCII HUD streaming through native USB CDC at ~25 Hz with dynamic range bars, frame rate telemetry, and 4-point sensor calibration status.
2. **Wi-Fi Access Point Web Server:** Hosts a local HTTP server serving an HTML5/CSS3 3D visualizer that updates an interactive CSS cube via AJAX requests.

---

## 🛠️ Hardware Requirements & Pinout

| Hardware Unit | Role | Notes / Configuration |
| :--- | :--- | :--- |
| **Adafruit QT Py ESP32-C3** | Microcontroller | RISC-V Single-Core CPU @ 160MHz |
| **Bosch BNO055** | 9-DOF IMU Sensor | Internal NDOF hardware fusion mode |
| **I2C Interface** | Communication Bus | Standard Mode (100 kHz) |

### Wiring Matrix

┌───────────────────────────────┐ ┌───────────────────────────────┐ │ Adafruit QT Py ESP32-C3 │ │ Bosch BNO055 IMU │ │ │ │ │ │ SDA ├──────────────┤ SDA │ │ SCL ├──────────────┤ SCL │ │ 3V3 ├──────────────┤ VIN │ │ GND ├──────┬───────┤ GND │ └───────────────────────────────┘ │ │ COM3 │ └───────┴───────────────────────────────┘

> **Hardware Note:** Wire **`COM3` to `GND`** on the BNO055 breakout board to force default I2C slave address `0x28`.

---

## 🏗️ Architecture & Data Flow

                              ┌──────────────────┐
                              │   BNO055 IMU     │
                              │   (NDOF Mode)    │
                              └────────┬─────────┘
                                       │ I2C @ 100 kHz
                                       ▼
                              ┌──────────────────┐
                              │  ESP32-C3 Core   │
                              └────────┬─────────┘
                                       │
                ┌──────────────────────┴──────────────────────┐
                ▼                                             ▼
   ┌──────────────────────────┐                  ┌──────────────────────────┐
   │   Serial HUD Terminal    │                  │  HTTP Server (Wi-Fi AP)  │
   │  • Yaw / Pitch / Roll    │                  │  • GET /           → 3D  │
   │  • Bar Sliders           │                  │  • GET /index.html → Web │
   │  • Calib Status & FPS    │                  │  • GET /data       → JSON│
   └──────────────────────────┘                  └──────────────────────────┘

---

## 🚀 Getting Started

### Prerequisites

- [VS Code](https://code.visualstudio.com/) with the [PlatformIO IDE Extension](https://platformio.org/) installed
- USB-C cable compatible with data transmission

### PlatformIO Configuration (`platformio.ini`)

Ensure your `platformio.ini` mirrors the configuration below to enable native USB CDC output on the ESP32-C3:

```ini
[env:adafruit_qtpy_esp32c3]
platform = espressif32
board = adafruit_qtpy_esp32c3
framework = arduino
monitor_speed = 115200
build_flags = 
    -D ARDUINO_USB_CDC_ON_BOOT=1
    -D ARDUINO_USB_MODE=1
lib_deps = 
    adafruit/Adafruit BNO055 @ ^1.6.3
    adafruit/Adafruit Unified Sensor @ ^1.1.14

Installation

1. Clone the repository:

git clone [https://github.com/your-username/AbsoluteLocation.git](https://github.com/your-username/AbsoluteLocation.git)
cd AbsoluteLocation

2. Build and Upload: Connect your ESP32-C3 to your computer via USB-C and run:

pio run --target upload

3. Open Serial Monitor:

pio device monitor

---

💻 Operation

1. Terminal HUD Interface

Set your serial client to 115200 baud. The output streams live telemetry frames containing calculated angles, visual position indicators, loop speed (FPS), and subsystem calibration levels (0 = uncalibrated, 3 = fully calibrated):

 ░▒▓████████████████████████████████████████████████████████▓▒░
 ░▒▓█      BNO055 ORIENTATION HUD - ESP32-C3 QT Py     █▓▒░
 ░▒▓████████████████████████████████████████████████████████▓▒░
  ├── Hardware Subsystem : Adafruit QT Py ESP32-C3
  ├── Protocol Interface : I2C Bus (Fast Mode 100kHz)
  └── Target Address     : 0x28 (Default Mode)
 ──────────────────────────────────────────────────────────────
  [SYSTEM INIT] Connecting to BNO055... [  OK - ONLINE  ]
 ──────────────────────────────────────────────────────────────

  YAW (Z: 0..360°)     PITCH (Y: ±180°)     ROLL (X: ±90°)      FPS   STATUS
 ══════════════════════════════════════════════════════════════════════════════════
  180.2° [──────┼──◆──]   -12.4° [────◆─┼─────]     5.1° [──────┼─◆───]   24.8 CALIB: SYS:3 G:3 A:3 M:3 [  FULL  ]

2. Interactive Web Visualizer

1. Connect your Wi-Fi enabled device to the Access Point created by the micro-controller:

• SSID: BNO055_3D
• Password: 12345678

2. Open any web browser and navigate to:

[http://192.168.4.1](http://192.168.4.1)

3. The page presents a full 3D rendering of a spatial orientation cube driven by high-frequency AJAX requests to the embedded /data REST endpoint.

---

📡 API Specification

GET /data

Returns real-time Euler angles in degrees as a lightweight JSON payload.

Response (200 OK)

{
  "yaw": 180.25,
  "pitch": -12.40,
  "roll": 5.12
}

---

📄 License

Distributed under the MIT License.