ADD/UPD documentation and MIT license

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 OM Tom (OE3TKT)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -7,19 +7,30 @@ An open-source, international ARDF (Amateur Radio Direction Finding) timekeeping
 FoxMesh is a resilient, off-grid timing infrastructure designed for Radio Orienteering and ARDF events. By placing programmable FoxMesh nodes at the start, finish, and individual fox stations, the system automatically registers, collects, and synchronizes runner timestamps across the entire field using LoRa mesh technology.
 
 ### Key Features
-* **Automated Checkpoints:** Nodes automatically log runner punch-ins at every station.
+* **Automated Checkpoints:** Logs runner punch-ins automatically at every station.
-* **Mesh Data Sync:** No cellular network required. Timestamps are relayed from node to node back to the finish line.
+* **Mesh Data Sync:** Operates entirely without cellular networks, relaying timestamps from node to node back to the finish line.
-* **Low Power & Cost-Effective:** Built on accessible ESP32/nRF52 and LoRa hardware (similar to MeshCom/Meshtastic).
+* **Low Power & Cost-Effective:** Built on highly accessible ESP32/nRF52 and LoRa hardware (similar to MeshCom or Meshtastic).
-* **Real-time Overview:** Provides race organizers with a live status of runners currently out in the field.
+* **Real-Time Overview:** Provides race organizers with a live status monitor of runners currently out in the field.
+
+### Technical Architecture
+* **Native ESP-IDF:** Developed using the pure `espressif32` platform (v7.x release branch) without the overhead of the Arduino framework.
+* **Event-Driven Multitasking:** Built from the ground up with thread-safe, dynamically expandable libraries. Avoids CPU-heavy polling for subsystems like CLI, GNSS, or I2C.
 
 ## Hardware Support
-FoxMesh is designed to run on popular LoRa development boards:
+> ⚠️ **Note:** Hardware support is currently limited as the project is under active development. 
-* Heltec Automation (e.g., Wireless Stick V3, WiFi LoRa 32 V3)
+
-* LILYGO T-Beam / T-Deck series
+The firmware is designed to target popular LoRa development ecosystems, with primary testing and core drivers focusing on:
-* RAK Wireless WisBlock modules
+* **Heltec Automation:** Wireless Stick V3, WiFi LoRa 32 V3
+* **LILYGO:** T-Beam & T-Deck series
+* **RAK Wireless:** WisBlock modules
+
+*Contributions and hardware abstraction layer (HAL) testing for specific boards are highly welcome!*
 
 ## Getting Started
 *(Coming Soon)* Instructions on how to flash the firmware using PlatformIO and deploy the nodes in the field.
 
