From 763aea9e07851e2e0c16079e14008a7e45643c06 Mon Sep 17 00:00:00 2001
From: jlpoole <jlpoole56@gmail.com>
Date: Wed, 18 Feb 2026 11:49:50 -0800
Subject: [PATCH] Add PlatformIO

---
 PlatformIO.md | 138 ++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 138 insertions(+)
 create mode 100644 PlatformIO.md

diff --git a/PlatformIO.md b/PlatformIO.md
new file mode 100644
index 0000000..1a3293a
--- /dev/null
+++ b/PlatformIO.md
@@ -0,0 +1,138 @@
+## Build System Architecture
+
+This project is built using **PlatformIO Core (PIO)**, a Python-based embedded build system. PlatformIO manages the ESP32-S3 toolchain (compiler, linker, and associated binaries required to build firmware for a target MCU (Microcontroller Unit, here, the ESP32-S3)), Arduino framework, dependency resolution, compilation, firmware linking, device upload, and serial monitoring.
+
+The `pio` executable is the PlatformIO Command Line Interface (CLI - a text-based interface used to interact with software via typed commands, e.g. Konsole or console). It reads the `platformio.ini` configuration file and constructs isolated build environments, each representing a deterministic firmware configuration (e.g., `node_a`, `node_b`).
+
+All build artifacts are generated inside the automatically managed `.pio/` directory.  Exercise directories contain compiled objects, firmware binaries, and toolchain packages.
+
+For reproducibility, PlatformIO may be installed inside a dedicated Python virtual environment rather than relying on system-wide Python.  I recommend using a dedicated Python virtual environment.  See https://wiki.archlinux.org/title/Python/Virtual_environment
+
+---
+
+# Important Distinction
+
+PlatformIO is:
+
+* A build orchestration system
+* Toolchain manager
+* Dependency manager
+* Firmware packaging system
+
+It is not:
+
+* Just a compiler
+* Just an IDE plugin
+* Just Arduino
+# PlatformIO Core (PIO)
+
+## What “pio” Actually Is
+
+`pio` is the command-line interface (CLI) for **PlatformIO Core** (the command-line engine that performs builds and device operations.).
+
+
+### MCU
+
+Microcontroller Unit — 
+
+### Framework
+
+A software abstraction layer for embedded programming.
+In your case:
+
+* Arduino framework for ESP32
+* Could also be ESP-IDF (Espressif IoT Development Framework)
+
+### Environment (PlatformIO environment)
+
+A named build configuration block inside `platformio.ini`.
+Example:
+
+```
+[env:node_a]
+```
+
+Each environment defines:
+
+* Target board
+* Framework
+* Build flags
+* Libraries
+* Upload protocol
+
+---
+
+# How PlatformIO Actually Works Internally
+
+PlatformIO Core is written in Python. When you run:
+
+```
+pio run -e node_a
+```
+
+PlatformIO:
+
+1. Reads `platformio.ini`
+2. Determines the selected environment
+3. Installs (if necessary):
+
+   * Compiler toolchain
+   * Framework packages
+   * Python dependencies
+4. Builds firmware
+5. Places artifacts in `.pio/build/<environment>/`
+
+---
+
+# What the `.pio/` Directory Is
+
+`.pio/` is:
+
+> The build output and package cache directory managed by PlatformIO Core.
+
+It contains:
+
+* Compiled object files
+* Firmware binaries
+* Dependency builds
+* Platform packages
+* Toolchain components
+
+It is automatically generated and typically excluded from version control.
+
+---
+
+# Relationship to Python
+
+PlatformIO Core runs inside a Python environment.
+
+There are two common models:
+
+## 1. System Python (default install)
+
+PlatformIO installs into:
+
+```
+~/.platformio/
+```
+
+and uses its own managed virtual environment internally.
+
+## 2. Custom Python Virtual Environment (recommended for reproducibility)
+
+You can explicitly create a Python virtual environment in your home folder and then "source" the activate command.
+
+```
+python3 -m venv [shortname for your environment, i.e. "rnsenv" meaning Reticulum Network Server ENVironment]
+source ~.rnsenv/bin/activate
+```
+Your console will now have a visual cue that you are in your custom Python environment:
+
+Thereafter you install Python's platformio package:
+
+```pip install platformio```
+
+Note: to exit the environment, just enter: ```deactivate```.  Since your environment includes in its PATH  ~.rnsenv/bin/, the "deactivate" command will be seen.
+
+
+