Feat/telemetry i2c

Telemetry/README.md

@@ -0,0 +1,131 @@
+# Telemetry_V1 – Project Layout
+
+This project separates **generated code** (Harmony/MPLAB X) from **hand-written code**.  
+Your own modules live at the project root **outside** the `.X` folder.
+
+```
+Telemetry_V1/
+├─ Telemetry_V1.X/           # MPLAB X project metadata & build configs (IDE files)
+├─ src/                      # Harmony-generated sources (owned by generator)
+│  └─ config/                # Board/peripheral init generated by MHC
+├─ app/                      # Your application layer
+│  ├─ include/               # Public app headers
+│  └─ src/                   # App .c files (main loop, tasks, state machines)
+├─ drivers/                  # Reusable drivers you own
+│  └─ ws2812/
+│     ├─ include/            # Public headers (e.g., ws2812_spi_enc.h)
+│     └─ src/                # Driver sources (e.g., ws2812_spi_enc.c)
+├─ utils/                    # Shared helpers (no board dependencies)
+│  ├─ include/               # Public helper headers
+│  └─ src/                   # Helper sources
+└─ README.md                 # This file
+```
+
+## Folder purposes
+
+### `Telemetry_V1.X/`
+- **Do not put hand-written code here.**
+- MPLAB X / nbproject metadata, build configs, linker settings, Harmony artifacts.
+- Contents may be modified automatically by the IDE/generator.
+
+### `src/` (generated)
+- Harmony/MHC generated startup and peripheral init code.
+- Generally **do not edit**; re-run the generator to change configuration.
+- `src/config/` contains SERCOM/clock/pin setup your code will use.
+
+### `app/`
+- Your application logic.
+- `include/`: public app headers (APIs, types).
+- `src/`: implementations—`main.c`, tasks, schedulers, state machines.
+
+### `drivers/`
+- Encapsulated modules interfacing hardware or external parts.
+- Each driver has its own subfolder with `include/` and `src/`.
+- Example: `drivers/ws2812/` (SPI encoder for WS2812B).
+
+### `utils/`
+- Generic helpers (timers, ring buffers, math, logging).
+- No board/peripheral dependencies; safe to include anywhere.
+
+## Include paths (MPLAB X v6.20)
+
+Add header search paths so the compiler can find your module headers.
+
+**C compiler (xc32-gcc):**
+1) Right-click project → **Properties**.  
+2) Under **Conf: [your config] → XC32 (vX.Y.Z)**, select **xc32-gcc**.  
+3) Set **Option categories** = **Preprocessing and messages**.  
+4) **Include directories (-I)** → **…** → add (one per line):
+   - `app/include`
+   - `drivers/ws2812/include`
+   - `drivers/wsen_pads/include` *(add any other driver include paths)*
+   - `utils/include`
+5) **OK** → **Apply**.
+
+**If you also build C++:** repeat under **xc32-g++**.
+
+**Can’t find the field?** As a fallback, put this in **xc32-gcc → General → Additional options**:
+
+
+**Usage in code (no `../` needed):**
+```c
+#include "ws2812_spi_enc.h"
+#include "wsen_pads.h"
+#include "ringbuf.h"
+
+## Adding files to the project (logical view)
+- Right-click **Header Files** → *Add Existing Item…* → select files under any `*/include`.
+- Right-click **Source Files** → *Add Existing Item…* → select files under any `*/src`.
+- The IDE’s logical folders don’t need to mirror disk exactly, but keeping them aligned helps.
+
+## Build & ownership rules
+- Generated code in `src/config/...` is **owned by the generator**.
+- Your code in `app/`, `drivers/`, `utils/` is **owned by you**.
+- Don’t edit generated files; instead change Harmony settings or wrap/extend from your modules.
+
+## Naming & style (suggested)
+- Lowercase file names with underscores: `ws2812_spi_enc.c`, `app_config.h`.
+- Public headers live in `include/`; private headers use `*_priv.h` in `src/`.
+- Prefix symbols by module: `ws2812_…`, `util_…`, `app_…`.
+
+## Example: WS2812 driver
+- Header: `drivers/ws2812/include/ws2812_spi_enc.h`
+- Source: `drivers/ws2812/src/ws2812_spi_enc.c`
+- Pair with SERCOM SPI ≈ 2.4 MHz (Mode 0) and continuous TX (DMA or tight loop).
+
+---
+
+## How to add a **new driver** (step-by-step)
+
+1) **Create folders on disk**
+```
+drivers/<driver_name>/
+  include/
+  src/
+```
+
+2) **Add your files**
+- Public API header → `drivers/<driver_name>/include/<driver_name>.h`
+- Implementation(s) → `drivers/<driver_name>/src/<driver_name>.c`
+- Optional internal header → `drivers/<driver_name>/src/<driver_name>_priv.h` (not exported)
+
+3) **Add to project (logical view)**
+- Right-click **Header Files** → *Add Existing Item…* → pick files from `drivers/<driver_name>/include/`
+- Right-click **Source Files** → *Add Existing Item…* → pick files from `drivers/<driver_name>/src/`
+
+4) **Expose headers to the compiler**
+- Project Properties → **Include directories** → add `drivers/<driver_name>/include`
+
+5) **Use it in code**
+```c
+#include "<driver_name>.h"
+```
+- Call the driver’s `init()` from your app startup (e.g., after Harmony `SYS_Initialize()`).
+- Link any ISR hooks or callbacks the driver requires (e.g., DMAC, SERCOM events).
+
+6) **Keep dependencies clean**
+- The driver should not include app files; export only what’s needed via its public header.
+- If the driver needs board pins/config, pass them in via an `init()` struct instead of including generated headers.
+
+7) **Version control**
+- Commit the new `drivers/<driver_name>/...` tree and the updated project settings (the `.X` metadata will record added files and include paths).