Home › Embedded / firmware › Arduino / PlatformIO rules

Arduino / PlatformIO rules

Cursor rules for microcontroller projects with PlatformIO and the Arduino framework: non-blocking loops, memory, pins.

CursorEmbedded / firmware

How to use

Save this as .cursor/rules/platformio.mdc in your repository root, commit it, and your agent will pick it up automatically. Edit the commands to match your project.

---
description: Arduino / PlatformIO conventions
globs: ["src/**/*.{cpp,h,ino}","include/**/*.h","platformio.ini"]
alwaysApply: false
---

# PlatformIO + Arduino framework

- Build with `pio run`, test with `pio test -e native` (host) or the board env; upload/monitor (`pio run -t upload`, `pio device monitor`) only when the user asks.
- Boards and libraries are declared in `platformio.ini` (`lib_deps` with pinned versions). Don't vendor libraries into `src/`.
- Code in `src/` split into modules (`sensors.cpp/.h`, `display.cpp/.h`); `main.cpp` has only `setup()` and `loop()` calling them.
- `loop()` must never block: no `delay()` beyond a few ms. Use `millis()`-based timers (`if (millis() - last >= interval)`) or a small state machine per task. Handle `millis()` rollover by subtracting, never comparing absolute times.
- Pins are named `constexpr uint8_t PIN_LED = 2;` in a `pins.h`, never magic numbers.
- Memory on small MCUs: avoid `String` concatenation in loops (heap fragmentation); use fixed `char` buffers with `snprintf`. Keep constant strings in flash (`F("...")` on AVR).
- Interrupt handlers are tiny, set `volatile` flags, and are attached with `digitalPinToInterrupt`.
- Debounce buttons in software; check sensor read return values and timeouts.
- Serial logging behind a `DEBUG` macro so release builds stay quiet.
- Secrets (Wi-Fi, API keys) in a gitignored `secrets.h` with a committed `secrets.example.h`.

## Done when
`pio run` builds every env with no warnings and RAM/flash usage from the build output is reported.