Clean up README formatting

2026-10-21 20:19:15 +03:00 · 2026-10-21 20:19:15 +03:00 · 7e5f54e025
commit 7e5f54e025
parent e56e40f576
1 changed files with 18 additions and 170 deletions
--- a/README.md
+++ b/README.md
@ -1,186 +1,34 @@
-# Multi-Functional Controller (MFC)
+# Multi-Functional 2.4 GHz RC Controller (ESP32-S3)
-[![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)
+An ESP32-S3 based handheld 2.4 GHz wireless transmitter built for controlling robotic vehicles and embedded hardware platforms. The project includes the ESP-IDF C firmware (`firmware/main/mmcontroller.c`), the KiCad schematic (`hardware/mfc-1.kicad_sch`), and prototype build photos.
 [![Controller 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/)
-## 1. Project Overview & Aim
+## Hardware Overview
- **Primary Goal:** Engineer a high-performance, bare-metal Multi-Functional Controller (**MFC**) from scratch using an **ESP32-S3-N16R8** for low-latency 2.4 GHz RF control (such as custom RC platforms) and **PC Gamepad (`USB HID / Bluetooth`)** support.
+- **MCU:** ESP32-S3 (`ESP-IDF v5.2.2`, FreeRTOS)
- **Secondary Objectives:** Extend the controller's capabilities to include a **cloud-connected AI voice assistant**, **local FAT32 SD card telemetry logging**, and **multi-transducer acoustic feedback**.
+- **Primary Controls:** Dual 2-axis Hall-effect analog gimbals read via `ADC1`
- **Tech Stack:** C/C++, ESP-IDF v5.x (FreeRTOS), bare-metal register manipulation, SPI, Hardware Pulse Counter (`PCNT`), and One-Shot `ADC1`.
+- **Channel Expansion:** 16-channel `CD74HC4067` analog/digital multiplexer (`S0..S3` on `GPIO 4, 5, 6, 7`, `SIG` on `GPIO 15`)
 - **Rotary Input:** Quadrature rotary encoder tracked with the ESP32 hardware Pulse Counter (`PCNT`) peripheral (`GPIO 16`, `GPIO 17`, switch on `GPIO 18`)
 - **RF Transceiver:** `nRF24L01+ PA+LNA` 2.4 GHz SPI module (`CSN: GPIO 10`, `CE: GPIO 9`, `SCK: GPIO 12`, `MOSI: GPIO 11`, `MISO: GPIO 13`)
 - **Display:** 0.96" `SSD1306` I2C OLED (`SDA: GPIO 8`, `SCL: GPIO 14`)
---
+## Repository Structure
-## 2. Current Situation & Early Prototype Showcase (Rev 0.1)
+- `firmware/` — ESP-IDF C source code and CMake configuration
 - `hardware/mfc-1.kicad_sch` — KiCad schematic file
 - `images/` — Breadboard prototype, schematic export, and wiring diagrams
-> [!NOTE]
+## Building the Firmware
 > **Early Prototype Notice (Rev 0.1 Carrier Build):**  
 > The photographs and schematic below represent the **very early initial stage** of the physical hardware build. At this stage, only the core carrier foundation is soldered onto the 6×9 cm perfboard: the **ESP32-S3-N16R8 microcontroller**, **nRF24L01+ 2.4 GHz radio module**, **100 µF electrolytic burst-smoothing capacitor**, **signal male pin headers**, and **power rail male headers**.  
 > The repository's firmware (`firmware/main/mmcontroller.c`) and schematic (`hardware/mfc-1.kicad_sch`) are intentionally kept matched to this verified **Rev 0.1 hardware baseline**. As the new controller modules (`1.8" ST7789 TFT`, `K-Silver PS5 Hall-Effect Joysticks`, `MicroSD`, `MAX4466`, `2N2222` buzzer stage, and enclosure) are physically integrated, both the hardware photos and firmware will be updated step-by-step.
- **Controller Prototype (Rev 0.1):** Prototyped on a **6×9 cm perfboard**. The `ESP32-S3-N16R8` communicates over a shared `SPI2_HOST` bus with a Nordic `nRF24L01+` 2.4 GHz transceiver and a temporary benchtop 1.3" SH1106 OLED display connected via the male breakout headers.
+Requires ESP-IDF v5.2.2 on Linux:
 - **Current Baseline Firmware:** A deterministic FreeRTOS state machine (`firmware/main/mmcontroller.c`) handles hardware quadrature decoding (`PCNT`) for a `KY-040` rotary encoder menu UI, `300 ms` software button debouncing, and live 2.4 GHz RF channel configuration (`0–125`).
 - **Display Hardware Pivot (`1.3" OLED` $\rightarrow$ `1.8" ST7789 TFT`):** Bench testing revealed that the 7-pin 1.3" OLED module lacks a physical Chip Select (`CS`) pin (hard-tied to GND internally), causing SPI bus collisions when sharing the bus. We are upgrading to a **1.8" ST7789 Color TFT LCD** (which exposes a dedicated hardware `CS` pin on `GPIO 10`) to share the SPI bus safely without bus contention.
 - **Manufacturing & Enclosure Status:** Paused cutting the rigid ABS plastic enclosure (`DT-100`, `190 × 137 × 59 mm`) until next month when a variable 3-speed rotary tool (`Dremel/E108`) and `2.35 mm` diamond cutting wheels arrive to ensure clean, professional cutouts without melting the ABS plastic.
 <p align="center">
  <img src="images/TOP_VIEW.png" alt="Early Prototype Rev 0.1 Top View" width="700">
  <br>
  <em><b>Figure 1 (Early Build — Rev 0.1):</b> Initial 6×9 cm perfboard carrier top view — ESP32-S3-N16R8 module, nRF24L01+ 2.4 GHz transceiver, 100 µF decoupling capacitor, peripheral male pin headers, and power rail male headers. (Will be updated as Phase 2 modules are installed).</em>
 </p>
 <p align="center">
  <img src="images/SIDE_VIEW_WITH_ANTENNA.png" alt="Early Prototype Rev 0.1 Side Profile & RF Antenna" width="700">
  <br>
  <em><b>Figure 2 (Early Build — Rev 0.1):</b> Side profile showing the external 2.4 GHz SMA dipole antenna connected to the nRF24L01+ transceiver and dual USB-C ports (Native USB-OTG & UART).</em>
 </p>
 <p align="center">
  <img src="images/BOTTOM_VIEW.png" alt="Early Prototype Rev 0.1 Underbody Perfboard Soldering" width="700">
  <br>
  <em><b>Figure 3 (Early Build — Rev 0.1):</b> Underbody point-to-point solder bridges, common ground/power rails, and shared SPI2 signal routing on the 6×9 cm perfboard.</em>
 </p>
 ### Rev 0.1 Core Carrier Schematic (`hardware/mfc-1.kicad_sch`)
 <p align="center">
  <img src="images/mfc-1.svg" alt="Rev 0.1 KiCad Schematic" width="750">
  <br>
  <em><b>Figure 4:</b> KiCad 10 schematic of the Rev 0.1 Core Carrier (`U1: ESP32-S3`, `U2: nRF24L01+`, `C1: 100 µF` decoupling capacitor).</em>
 </p>
 ---
 ## 3. Controller Hardware Architecture & Bill of Materials (BOM)
 ```mermaid
 flowchart LR
    subgraph MFC["Multi-Functional Controller (ESP32-S3-N16R8)"]
        MCU["ESP32-S3-N16R8 (FreeRTOS Dual-Core)"]
        HALL["2x K-Silver PS5 Hall-Effect Joysticks"] -->|ADC1| MCU
        MIC["MAX4466 Electret Mic Pre-Amp"] -->|ADC1| MCU
        ENC["KY-040 Rotary Encoder"] -->|Hardware PCNT| MCU
        MCU -->|SPI2_HOST + CS GPIO10| TFT["1.8-inch ST7789 Color TFT"]
        MCU -->|SPI2_HOST + CS GPIO18| SD["MicroSD Card (FAT32)"]
        MCU -->|2N2222 NPN Drivers| BUZ["1x Passive + 2x Active Buzzers"]
        MCU -->|SPI2_HOST + CSN GPIO14| NRF_TX["nRF24L01+ 2.4GHz Transceiver"]
    end
 ```
 | Subsystem | Component | Technical Details & Role | Build State |
 | :--- | :--- | :--- | :---: |
 | **MCU** | **Espressif ESP32-S3-N16R8** | Dual-core Xtensa® LX7 @ 240 MHz, 16 MB Quad SPI Flash, 8 MB Octal PSRAM. | **Installed (Rev 0.1)** |
 | **RF Telemetry** | **Nordic nRF24L01+ Module** | 2.4 GHz ISM band transceiver over shared `SPI2_HOST`. | **Installed (Rev 0.1)** |
 | **Bulk Decoupling**| **100 µF Electrolytic + Male Headers**| Suppresses nRF24 PTX current spikes; modular header rails for peripherals. | **Installed (Rev 0.1)** |
 | **Display** | **1.8" ST7789 TFT Color LCD** | 3.3V logic, full-color SPI display **with dedicated `CS` pin** (replacing 7-pin CS-less 1.3" bench OLED). | **Next Upgrade** |
 | **Joysticks** | **2× K-Silver (KS) PS5 Hall-Effect Modules** | 3.3V active magnetic contactless gimbals for zero stick drift. | **Next Upgrade** |
 | **UI Input** | **KY-040 Rotary Encoder** | Quadrature encoder (`CLK`, `DT`, `SW`) decoded in hardware via ESP32-S3 `PCNT`. | **Bench Verified** |
 | **Voice AI** | **MAX4466 Electret Microphone Module** | Analog pre-amplifier with adjustable gain for cloud-connected AI voice assistant input. | **Next Upgrade** |
 | **Data Logging** | **Arduino Micro SD Card Module** | SPI interface, formatted `FAT32` for local telemetry and configuration logging. | **Next Upgrade** |
 | **Audio Output** | **1× Passive Buzzer + 2× Active Buzzers** | Passive buzzer for melodies + 2× active buzzers for percussive UI clicks, driven by **2N2222 NPN Transistors**. | **Next Upgrade** |
 | **Enclosure** | **DT-100 Project Box** | Rigid black ABS desktop/console instrument enclosure (`190 × 137 × 59 mm`). | **Next Upgrade** |
 | **Switches** | **Waterproof Main + KTS-303 Toggle + Slide** | 12–24V illuminated push-button switch, KTS-303 3-pin toggle switch, and 180° vertical slide switch. | **Next Upgrade** |
 | **Power System** | **Dual 18650 Li-ion + TP4056 + MT3608** | Dual 18650 cells (4800 mAh), `TP4056` charger, `MT3608` DC-DC boost converter, `1N5817` Schottky & `1N4001` diodes, `100 nF` ceramic caps. | **Next Upgrade** |
 ---
 ## 4. Pinout Definitions (ESP32-S3 Controller)
 ### 4.1 Current Verified Pin Allocation (`firmware/main/mmcontroller.c`)
 | Bus / Peripheral | Signal | ESP32-S3 Pin | Interface / Mode | Notes |
 | :--- | :--- | :---: | :--- | :--- |
 | **SPI Hub (`SPI2_HOST`)** | `MOSI` | `GPIO 11` | SPI Master Output | Shared data line (`nRF24L01+`, Display `SDA`, MicroSD) |
 | **SPI Hub (`SPI2_HOST`)** | `MISO` | `GPIO 13` | SPI Master Input | Shared data input (`nRF24L01+`, MicroSD) |
 | **SPI Hub (`SPI2_HOST`)** | `SCK` | `GPIO 12` | SPI Master Clock | Shared clock line (`nRF24L01+`, Display `CLK`, MicroSD) |
 | **nRF24L01+ Radio** | `CSN` | `GPIO 14` | SPI Chip Select | Dedicated radio bus enable |
 | **nRF24L01+ Radio** | `CE` | `GPIO 21` | Digital Output | Radio TX/RX power state activation |
 | **TFT Display (1.8" ST7789)**| `CS` | `GPIO 10` | SPI Chip Select | Dedicated display bus enable |
 | **TFT Display (1.8" ST7789)**| `DC` | `GPIO 9` | Digital Output | Command vs. frame data selection |
 | **TFT Display (1.8" ST7789)**| `RES` | `GPIO 8` | Digital Output | Hardware display reset (`BLK` tied to `3.3V`) |
 | **KY-040 Rotary Encoder** | `CLK` | `GPIO 15` | Hardware `PCNT` | Quadrature channel A (1000 ns glitch filter) |
 | **KY-040 Rotary Encoder** | `DT` | `GPIO 16` | Hardware `PCNT` | Quadrature channel B (direction sensing) |
 | **KY-040 Rotary Encoder** | `SW` | `GPIO 17` | Input (`PULLUP`) | Push-button switch (300 ms software debounce) |
 | **K-Silver Hall Joystick 1**| `VRx` | `GPIO 4` | `ADC1_CH3` (`12 dB`) | Analog X-axis (0–3.3V active Hall sensor) |
 | **K-Silver Hall Joystick 1**| `VRy` | `GPIO 5` | `ADC1_CH4` (`12 dB`) | Analog Y-axis (0–3.3V active Hall sensor) |
 ### 4.2 Planned Pin Allocation for Phase 2 Modules (Safe ESP32-S3 Matrix)
 To avoid ESP32-S3 Octal Flash/PSRAM pins (`GPIO 26–37`), USB-OTG pins (`GPIO 19–20`), strapping pins (`GPIO 0, 3, 45, 46`), and `ADC2` Wi-Fi conflicts, the remaining controller modules map cleanly to:
 | Upcoming Module | Signal | Recommended GPIO | Hardware Resource |
 | :--- | :--- | :---: | :--- |
 | **K-Silver Hall Joystick 2** | `VRx2` / `VRy2` | `GPIO 6` / `GPIO 7` | `ADC1_CH5` / `ADC1_CH6` (`12 dB` Atten) |
 | **MAX4466 Microphone** | `OUT` (Analog) | `GPIO 1` | `ADC1_CH0` (DMA / Oneshot audio sampling) |
 | **Battery Sense Divider** | `VBAT_SNS` | `GPIO 2` | `ADC1_CH1` (100kΩ / 100kΩ voltage divider) |
 | **MicroSD Card Module** | `CS_SD` | `GPIO 18` | Shared `SPI2_HOST` Chip Select #3 |
 | **Passive Buzzer (Melody)** | `BUZ_PWM` | `GPIO 38` | `LEDC` Hardware Timer PWM via `2N2222` |
 | **Active Buzzers 1 & 2** | `ACT_BUZ_1/2` | `GPIO 39` / `GPIO 40`| Digital Output via `2N2222` NPN low-side switches |
 | **Toggle / Slide Switches** | `SW_MODE` | `GPIO 41` / `GPIO 42`| Digital Input (`GPIO_PULLUP_ENABLE`) |
 ---
 ## 5. Hardware Safety & Engineering Rules
 1. **Enclosure Machining RPM Rule:** Do **NOT** use standard fixed `16,000 RPM` rotary tools on the `DT-100` ABS plastic enclosure; high friction melts ABS instead of cutting it. Machining is paused until the variable 3-speed rotary tool with `2.35 mm` diamond cutting discs arrives.
 2. **Hall-Effect Gimbal Polarity Protection:** Do **NOT** wire the K-Silver (KS) PS5 Hall-effect joystick `VCC` backward. Unlike passive carbon potentiometers, these are active 3.3V CMOS magnetic sensors and will burn out immediately under reverse polarity.
 3. **nRF24L01+ Burst Decoupling:** Always keep the `100 µF` electrolytic capacitor across the `nRF24L01+` `VCC`/`GND` pins (alongside a `100 nF` ceramic cap for high-frequency noise) to prevent 3.3V rail brown-outs during PTX transmission bursts.
 4. **2N2222 Base Resistor & Flyback Protection:** Always place a **`1 kΩ` series resistor** between the ESP32-S3 GPIO pin and the Base (`B`) of each `2N2222` NPN transistor (an unresisted BJT base clamps the GPIO to `0.7V` and draws excessive current). Place a **`1N4001` flyback diode** in reverse-parallel across inductive buzzer coils.
 5. **Multi-Slave SPI Bus Initialization Rule:** When sharing `SPI2_HOST` across `nRF24L01+` (`GPIO 14`), `TFT Display` (`GPIO 10`), and `MicroSD` (`GPIO 18`), configure all three `CS` pins as outputs and drive them **HIGH (`1`)** prior to initializing the first SPI device so uninitialized slaves do not corrupt `MISO` (`GPIO 13`).
 ---
 ## 6. Immediate Next Steps & Engineering Roadmap
 1. **1.8" ST7789 TFT Migration:** Rewrite the display initialization and frame buffer logic using ESP-IDF's `esp_lcd` component to replace the custom 5×8 monochrome OLED driver once the CS-equipped TFT module is wired.
 2. **MicroSD Card SPI & FATFS Setup:** Configure the Arduino MicroSD card module on the shared SPI bus and initialize the `FATFS` virtual filesystem (`VFS`) for reading/writing telemetry logs.
 3. **NVS Hall-Effect Joystick Calibration:** Write the calibration routine for the K-Silver PS5 Hall-effect joysticks—measuring resting center, minimum, and maximum voltages and saving them persistently to ESP32-S3 Non-Volatile Storage (`NVS`) flash.
 4. **USB HID & Bluetooth Gamepad Stack:** Expose the calibrated Hall-effect axes and buttons as a standard gamepad interface over the ESP32-S3 native USB-OTG port and BLE.
 ---
 ## 7. Repository Structure & Build Instructions
 ```text
 multi-functional-controller/
 ├── firmware/                        # ESP-IDF v5.x C99 Firmware Project (ESP32-S3 Rev 0.1 Baseline)
 │   ├── CMakeLists.txt               # Top-level CMake project configuration
 │   ├── sdkconfig                    # Verified ESP32-S3 target configuration
 │   └── main/
 │       ├── CMakeLists.txt           # Component registration
 │       └── mmcontroller.c           # Master firmware: Shared SPI2, PCNT menu UI, nRF24 tuning
 ├── hardware/                        # KiCad 10 Electronic Design Automation (EDA)
 │   ├── mfc-1.kicad_pro              # KiCad project file
 │   ├── mfc-1.kicad_sch              # Rev 0.1 carrier schematic (ESP32-S3, nRF24L01+, 100uF cap)
 │   └── mfc-1.kicad_pcb              # Board layout & routing rules
 ├── images/                          # Rev 0.1 early prototype photography & vector schematic
 │   ├── TOP_VIEW.png                 # Early build (Rev 0.1) carrier top view
 │   ├── SIDE_VIEW_WITH_ANTENNA.png   # Early build (Rev 0.1) RF antenna & profile view
 │   ├── BOTTOM_VIEW.png              # Early build (Rev 0.1) perfboard underside wiring
 │   └── mfc-1.svg                    # Vector export of Rev 0.1 KiCad schematic
 ├── .gitignore                       # Clean repository filter (builds, caches, local configs)
 ├── LICENSE                          # MIT License
 └── README.md                        # Master engineering documentation
 ```
 ### Build & Flash (ESP32-S3 Controller)
 ```bash
-. $HOME/esp/esp-idf/export.sh
+source ~/esp/esp-idf/export.sh
 cd firmware
 idf.py set-target esp32s3
 idf.py build
 idf.py -p /dev/ttyACM0 flash monitor
 ```
---
+## License
-## Author & Project Links
+MIT
 - **Author:** [Ertunç Özbay](https://git.ertuncozbay.dev/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)