ADD/UPD documentation and MIT license

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`).
-On **Arch Linux** the core `python` package (installed via `sudo pacman -S python`) **already includes the standard libryre `venv` module by default**.
+* 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 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