multi-functional-controller/README.md

# Multi-Functional Controller (MFC)

[![ESP-IDF](https://img.shields.io/badge/ESP--IDF-v5.x-E7352C?style=for-the-badge&logo=espressif&logoColor=white)](https://github.com/espressif/esp-idf)
[![Target MCU](https://img.shields.io/badge/MCU-ESP32--S3--N16R8-red?style=for-the-badge&logo=espressif)](https://www.espressif.com/en/products/socs/esp32-s3)
[![KiCad](https://img.shields.io/badge/EDA-KiCad%2010-314CB0?style=for-the-badge&logo=kicad&logoColor=white)](https://www.kicad.org/)
[![Language](https://img.shields.io/badge/Firmware-C99%20%2F%20C%2B%2B-00599C?style=for-the-badge&logo=c)](https://en.wikipedia.org/wiki/C_(programming_language))
[![RTOS](https://img.shields.io/badge/OS-FreeRTOS-008080?style=for-the-badge)](https://www.freertos.org/)
[![Status](https://img.shields.io/badge/Status-Active%20Prototype-success?style=for-the-badge)](#roadmap--milestones)

A custom, high-performance handheld remote controller engineered from scratch for dual-role applications: **long-range, low-latency RC vehicle control** and **USB/Bluetooth HID gaming**. 

Built around the **ESP32-S3 (Xtensa® 32-bit LX7 dual-core @ 240 MHz)**, this project bridges hardware and software engineering—combining magnetic Hall-effect sensing, RF telemetry, hardware pulse-counted rotary inputs, hardware PWM audio synthesis, and an SPI graphics pipeline into a unified, battery-powered embedded platform.

---

## Prototype Showcase

<p align="center">
  <img src="images/TOP_VIEW.png" alt="Multi-Functional Controller Top View" width="700">
  <br>
  <em><b>Figure 1:</b> Top assembly layout — Dual Hall-effect joysticks, rotary encoder, tactile buttons, 1.3" SPI OLED display, NeoPixel telemetry bar, and audio transducers.</em>
</p>

<p align="center">
  <img src="images/SIDE_VIEW_WITH_ANTENNA.png" alt="Multi-Functional Controller Profile & RF Antenna" width="700">
  <br>
  <em><b>Figure 2:</b> Ergonomic profile — 2.4 GHz high-gain dipole antenna connected to the NRF24L01+ RF transceiver, rotary dial, and dual USB-C ports.</em>
</p>

<p align="center">
  <img src="images/BOTTOM_VIEW.png" alt="Multi-Functional Controller Perfboard Soldering" width="700">
  <br>
  <em><b>Figure 3:</b> Underbody point-to-point bus routing — 6×9 cm perfboard with dedicated decoupled power rails (100 µF smoothing capacitor) and direct GPIO signal lines.</em>
</p>

---

## Key Hardware & Architectural Features

- **Microcontroller Core:** Espressif ESP32-S3-N16R8 (16 MB Quad SPI Flash, 8 MB Octal PSRAM) running FreeRTOS preemptive multitasking.
- **Dual Wireless Pipelines:**
  - **2.4 GHz RF (NRF24L01+):** Dedicated SPI radio module with external SMA antenna for low-latency, deterministic RC telemetry.
  - **Bluetooth 5.0 LE & Wi-Fi:** Native wireless stacks for PC/gamepad HID modes and wireless telemetry streaming.
- **Precision Analog & Digital Controls:**
  - **Dual Hall-Effect Joysticks:** Contactless magnetic sensing for zero stick drift and extended durability.
  - **Hardware Pulse-Counted Rotary Encoder:** Quadrature decoding handled in hardware via the ESP32-S3 `pulse_cnt` peripheral to guarantee zero missed ticks during high-load processing loops.
  - **Dedicated Navigation Buttons:** Tactile push-buttons configured with internal pull-ups for UI interaction and control toggling.
- **Multi-Sensor Audio & Visual Telemetry:**
  - **1.3" SPI OLED Display (SH1106 / SSD1306):** Driven via hardware DMA SPI (`SPI2_HOST`) with custom frame buffering for menus, telemetry, and live status readouts.
  - **Polyphonic Melodic Synthesis:** Passive buzzer modulated via hardware LEDC PWM timer (`LEDC_TIMER_0`, 13-bit duty resolution).
  - **Percussive Acoustic Alerts:** Dual active buzzers for instant tactile/auditory feedback and warning signals.
  - **Visual Beat & Metric Indicators:** Dedicated Kick (GPIO 21) and Hi-Hat (GPIO 22) LEDs alongside an 8-LED WS2812B NeoPixel RGB strip driven via RMT.
- **Power Subsystem:**
  - Dual parallel 18650 Li-ion cells delivering **4800 mAh** combined capacity.
  - Dual USB-C ports: one dedicated for high-efficiency battery charging and one for USB-UART flashing, debugging, and wired HID gamepad control.
  - 100 µF low-ESR electrolytic capacitor buffering transient current spikes from RF transmission bursts and buzzer pulses.

---

## GPIO Pinout & Peripheral Mapping (ESP32-S3 Hardware Specification)

The physical controller uses a shared high-speed **SPI2_HOST** bus for both the 1.3" OLED and the NRF24L01+ RF transceiver, alongside dedicated ADC1 channels and hardware pulse-counter inputs:

| Peripheral / Signal | GPIO | Hardware Interface | Description |
| :--- | :---: | :--- | :--- |
| **SPI Bus: MOSI** | `GPIO 11` | SPI Master Output (`SPI2_HOST`) | Shared data line for NRF24L01+ and OLED (`SDA` / `D1`) |
| **SPI Bus: MISO** | `GPIO 13` | SPI Master Input (`SPI2_HOST`) | Data line from NRF24L01+ radio module |
| **SPI Bus: SCK (Clock)** | `GPIO 12` | SPI Master Clock (`SPI2_HOST`) | Shared clock line for NRF24L01+ and OLED (`CLK` / `D0`) |
| **NRF24L01+ Chip Select (CSN)** | `GPIO 14` | Dedicated SPI Device Select | Radio bus enable / frame delimiter |
| **NRF24L01+ Chip Enable (CE)** | `GPIO 21` | Digital Output | Radio RX/TX state activation and power line |
| **OLED Chip Select (CS)** | `GPIO 10` | Dedicated SPI Device Select | Display bus enable |
| **OLED Data/Command (DC)** | `GPIO 9` | Digital Output | 1.3" OLED command vs. graphic data selection |
| **OLED Reset (RES)** | `GPIO 8` | Digital Output | Hardware display reset line |
| **Joystick VRx (X-Axis)** | `GPIO 4` | ADC1 Channel 3 (12 dB Attenuation) | Analog X-axis potentiometer (0–3.3V range, Wi-Fi safe) |
| **Joystick VRy (Y-Axis)** | `GPIO 5` | ADC1 Channel 4 (12 dB Attenuation) | Analog Y-axis potentiometer (0–3.3V range, Wi-Fi safe) |
| **Rotary Encoder CLK** | `GPIO 15` | ESP-IDF `pulse_cnt` Unit | Quadrature channel A (hardware edge counter) |
| **Rotary Encoder DT** | `GPIO 16` | ESP-IDF `pulse_cnt` Unit | Quadrature channel B (hardware direction sensing) |
| **Rotary Encoder Switch (SW)**| `GPIO 17` | Digital Input (`PULLUP`) | Rotary push-button (menu select / enter) |

---

## Repository Structure

```text
multi-functional-controller/
├── firmware/                        # ESP-IDF C99/C++ Firmware Project
│   ├── CMakeLists.txt               # Top-level CMake project configuration
│   ├── sdkconfig                    # ESP32-S3 configuration (PSRAM, Flash, FreeRTOS)
│   └── main/
│       ├── CMakeLists.txt           # Component registration
│       ├── idf_component.yml        # Espressif component dependencies (led_strip)
│       └── mmcontroller.c           # Core firmware: FreeRTOS tasks, pulse counter, SPI OLED, LEDC PWM
├── hardware/                        # KiCad 10 Electronic Design Automation (EDA)
│   ├── mfc-1.kicad_pro              # KiCad project file
│   ├── mfc-1.kicad_sch              # Complete schematic design & component symbols
│   └── mfc-1.kicad_pcb              # Board layout & routing rules
├── images/                          # High-resolution prototype photography
│   ├── TOP_VIEW.png                 # Front control surface overview
│   ├── SIDE_VIEW_WITH_ANTENNA.png   # RF antenna and profile perspective
│   └── BOTTOM_VIEW.png              # Perfboard underside bus wiring
├── .gitignore                       # Clean repository filter (builds, caches, local configs)
└── README.md                        # Master engineering documentation
```

---

## Getting Started: Building the Firmware

### Prerequisites
- [ESP-IDF v5.1+](https://docs.espressif.com/projects/esp-idf/en/latest/esp32s3/get-started/) installed and exported into your environment:
  ```bash
  . $HOME/esp/esp-idf/export.sh
  ```

### Build & Flash

1. Navigate to the firmware directory:
   ```bash
   cd firmware
   ```

2. Set target to ESP32-S3:
   ```bash
   idf.py set-target esp32s3
   ```

3. Compile the firmware:
   ```bash
   idf.py build
   ```

4. Flash to the controller and open serial monitoring:
   ```bash
   idf.py -p /dev/ttyUSB0 flash monitor
   ```
   *(Replace `/dev/ttyUSB0` with your serial device node, e.g. `/dev/ttyACM0`)*.

---

## Hardware CAD & Schematic Editing

The electronic schematic is developed in **KiCad 10**:

1. Open the project:
   ```bash
   kicad hardware/mfc-1.kicad_pro
   ```
2. Inspect or modify the schematic in `eeschema` (`hardware/mfc-1.kicad_sch`).
3. To generate vector schematics for documentation or web publication:
   - Select **File $\rightarrow$ Plot $\rightarrow$ SVG** or **PDF**.

---

## Roadmap & Milestones

- [x] Initial hardware breadboard and perfboard prototype (6×9 cm assembly).
- [x] Dual-core ESP-IDF firmware setup with FreeRTOS task scheduling.
- [x] Hardware pulse-counter integration for quadrature rotary encoder (`driver/pulse_cnt.h`).
- [x] Hardware LEDC PWM audio synthesis & percussive buzzer drivers.
- [x] High-speed SPI OLED graphics driver with DMA channel support.
- [x] Addressable WS2812B NeoPixel telemetry integration.
- [ ] Custom multi-layer printed circuit board (PCB) design in KiCad.
- [ ] 3D-printable ergonomic handheld enclosure (PETG / Resin).
- [ ] Low-latency NRF24L01+ bidirectional packet protocol with ACK-payload telemetry.
- [ ] Standard USB Gamepad HID descriptor integration for plug-and-play PC gaming.

---

## Author & Project Notebook

- **Author:** [Ertunç Özbay](https://github.com/ertunc-ozbay)
- **Personal Workshop & Portfolio:** [ertuncozbay.dev](https://ertuncozbay.dev)
- **Project Detail Page:** [ertuncozbay.dev/projects/multi-functional-controller.html](https://ertuncozbay.dev/projects/multi-functional-controller.html)
- **License:** [MIT License](LICENSE)