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);
+```