platformio-config

name	platformio-config
description	Applies platformio.ini and library.json conventions when creating or modifying PlatformIO C++ project and library configuration files. Covers per-board environments, build flags, pinned lib_deps, library.json metadata, the lib_deps<->dependencies mirroring rule, the main.cpp export exclusion, and library.json as the single source of the C++ library version. Use when creating or modifying these files, adding a board or dependency, or when asked about PlatformIO conventions.
user-invocable	false

PlatformIO configuration style guide

Applies conventions for the two PlatformIO configuration files a C++ microcontroller library ships: platformio.ini (local build, test, and upload configuration) and library.json (the published PlatformIO registry manifest). This is the C++ PlatformIO analogue of /pyproject-style and /tox-config.

You MUST read this skill and load the reference templates before creating or modifying either file. You MUST verify your changes against the checklist before submitting.

---

Scope

Covers:

• platformio.ini per-board [env:<board>] sections, the standard field set, build flags/unflags
• lib_deps dependency pinning and the registry-owner naming convention
• library.json metadata, headers, dependencies, export, and build fields
• The lib_deps <-> dependencies mirroring rule and per-dependency platforms scoping
• library.json version as the single source of the C++ library version

Does not cover:

• C++ source code style (see /cpp-style)
• Firmware Module/Kernel implementation (see microcontroller:firmware-module)
• Project directory structure and which files belong where (see /project-layout)
• Python pyproject.toml / tox.ini configuration (see /pyproject-style, /tox-config)

---

Workflow

You MUST follow these steps when this skill is invoked.

Step 1: Read this skill

Read this entire file. The conventions below apply to ALL ataraxis PlatformIO libraries.

Step 2: Load the reference templates

Load config-templates.md for the full annotated platformio.ini and library.json examples when creating either file from scratch or adding a board/dependency.

Step 3: Apply conventions

Write or modify the file following all conventions from this file and the loaded template. When adding or changing a dependency, apply the mirroring rule (below) to BOTH files in the same change.

Step 4: Verify compliance

Complete the verification checklist at the end of this file. Every item must pass.

---

platformio.ini conventions

platformio.ini declares one build environment per supported board. It governs local builds, unit tests, and uploads; it does NOT carry a version (the library version lives only in library.json).

Environment sections

Declare one [env:<board>] section per supported board, named for the board (teensy41, due, mega). Each section uses this field set:

Field	Convention
platform	The board's PlatformIO platform (teensy, atmelsam, atmelavr)
board	The PlatformIO board id (teensy41, due, megaatmega2560)
framework	arduino
monitor_speed	Serial monitor baud rate for that board (board-specific, e.g. 115200)
test_framework	unity
upload_protocol	Set when the board needs a non-default uploader (e.g. teensy-cli for Teensy)
build_flags	-std=c++17 (the project C++ standard)
build_unflags	Add -std=gnu++11 on boards whose Arduino core pins an older standard (AVR/SAM)
lib_deps	Pinned third-party and ataraxis dependencies (see below)

build_unflags = -std=gnu++11 is required only where the board's default toolchain would otherwise override build_flags (the AVR mega and SAM due cores); Teensy needs no unflag. Omit a field when the board does not need it (e.g. a board with no dependencies omits lib_deps entirely).

Board / platform mapping

Board id	platform
teensy41	teensy
due	atmelsam
megaatmega2560	atmelavr

lib_deps pinning

List each dependency as registry_owner/name@^MAJOR.MINOR.PATCH. The registry owner is the lowercase PlatformIO registry account, NOT the GitHub org — ataraxis libraries are published under inkaros (e.g. inkaros/ataraxis-transport-layer-mc@^3.0.0); third-party deps use their own owners (arminjo/digitalWriteFast@^1.3.1, pfeerick/elapsedMillis@^1.0.6). Use the caret (^) range so patch/minor updates are accepted. List a dependency only under the boards that need it.

---

library.json conventions

library.json is the PlatformIO registry manifest — what consumers receive when they add the library via lib_deps. Pin $schema to the official PlatformIO schema URL and order fields as in the template.

