From bcc1945868012ed89b7d659253d6d64a77e37e6b Mon Sep 17 00:00:00 2001
From: Husamettin ARABACI <harabaci88@gmail.com>
Date: Wed, 22 Oct 2025 18:41:08 +0300
Subject: [PATCH] docs(basic): added basic docs Added simple documantation for
 version v1.0.0

---
 README.md                 | 190 +++++++++++++++++++++++++++++++++++++-
 docs/ARCHITECTURE.md      | 127 +++++++++++++++++++++++++
 docs/GETTING_STARTED.md   | 108 +++++++++++++++++++++-
 docs/PROJECT_STRUCTURE.md |  83 +++++++++++++++++
 4 files changed, 505 insertions(+), 3 deletions(-)

diff --git a/README.md b/README.md
index cca41ed..720e715 100644
--- a/README.md
+++ b/README.md
@@ -3,5 +3,193 @@ SPDX-FileCopyrightText: 2025 hexaTune LLC
 SPDX-License-Identifier: MIT
 -->
 
-# hexaGenMini
+# 🎛️ hexaGenMini
+
+[![GitHub](https://img.shields.io/badge/GitHub-hTuneSys/hexagenmini-blue)](https://github.com/hTuneSys/hexaGenMini)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Rust](https://img.shields.io/badge/Rust-1.86.0-orange)](https://www.rust-lang.org/)
+[![Embassy](https://img.shields.io/badge/Embassy-0.9.0-red)](https://embassy.dev/)
+
+**hexaGenMini** is a compact, USB-powered signal generator designed for music synthesis and electronic experimentation. Built on the Raspberry Pi Pico (RP2040), it features Direct Digital Synthesis (DDS) for precise frequency generation, RGB status indication, and USB MIDI control via AT commands.
+
+Developed by **hexaTune LLC** and the **hexaTeam**, led by **Husamettin ARABACI**.
+
+## ✨ Features
+
+- **Precise Frequency Generation**: AD985x DDS chip supporting frequencies up to 125MHz
+- **USB MIDI Control**: Send AT commands via MIDI SysEx for remote control
+- **RGB Status LED**: Visual feedback for device state and DDS availability
+- **Firmware Updates**: Built-in BOOTSEL mode for easy firmware flashing
+- **Cross-Platform**: Works with any USB MIDI-compatible host
+- **Mobile App**: Control via dedicated iOS/Android app ([hexaGenApp](https://github.com/hTuneSys/hexaGenApp))
+- **Open Source**: Fully open hardware and software under MIT license
+
+## 📱 Mobile App
+
+Control your hexaGenMini wirelessly with our companion mobile app:
+
+- **iOS & Android Support**
+- **Real-time Frequency Control**
+- **Preset Management**
+- **Visual Waveform Display**
+
+[![Get it on Google Play](https://img.shields.io/badge/Get%20it%20on-Google%20Play-green)](https://play.google.com/store/apps/developer?id=hexaTune+LLC)
+[![Download on the App Store](https://img.shields.io/badge/Download%20on-the%20App%20Store-black)](https://apps.apple.com/us/developer/hexatune-llc/id1234567890)
+
+**Source Code**: [hTuneSys/hexaGenApp](https://github.com/hTuneSys/hexaGenApp)
+
+## 🚀 Quick Start
+
+1. **Connect** your hexaGenMini via USB
+2. **Flash Firmware**:
+   ```bash
+   cd firmware
+   cargo run
+   ```
+3. **Send AT Commands** via MIDI SysEx:
+   ```
+   AT+FREQ=1#1000000#1000  # Set 1MHz for 1 second
+   AT+SETRGB=2#255#0#128   # Set LED to purple
+   ```
+
+## 📦 Installation
+
+### Prerequisites
+
+- **Rust** (1.86.0+): [Install rustup](https://rustup.rs/)
+- **picotool**: For flashing RP2040
+- **Node.js & pnpm**: For development tools
+- **KiCad** (optional): For hardware modifications
+- **FreeCAD** (optional): For enclosure modifications
+
+### Setup
+
+```bash
+# Clone repository
+git clone https://github.com/hTuneSys/hexaGenMini.git
+cd hexaGenMini
+
+# Install development dependencies
+pnpm install
+pnpm prepare  # Setup husky pre-commit hooks
+
+# Install Rust targets
+rustup target add thumbv6m-none-eabi
+```
+
+### Flashing Firmware
+
+```bash
+cd firmware
+cargo run
+```
+
+Put your device in BOOTSEL mode (hold BOOTSEL while plugging in) when prompted.
+
+## 🎯 Usage
+
+### AT Command Protocol
+
+hexaGenMini uses AT commands sent via MIDI SysEx messages:
+
+#### Supported Commands
+
+- `AT+VERSION?` - Get firmware version
+- `AT+SETRGB=<ID>#<R>#<G>#<B>` - Set RGB LED color
+- `AT+FREQ=<ID>#<FREQ>#<TIME_MS>` - Generate frequency with dwell time
+- `AT+RESET=<ID>` - System reset
+- `AT+FWUPDATE=<ID>` - Enter firmware update mode
+
+#### Example Usage
+
+```bash
+# Query version
+AT+VERSION?
+
+# Set frequency to 440Hz for 5 seconds
+AT+FREQ=1#440#5000
+
+# Set LED to red
+AT+SETRGB=2#255#0#0
+```
+
+### Hardware Connections
+
+- **USB**: Power and MIDI communication
+- **SMA Output**: DDS signal output
+- **RGB LED**: Status indication
+- **BOOTSEL**: Firmware update mode
+
+## 🏗️ Architecture
+
+The firmware is built with Rust and Embassy, running concurrent async tasks:
+
+- **USB Task**: MIDI communication handling
+- **AT Dispatcher**: Command parsing and routing
+- **DDS Task**: Frequency generation control
+- **RGB Task**: LED management
+- **Main Loop**: Status monitoring
+
+For detailed architecture information, see [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md).
+
+## 📁 Project Structure
+
+```
+hexaGenMini/
+├── firmware/          # Rust firmware (Embassy framework)
+├── hardware/          # KiCad PCB designs
+├── mechanic/          # FreeCAD enclosure designs
+├── docs/             # Documentation
+├── .github/          # CI/CD workflows
+└── README.md
+```
+
+## 🤝 Contributing
+
+We welcome contributions! Please see our [Contributing Guide](docs/CONTRIBUTING.md) for details.
+
+### Development Workflow
+
+1. Fork the repository
+2. Create a feature branch from `develop`
+3. Make your changes
+4. Submit a pull request
+5. Follow conventional commit format
+
+### Areas for Contribution
+
+- Firmware enhancements
+- Hardware improvements
+- Documentation
+- Mobile app features
+- Testing and CI/CD
+
+## 📄 Documentation
+
+- [Getting Started](docs/GETTING_STARTED.md) - Setup guide
+- [Architecture](docs/ARCHITECTURE.md) - System design
+- [Project Structure](docs/PROJECT_STRUCTURE.md) - Repository overview
+- [Contributing](docs/CONTRIBUTING.md) - How to contribute
+- [FAQ](docs/FAQ.md) - Common questions
+
+## 📜 License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+
+## 📞 Contact
+
+- **Website**: [hexatune.com](https://hexatune.com)
+- **Email**: [info@hexatune.com](mailto:info@hexatune.com)
+- **GitHub**: [hTuneSys](https://github.com/hTuneSys)
+- **Issues**: [GitHub Issues](https://github.com/hTuneSys/hexaGenMini/issues)
+
+## 🙏 Acknowledgments
+
+Built with ❤️ by the hexaTeam at hexaTune LLC.
+
+Special thanks to the Rust embedded community and Embassy framework developers.
+
+---
+
+**hexaGenMini** - Precision meets portability in signal generation.
 
diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md
index 1c09c3c..50fea9c 100644
--- a/docs/ARCHITECTURE.md
+++ b/docs/ARCHITECTURE.md
@@ -14,3 +14,130 @@ Contact the team at **[info@hexatune.com](mailto:info@hexatune.com)** or open an
 ---
 
 Built by [hexaTune LLC](https://hexatune.com) · GitHub: [hTuneSys/hexaGenMini](https://github.com/hTuneSys/hexaGenMini) · License: [MIT](https://opensource.org/license/mit/)
+
+---
+
+## Overview
+
+hexaGenMini is a compact signal generator device based on the Raspberry Pi Pico (RP2040) microcontroller. It features a Direct Digital Synthesis (DDS) module for generating precise waveforms, an RGB LED for status indication, and USB MIDI communication for control. The device is designed for integration into music synthesis setups, providing frequency generation capabilities via AT command protocol over MIDI SysEx messages.
+
+## System Architecture
+
+The firmware is written in Rust using the Embassy framework for embedded async programming. It consists of several modules running as concurrent tasks on the RP2040's dual cores:
+
+- **USB Module**: Handles USB MIDI communication
+- **AT Command Module**: Parses and dispatches AT commands
+- **DDS Module**: Controls the AD985x DDS chip for frequency generation
+- **RGB Module**: Manages the WS2812 RGB LED
+- **Channel Manager**: Facilitates inter-task communication via async channels
+
+### Core 0 Tasks
+- USB Device Task
+- USB IO Task
+- AT Task
+- RGB Task
+- Main Loop Task
+
+### Core 1 Tasks
+- DDS Task
+
+## System Flow
+
+1. **Initialization**: The main function initializes peripherals, sets up channels, and spawns tasks on both cores.
+
+2. **USB Communication**: USB IO task listens for incoming MIDI packets containing SysEx messages.
+
+3. **AT Command Parsing**: Received SysEx payloads are parsed into AT commands.
+
+4. **Command Dispatch**: The AT dispatcher routes commands to appropriate handlers based on the command name.
+
+5. **Handler Execution**: Handlers perform actions like setting frequency, changing LED color, or triggering firmware updates.
+
+6. **Response Generation**: Results are compiled back into AT response format and sent via USB MIDI.
+
+## AT Command Structure
+
+AT commands follow a specific format for communication with the device:
+
+### Command Format
+```
+AT+<COMMAND>=<ID>#<PARAM1>#<PARAM2>#...
+```
+
+### Query Format
+```
+AT+<COMMAND>?
+```
+
+### Response Format
+```
+AT+<RESPONSE>=<ID>#<PARAM1>#<PARAM2>#...
+```
+
+### Supported Commands
+
+#### VERSION
+- **Query**: `AT+VERSION?`
+- **Response**: `AT+VERSION=0#v1.0.0`
+- **Description**: Returns the firmware version
+
+#### SETRGB
+- **Command**: `AT+SETRGB=<ID>#<R>#<G>#<B>`
+- **Response**: `AT+DONE=<ID>`
+- **Description**: Sets the RGB LED color (R, G, B values 0-255)
+- **Example**: `AT+SETRGB=123#255#0#128`
+
+#### RESET
+- **Command**: `AT+RESET=<ID>`
+- **Description**: Performs a system reset
+- **Note**: No response as device resets
+
+#### FWUPDATE
+- **Command**: `AT+FWUPDATE=<ID>`
+- **Description**: Enters BOOTSEL mode for firmware update
+- **Note**: No response as device enters bootloader
+
+#### FREQ
+- **Command**: `AT+FREQ=<ID>#<FREQUENCY>#<TIME_MS>`
+- **Response**: `AT+DONE=<ID>` or `AT+ERROR=<ID>#<ERROR_CODE>`
+- **Description**: Sets DDS frequency with dwell time
+- **Parameters**:
+  - FREQUENCY: Frequency in Hz (u32)
+  - TIME_MS: Dwell time in milliseconds (u32)
+- **Example**: `AT+FREQ=456#1000000#5000`
+
+### Error Codes
+- E001001: Invalid command
+- E001002: DDS busy
+- E001003: Invalid UTF-8
+- E001004: Invalid SysEx
+- E001005: Invalid data length
+- E001006: Parameter count error
+- E001007: Parameter value error
+- E001008: Not a query
+- E001009: Unknown command
+
+## Communication Protocol
+
+Commands are sent as MIDI SysEx messages over USB MIDI:
+
+- **SysEx Start**: 0xF0
+- **Payload**: UTF-8 encoded AT command string
+- **SysEx End**: 0xF7
+
+The USB MIDI implementation uses standard MIDI packet formats for SysEx transmission.
+
+## Hardware Interfaces
+
+- **USB**: Full-speed USB 2.0 for MIDI communication
+- **DDS**: AD985x controlled via GPIO bit-banging
+- **RGB LED**: WS2812 controlled via PIO
+- **Status LED**: Onboard LED for system status
+
+## Task Communication
+
+Inter-task communication uses Embassy async channels with a capacity of 16 messages per channel. The ChannelManager provides typed access to senders and receivers for each module.
+
+## Configuration
+
+System configuration is managed through constants in `hexa_config` module, including version information and DDS availability status.
diff --git a/docs/GETTING_STARTED.md b/docs/GETTING_STARTED.md
index 0f08f40..6aaa309 100644
--- a/docs/GETTING_STARTED.md
+++ b/docs/GETTING_STARTED.md
@@ -3,9 +3,113 @@ SPDX-FileCopyrightText: 2025 hexaTune LLC
 SPDX-License-Identifier: MIT
 -->
 
-# GETTING_STARTED.md
+# 🚀 Getting Started with hexaGenMini
 
-Welcome to the hexaGenMini project! This guide will help you set up your environment, build the project, and understand the basics of how to start using or contributing to hexaGenMini.
+Welcome to the hexaGenMini project! This guide will help you set up your development environment, build the project components, and get started with contributing or using hexaGenMini.
+
+## Prerequisites
+
+Before you begin, ensure you have the following installed:
+
+- **Git**: For version control
+- **Node.js** and **pnpm**: For managing development tools
+- **Rust**: For firmware development (install via rustup)
+- **KiCad**: For PCB design (optional, for hardware development)
+- **FreeCAD**: For mechanical design (optional, for enclosure design)
+- **picotool**: For flashing firmware to Raspberry Pi Pico
+
+## Project Setup
+
+1. **Clone the repository**:
+   ```bash
+   git clone https://github.com/hTuneSys/hexaGenMini.git
+   cd hexaGenMini
+   ```
+
+2. **Install dependencies**:
+   ```bash
+   pnpm install
+   ```
+
+3. **Set up pre-commit hooks**:
+   ```bash
+   pnpm prepare
+   ```
+
+## Development Areas
+
+### Firmware Development
+
+The firmware is written in Rust for the RP2040 microcontroller.
+
+1. **Navigate to firmware directory**:
+   ```bash
+   cd firmware
+   ```
+
+2. **Install Rust targets** (if not already installed):
+   ```bash
+   rustup target add thumbv6m-none-eabi
+   ```
+
+3. **Connect your hexaGenMini device** via USB and put it in BOOTSEL mode (hold BOOTSEL button while plugging in).
+
+4. **Flash and test the firmware**:
+   ```bash
+   cargo run
+   ```
+
+   This will build the firmware and flash it to the connected device.
+
+5. **Monitor output** (optional):
+   Use a tool like `minicom` or the embedded debugger to view serial output.
+
+### Hardware Development
+
+PCB designs are created with KiCad.
+
+1. **Open KiCad** and load the project:
+   - Navigate to `hardware/hexaGenMini-v1/`
+   - Open `hexaGenMini-v1.kicad_pro`
+
+2. **View schematics**:
+   - Open `hexaGenMini-v1.kicad_sch`
+
+3. **View PCB layout**:
+   - Open `hexaGenMini-v1.kicad_pcb`
+
+4. **Generate fabrication files**:
+   - Use KiCad's Plot and Drill tools to export Gerber files
+   - Fabrication outputs are pre-generated in `fabrication_output/`
+
+### Mechanical Development
+
+Enclosure designs are created with FreeCAD.
+
+1. **Open FreeCAD** and load the design files:
+   - `mechanic/Bottom.FCStd` - Bottom case
+   - `mechanic/PcbBoard.FCStd` - PCB mounting
+
+2. **Export for manufacturing**:
+   - Use FreeCAD's export tools for STL (3D printing) or DXF (laser cutting)
+
+## Testing Your Setup
+
+1. **Firmware**: After flashing, the device should blink its status LED and be detectable as a USB MIDI device.
+
+2. **AT Commands**: Use a MIDI tool to send SysEx messages with AT commands (see [ARCHITECTURE](ARCHITECTURE.md) for details).
+
+3. **Hardware**: Verify PCB connections and component placement.
+
+## Documentation
+
+For more detailed information, explore the documentation files:
+
+- [ARCHITECTURE](ARCHITECTURE.md) - System design and AT command protocol
+- [DEVELOPMENT_GUIDE](DEVELOPMENT_GUIDE.md) - Detailed development setup
+- [PROJECT_STRUCTURE](PROJECT_STRUCTURE.md) - Repository organization
+- [CONTRIBUTING](CONTRIBUTING.md) - How to contribute
+- [FAQ](FAQ.md) - Common questions
 
 ---
 
diff --git a/docs/PROJECT_STRUCTURE.md b/docs/PROJECT_STRUCTURE.md
index 2819b83..c5a763d 100644
--- a/docs/PROJECT_STRUCTURE.md
+++ b/docs/PROJECT_STRUCTURE.md
@@ -4,3 +4,86 @@ SPDX-License-Identifier: MIT
 -->
 
 # 📁 Project Structure: `hexaGenMini`
+
+This document outlines the organization of the hexaGenMini project repository.
+
+## Root Directory
+
+- `.github/`: GitHub workflows, issue templates, and configuration
+- `.husky/`: Git hooks for commit linting
+- `docs/`: Documentation files
+- `firmware/`: Embedded firmware source code (Rust)
+- `hardware/`: PCB design files (KiCad)
+- `mechanic/`: Mechanical design files (FreeCAD)
+- `LICENSE`: MIT license
+- `README.md`: Project overview
+- `package.json` & `pnpm-lock.yaml`: Node.js dependencies for tooling
+
+## Firmware Directory (`firmware/`)
+
+The firmware is written in Rust using the Embassy framework for the RP2040 microcontroller.
+
+- `src/`: Source code
+  - `main.rs`: Application entry point and task initialization
+  - `at/`: AT command parsing and handling
+  - `channel/`: Inter-task communication channels
+  - `dds/`: Direct Digital Synthesis (AD985x) control
+  - `error/`: Error definitions
+  - `hexa_config/`: Configuration constants
+  - `rgb/`: RGB LED control
+  - `sysex/`: MIDI SysEx message handling
+  - `usb/`: USB MIDI communication
+- `build.rs`: Build script for memory layout
+- `Cargo.toml`: Rust dependencies and build configuration
+- `memory.x`: Linker memory layout
+
+## Hardware Directory (`hardware/`)
+
+PCB designs created with KiCad.
+
+- `hexaGenMini-v1/`: Main PCB design
+  - `fabrication_output/`: Manufacturing files
+    - `bom/`: Bill of Materials
+    - `gerber/`: Gerber files for PCB fabrication
+    - `pnp/`: Pick and place files
+  - `*.kicad_*`: KiCad project files
+  - `PCB_Library.pretty/`: Custom KiCad footprints
+  - `SCH_Library.kicad_sym`: Custom KiCad symbols
+
+## Mechanic Directory (`mechanic/`)
+
+Mechanical designs for the product enclosure, created with FreeCAD.
+
+- `Bottom.FCStd`: Bottom case design
+- `PcbBoard.FCStd`: PCB mounting design
+- `PcbBoard-Body.dxf`: 2D export for manufacturing
+
+## Documentation (`docs/`)
+
+- `ARCHITECTURE.md`: System architecture and AT command protocol
+- `BRANCH_STRATEGY.md`: Git branching guidelines
+- `BRANDING.md`: Branding guidelines
+- `COMMIT_STRATEGY.md`: Commit message conventions
+- `COMMUNITY.md`: Community guidelines
+- `CONFIGURATION.md`: Configuration instructions
+- `CONTACT.md`: Contact information
+- `CONTRIBUTING.md`: Contribution guidelines
+- `DEVELOPMENT_GUIDE.md`: Development setup
+- `FAQ.md`: Frequently asked questions
+- `GETTING_STARTED.md`: Quick start guide
+- `LABELLING_STRATEGY.md`: Issue labeling
+- `PR_STRATEGY.md`: Pull request guidelines
+- `PROJECT_BOARD.md`: Project management
+- `PROJECT_STRUCTURE.md`: This file
+- `SECURITY.md`: Security policy
+- `STYLE_GUIDE.md`: Code style guidelines
+- `SUMMARY.md`: Project summary
+- `SUPPORT.md`: Support information
+
+## Build and Development
+
+- Firmware: Built with Cargo (Rust toolchain)
+- Hardware: Fabricated using standard PCB processes
+- Mechanics: Manufactured using 3D printing or CNC
+
+For detailed setup instructions, see `docs/DEVELOPMENT_GUIDE.md`.