PlatformIO Arduino Development

This skill guides Claude Code when working with Arduino firmware projects built with PlatformIO, particularly for Arduino MKR WiFi 1010 boards with automated distillation control systems.

Project Structure

The codebase follows a modular architecture with clear separation of concerns:

Build Commands

Standard Build

```bash

Build for Arduino MKR WiFi 1010

pio run

Build specific environment

pio run -e prod # Production build

pio run -e native # Native build for development

pio run -e test # Test build

pio run -e ci # CI build with warnings as errors

Upload to board

pio run -t upload

Clean build artifacts

pio run -t clean

```

Testing

```bash

Run all tests in Docker (recommended)

./scripts/pio-tools.sh test

Run tests directly

pio test -e test

Run specific test file

pio test -e test -f test_thermometer

```

Code Quality

```bash

Format code with clang-format

./scripts/pio-tools.sh format

Static analysis with clang-tidy

./scripts/pio-tools.sh tidy

Run all checks (format, tidy, test)

./scripts/pio-tools.sh all

```

Docker Development Environment

The project uses Docker for consistent development environments:

```bash

Build Docker image

docker build -t distiller-tools .

Run commands in container

docker run -v $(pwd):/project distiller-tools [command]

Where [command] is: format, tidy, test, all

```

Testing Strategy

Tests use Google Test and Google Mock with a mock Arduino implementation:

Test Structure Example

```cpp

#ifdef UNIT_TEST

// Test-specific constructor with dependency injection

Controller(MockHardware* mock) : hardware(mock) {}

#else

// Production constructor

Controller() : hardware(new RealHardware()) {}

#endif

```

Library Dependencies

Key Arduino libraries used:

Test libraries:

State Machine Pattern

Distillation processes follow a state machine:

1. HEAT_UP → STABILIZING (temp > 40°C)

2. STABILIZING → EARLY_FORESHOTS (temperature stabilizes)

3. EARLY_FORESHOTS → LATE_FORESHOTS (200ml collected)

4. LATE_FORESHOTS → HEADS (400ml collected)

5. HEADS → HEARTS (900ml collected)

6. HEARTS → EARLY_TAILS (5000ml or temperature rise)

7. EARLY_TAILS → LATE_TAILS (700ml collected)

8. LATE_TAILS → FINALIZING (600ml collected)

9. FINALIZING → OFF (10 minutes elapsed)

Design Patterns

Guidelines for Claude Code

When working with this codebase:

1. **Always run tests** after making changes to hardware controllers or state logic

2. **Use Docker tools** for consistent formatting and linting

3. **Add unit tests** for new controller methods using Google Mock

4. **Preserve hardware abstraction** when modifying controller classes

5. **Use TaskManagerIO** for any new timed or repeated operations

6. **Follow state machine** patterns when modifying process flow

7. **Test on native environment** before uploading to Arduino hardware

8. **Keep mocks updated** when changing hardware interfaces

Common Tasks

Adding a New Hardware Controller

1. Create hardware abstraction interface

2. Implement production and mock versions

3. Add controller class with conditional constructor

4. Write unit tests with Google Mock

5. Integrate with TaskManagerIO for scheduling

6. Update main controller orchestration

Modifying State Transitions

1. Update state transition logic in DistillationStateManager

2. Adjust condition thresholds if needed

3. Update tests to cover new transition conditions

4. Verify state machine flow with integration tests

Adding New Sensors

1. Add sensor abstraction in HAL

2. Create mock implementation for testing

3. Update relevant controller (Thermometer, Scale, etc.)

4. Add calibration routines if needed

5. Test with mock values before hardware integration