+## Developers
+Please refer to the documentation pages under `docs/developers/` for architecture deep-dives and contribution guidelines.
+
 ---
 Project hosted under the [f0x.at](https://f0x.at) ARDF experimentation platform.

docs/developers/coding-standards.md

@@ -0,0 +1,108 @@
+# FoxMesh Code Style and Coding Standards
+
+This document defines the strict architectural and structural coding standards for **FoxMesh**. Every contributor must adhere to these rules to guarantee clean, deterministic, and highly responsive firmware code.
+
+---
+
+## 1. General Principles
+
+* **Language:** All source code, variable names, class names, file names, and comments **must be written entirely in English**.
+* **Modern C++ Execution:** We target pure C++ implementation architectures utilizing **ESP-IDF v6.0+ (PlatformIO platform v7.x)**. 
+* **Framework Restrictions:** The Arduino framework layer is **strictly prohibited**. Only native ESP-IDF APIs are permitted.
+* **No CPU Polling:** Code must be completely event-driven or asynchronous. Traditional busy-waiting or repetitive polling loops inside worker tasks are banned. Use FreeRTOS blocking mechanisms (Queues, Notifications, Semaphores) instead.
+
+---
+
+## 2. File and Header Formats
+
+### 2.1 File Inclusions
+* Every header file (`.hpp`) must start with `#pragma once` to prevent multi-include compilation loops. Traditional `#ifndef` macro guards are deprecated.
+
+### 2.2 Standard SPDX File Header
+Every source file (`.hpp`, `.cpp`) must feature a compact, Doxygen-compliant documentation block identifying the file scope, the author **OM Tom (OE3TKT)**, and the **MIT License** via SPDX shorthand markers.
+
+```cpp
+/**
+ * @file filename.hpp
+ * @brief Concise one-line description of the file's primary hardware/software layer
+ * @author OM Tom (OE3TKT)
+ * 
+ * @license SPDX-License-Identifier: MIT
+ * @copyright Copyright (c) 2026 OM Tom (OE3TKT)
+ * For the full license terms, see the LICENSE file in the project root.
+ */
+```
+
+---
+
+## 3. Naming Conventions
+
+To guarantee readability when scanning source text, we enforce strict naming rules across distinct entity spaces:
+
+| Entity | Case Style | Example | Notes |
+| :--- | :--- | :--- | :--- |
+| **Classes & Structs** | `PascalCase` | `LedController`, `BlinkProfile` | Clear noun structures. |
+| **Methods & Functions** | `camelCase` | `startTask()`, `updateProfile()` | Action-oriented verbs. |
+| **Local Variables** | `camelCase` | `remainingLowTimeMs`, `bufferIndex` | Descriptive names. |
+| **Private Member Variables** | `m_camelCase` | `m_gpioPin`, `m_taskHandle` | Prefixed with `m_` for instant scoping. |
+| **Compile-Time Constants** | `UPPER_CASE` | `BLINK_INTERVAL_MS`, `LED_ON_MS` | Declared via `constexpr` where possible. |
+
+---
+
+## 4. FreeRTOS & Thread-Safety Rules
+
+Because FoxMesh acts as an international real-time tracking network, core memory regions must be isolated against multi-core Race Conditions:
+
+### 4.1 Cross-Thread Communication
+* Avoid simple `bool` flags or global un-mutexed variables for controlling background tasks.
+* To wake up or re-configure a sleeping/blocking task immediately, use **FreeRTOS Task Notifications** (`xTaskNotifyGive` / `ulTaskNotifyWait`).
+* For heavy data passing, use thread-safe FreeRTOS `QueueHandle_t` pipelines.
+
+### 4.2 Core Pinning Allocation
+* **Core 0:** Reserved for user-facing, asynchronous interactive modules like the Serial Console interface (`CLI`).
+* **Core 1:** Strictly reserved for timing-critical tracking execution layers, high-priority Interrupt Service Routines (ISRs), and the **Semtech LoRa Mesh network layer**.
+
+---
+
+## 5. Compiler Warnings and Type Safety
+
+Our `platformio.ini` profile forces highly aggressive compiler strictness using GCC. Code must be designed to satisfy the following rigid parameters:
+
+### 5.1 No Implicit Narrowing (`-Wconversion`)
+Implicit down-casting of numerical boundaries will drop execution blocks on the spot. You must enforce clear, deterministic size markers.
+* **Bad:** `uint8_t shortInterval = intervalMs;`
+* **Good:** `uint8_t shortInterval = static_cast<uint8_t>(intervalMs);`
+
+### 5.2 No Variable Shadowing (`-Wshadow`)
+A localized function-scope configuration parameter must never mask out an upper-tier variable state. Ensure completely unique identifier tokens across inner blocks.
+
+### 5.3 Mandatory Explicit Type Casts
+When passing numbers into standard FreeRTOS macro conversions (like `pdMS_TO_TICKS()`), ensure calculation metrics are cast beforehand if values are mixed signed/unsigned types.
+
+---
+
+## 6. Error Handling and System Stability
+
+To guarantee continuous operation during field deployment, error conditions must be handled strictly according to their severity:
+
+### 6.1 Fatal Critical Setup Errors
+* The use of Espressif's `ESP_ERROR_CHECK()` macro is **only allowed during hardware initialization** (e.g., inside `app_main` or bus allocation wrappers).
+* If a critical bus initialization fails on boot, a hardware panic/reboot via abort is acceptable to prevent running undefined node configurations.
+
+### 6.2 Dynamic Runtime Errors
+* Any error occurring during active field operations (e.g., I2C sensor timeouts, frame drop glitces, or temporary LoRa transmission failures) **must never use `ESP_ERROR_CHECK()`**.
+* Runtime anomalies must be caught defensively by checking return values (`esp_err_t == ESP_OK`), resolving them gracefully, and outputting explicit standard logging metrics via `ESP_LOGE`.
+
+---
+
+## 7. Doxygen Documentation Requirements
+
+All public APIs, public structures, and method signatures within header files must include Javadocs-style `/** ... */` annotations so that documentation engines can generate an automated index map.
+
+```cpp
+/**
+ * @brief Dynamic method modifying a running task profile state.
+ * @param profile Input mapping parameters for the new execution layer.
+ */
+void updateProfile(const BlinkProfile& profile);
+```

docs/developers/installation-vscodium.md

@@ -2,11 +2,11 @@
 
 ## Installation of VSCodium (Visual Studio Code)
 
-I prefer the installation of VSCodium, it is an excellent, privacy-focused alternative to Microsoft Visual Studio (VS Code) as it completely eliminatess telemtry, tracking, and proprietary Microsoft licenses.
+I prefer the installation of VSCodium, it is an excellent, privacy-focused alternative to Microsoft Visual Studio (VS Code) as it completely eliminates telemetry, tracking, and proprietary Microsoft licenses.
 
 However, setting up VSCodium with PlatformIO introduces a major technical hurdle:
 Microsoft explicitly restricts the use of its official C/C++ extension (ms-vscode.cpptools) to official Microsoft product distributions.
-Because PlatformIO relies heavily on this extension for code completion, debugging, and naviagation, you cannot simply download everything directly from VSCodium's default extension marketplace.
+Because PlatformIO relies heavily on this extension for code completion, debugging, and navigation, you cannot simply download everything directly from VSCodium's default extension marketplace.
 
 The following guide walks you through the proven workflows to successfully install and run PlatformIO on VSCodium.
 
@@ -18,13 +18,13 @@ This method keeps your VSCodium completely decoupled from Microsoft's marketplac
 Ensure **Python 3** and **Git** are installed on your system.
 PlatformIO uses them under the hood to manage libraries and compile code.
 
-* Linux Users: You must also install the `python3-venv` packatge via your package manager (e.g. `sudo apt install python3-venv`).
+* Linux Users: You must also install the `python3-venv` package via your package manager (e.g. `sudo apt install python3-venv`).
-On **Arch Linux** the core `python` package (installed via `sudo pacman -S python`) **already includes the standard libryre `venv` module by default**.
+On **Arch Linux** the core `python` package (installed via `sudo pacman -S python`) **already includes the standard library `venv` module by default**.
 
 ### 2. Download the Required Extensions
 
 Because of license restrictions, the required versions are not available on VSCodium's default *Open-VSX* registry.
-You need to grap them from the official Visual Studio Marketplace:
+You need to grab them from the official Visual Studio Marketplace:
 
 1. Go to the Microsoft C/C++ Extension Page.
 On the right-hand side under *Resources*, click **Download Extensions** to save the `.vsix` file.

docs/developers/troubleshooting.md

@@ -13,7 +13,9 @@ Interestingly, this error **does not occur** when triggering the build inside th
 This behavior is caused by a **Python environment collision** on your local Linux system. 
 
 * **Inside the IDE (Success):** VS Code automatically sandboxes the execution path. It activates PlatformIO's isolated virtual environment (located at `~/.platformio/penv/`), ensuring that only the internally shipped, compatible dependencies are used.
-* **Inside the System Terminal (Failure):** When calling `pio` globally, your shell utilizes the system's global Python environment. If global Python packages or system-wide SCons modules are present (e.g., installed via `apt`, `dnf`, or `pacman`), they collide with the PlatformIO Core engine. This breaks internal lookup paths, causing the compilation to miss the required `FortranCommon` module during the binary linking process.
+* **Inside the System Terminal (Failure):** When calling `pio` globally, your shell utilizes the system's global Python environment.
+If global Python packages or system-wide SCons modules are present (e.g., installed via `apt`, `dnf`, or `pacman`), they collide with the PlatformIO Core engine.
+This breaks internal lookup paths, causing the compilation to miss the required `FortranCommon` module during the binary linking process.
 
 ### Solution