Field	Convention
$schema	https://raw.githubusercontent.com/platformio/platformio-core/develop/platformio/assets/schema/library.json
name	The library name (matches the repository)
version	The library version — the SINGLE source of truth (see Versioning)
description	One sentence, matching the README/repository description
keywords	Comma-separated discovery keywords
repository	{ "type": "git", "url": "https://github.com/Sun-Lab-NBB/<name>" }
homepage	The Netlify API-docs URL
authors	Author objects; the primary author carries "maintainer": true
license	Apache-2.0
frameworks	["arduino"]
platforms	Every platform the library supports (["atmelavr", "atmelsam", "teensy"])
headers	The PUBLIC header(s) consumers include — a string for one, an array for several
dependencies	Published dependency list — MUST mirror lib_deps (see mirroring rule)
export	include (./examples/*, ./src/*) and exclude (./src/main.cpp)
build	{ "flags": "-std=c++17" }, mirroring platformio.ini build_flags

headers

headers lists only the PUBLIC headers a consumer includes (e.g. ["kernel.h", "communication.h", "module.h", "axmc_shared_assets.h"]), not every file under src/. Use a bare string when the library exposes a single header ("transport_layer.h").

export and the main.cpp exclusion

export.include ships ./examples/* and ./src/*, and export.exclude MUST list ./src/main.cpp. src/main.cpp is the local build/test harness (see microcontroller:firmware-module) and must never be shipped to consumers, even though it lives under src/.

---

The lib_deps <-> dependencies mirroring rule

platformio.ini lib_deps (used for local builds/tests) and library.json dependencies (shipped to consumers) MUST describe the same dependency set with the same owner, name, and version. Whenever you add, remove, or re-pin a dependency, update BOTH files in the same change.

Scope each library.json dependency to the boards that need it with a platforms array that matches which [env] sections list it in lib_deps:

• A dependency in every board's lib_deps -> "platforms": ["atmelsam", "atmelavr", "teensy"].
• A dependency only in the due/mega lib_deps -> "platforms": ["atmelsam", "atmelavr"].

{ "owner": "pfeerick", "name": "elapsedMillis", "version": "^1.0.6", "platforms": ["atmelsam", "atmelavr"] }

---

Versioning

library.json version is the SINGLE source of truth for the C++ library version — releases are cut from it, and there is no Python-style single-sourcing helper. platformio.ini carries no version field. When releasing, bump library.json version (see /release).

---

pio command reference

These are the PlatformIO development-automation commands (agent-runnable, the C++ analogue of tox envs). The PR gate for a PlatformIO library is tox (docs) plus pio check and pio test.

Command	Purpose
pio project init	Scaffold/refresh the PlatformIO project from platformio.ini
pio project metadata	Emit resolved per-env build metadata (IDE/index integration)
pio run	Build the firmware/library for the selected environment(s)
pio test	Run the Unity unit tests on the selected environment(s)
pio check	Run static analysis on the source

---

Related skills

Skill	Relationship
/project-layout	Owner of where platformio.ini/library.json sit in the C++ archetypes
/cpp-style	C++ source style (scopes out these config files)
microcontroller:firmware-module	The src/main.cpp harness that export excludes and the module sources
/readme-style	C++ PlatformIO README Installation/Developers sections
/release	Uses library.json version as the C++ library release version

---

Proactive behavior

You should proactively offer to invoke this skill when:

• Creating a new PlatformIO C++ library or firmware project that needs a platformio.ini or library.json
• Adding a board environment, or adding, removing, or re-pinning a lib_deps dependency
• Releasing a C++ library (library.json version is the single source of the release version)
• The user asks about PlatformIO configuration or the lib_deps<->dependencies mirroring rule

---

Verification checklist

PlatformIO configuration:
- [ ] platformio.ini has one [env:<board>] section per supported board, named for the board
- [ ] Each env sets platform, board, framework=arduino, monitor_speed, test_framework=unity, build_flags=-std=c++17
- [ ] build_unflags=-std=gnu++11 present on AVR/SAM boards that need it; upload_protocol set where required
- [ ] lib_deps entries are pinned as registry_owner/name@^X.Y.Z (ataraxis libs under the inkaros owner)
- [ ] library.json pins $schema and orders fields per the template
- [ ] headers lists only the public consumer-facing header(s)
- [ ] export.include ships ./examples/* and ./src/*; export.exclude lists ./src/main.cpp
- [ ] library.json dependencies mirror platformio.ini lib_deps (same owner/name/version)
- [ ] each library.json dependency's platforms array matches the boards that list it in lib_deps
- [ ] library.json version is set (the single source of the C++ library version); platformio.ini has no version