CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Build and Development Commands

Building the Project

# Build for the Arduino MKR WiFi 1010
pio run

# Build for a specific environment (prod, native, test, ci)
pio run -e prod   # Production build for Arduino MKR WiFi 1010
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 Arduino MKR WiFi 1010
pio run -t upload

# Clean build
pio run -t clean

Testing

# Run all tests using Docker (recommended for consistent environment)
./scripts/pio-tools.sh test

# Alternative: Run tests directly with PlatformIO
pio test -e test

# Run a specific test file
pio test -e test -f test_thermometer

Code Quality Tools

# Format code using clang-format
./scripts/pio-tools.sh format

# Run static analysis using clang-tidy
./scripts/pio-tools.sh tidy

# Run all checks (format, tidy, test) sequentially
./scripts/pio-tools.sh all

Docker Development Environment

The project uses a Docker container for development tasks. The

pio-tools.sh

script simplifies running commands:

# Build Docker image (if not already built)
docker build -t distiller-tools .

# Run a command in the Docker container
docker run -v $(pwd):/project distiller-tools [command]
# Where [command] can be: format, tidy, test, all

System Architecture

The Distiller is an automated distillation control system built for the Arduino MKR WiFi 1010. It follows a modular architecture with clear separation of concerns.

Core Components

Main Controller (main.cpp): Orchestrates the overall distillation process
Distillation State Manager: Manages the distillation process state transitions
Heater Controller: Controls heating elements at 3 power levels
Valve Controller: Manages 8 valves for different fractions and coolant
Thermometer Controller: Manages 4 temperature sensors
Scale Controller: Manages 6 weight sensors
Flow Controller: Controls flow rates using PID
Display Controller: Manages the LCD display

Hardware Abstraction Layer

Relay: Abstracts digital output pins for heaters and valves
Thermometer: Abstracts DS18B20 temperature sensors
Scale: Abstracts HX711 load cell amplifiers
LCD: Abstracts I2C LCD display

Key Design Patterns

Singleton Pattern: Used for DistillationStateManager to ensure a single source of truth
State Pattern: The distillation process is managed through a series of states
Task Scheduling: Uses TaskManagerIO for non-blocking concurrent operations
PID Control: Maintains consistent flow rates by controlling valve openings
Adapter/Delegation Pattern: Used for mocking in tests

Distillation Process Flow

The system progresses through these states automatically:

HEAT_UP → STABILIZING (when temperature > 40°C)
STABILIZING → EARLY_FORESHOTS (when temperature stabilizes)
EARLY_FORESHOTS → LATE_FORESHOTS (after 200ml)
LATE_FORESHOTS → HEADS (after 400ml)
HEADS → HEARTS (after 900ml)
HEARTS → EARLY_TAILS (after 5000ml or temperature increase)
EARLY_TAILS → LATE_TAILS (after 700ml)
LATE_TAILS → FINALIZING (after 600ml)
FINALIZING → OFF (after 10 minutes)

Testing Strategy

The project uses Google Test and Google Mock for unit testing. Tests are designed to run on the development machine, not on the Arduino hardware.

Mock Arduino Implementation

The project includes a mock Arduino implementation (

mock_arduino.h

and

mock_arduino.cpp

) that provides:

Mock implementations of Arduino functions (pinMode, digitalWrite, millis)
Helper functions for setting and advancing mock time
Test fixtures for pin operations

Unit Test Structure

Tests use conditional compilation (#ifdef UNIT_TEST) to adapt production code for testing:

Controller classes often have separate constructors for test and production environments
Hardware-dependent code is abstracted and mockable
Google Mock allows verification of hardware interactions

Testing Command Example

To run a specific test:

pio test -e test -f test_thermometer

Library Dependencies

The project uses the following Arduino libraries:

HX711 (v0.7.5): For load cell amplifiers
DallasTemperature (v3.11.0): For temperature sensors
PID (v1.2.1): For implementing PID control
hd44780 (v1.3.2): For LCD display
TaskManagerIO (v1.4.3): For task scheduling
OneWire: For OneWire devices
Wire: For I2C communication

For testing, it uses:

Google Test/Mock (v1.15.2): For unit testing

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Build and Development Commands

Building the Project

# Build for the Arduino MKR WiFi 1010
pio run

# Build for a specific environment (prod, native, test, ci)
pio run -e prod   # Production build for Arduino MKR WiFi 1010
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 Arduino MKR WiFi 1010
pio run -t upload

# Clean build
pio run -t clean

Testing

# Run all tests using Docker (recommended for consistent environment)
./scripts/pio-tools.sh test

# Alternative: Run tests directly with PlatformIO
pio test -e test

# Run a specific test file
pio test -e test -f test_thermometer

Code Quality Tools

# Format code using clang-format
./scripts/pio-tools.sh format

# Run static analysis using clang-tidy
./scripts/pio-tools.sh tidy

# Run all checks (format, tidy, test) sequentially
./scripts/pio-tools.sh all

Docker Development Environment

The project uses a Docker container for development tasks. The

pio-tools.sh

script simplifies running commands:

# Build Docker image (if not already built)
docker build -t distiller-tools .

# Run a command in the Docker container
docker run -v $(pwd):/project distiller-tools [command]
# Where [command] can be: format, tidy, test, all

System Architecture

The Distiller is an automated distillation control system built for the Arduino MKR WiFi 1010. It follows a modular architecture with clear separation of concerns.

Core Components

Main Controller (main.cpp): Orchestrates the overall distillation process
Distillation State Manager: Manages the distillation process state transitions
Heater Controller: Controls heating elements at 3 power levels
Valve Controller: Manages 8 valves for different fractions and coolant
Thermometer Controller: Manages 4 temperature sensors
Scale Controller: Manages 6 weight sensors
Flow Controller: Controls flow rates using PID
Display Controller: Manages the LCD display

Hardware Abstraction Layer

Relay: Abstracts digital output pins for heaters and valves
Thermometer: Abstracts DS18B20 temperature sensors
Scale: Abstracts HX711 load cell amplifiers
LCD: Abstracts I2C LCD display

Key Design Patterns

Singleton Pattern: Used for DistillationStateManager to ensure a single source of truth
State Pattern: The distillation process is managed through a series of states
Task Scheduling: Uses TaskManagerIO for non-blocking concurrent operations
PID Control: Maintains consistent flow rates by controlling valve openings
Adapter/Delegation Pattern: Used for mocking in tests

Distillation Process Flow

The system progresses through these states automatically:

HEAT_UP → STABILIZING (when temperature > 40°C)
STABILIZING → EARLY_FORESHOTS (when temperature stabilizes)
EARLY_FORESHOTS → LATE_FORESHOTS (after 200ml)
LATE_FORESHOTS → HEADS (after 400ml)
HEADS → HEARTS (after 900ml)
HEARTS → EARLY_TAILS (after 5000ml or temperature increase)
EARLY_TAILS → LATE_TAILS (after 700ml)
LATE_TAILS → FINALIZING (after 600ml)
FINALIZING → OFF (after 10 minutes)

Testing Strategy

The project uses Google Test and Google Mock for unit testing. Tests are designed to run on the development machine, not on the Arduino hardware.

Mock Arduino Implementation

The project includes a mock Arduino implementation (

mock_arduino.h

and

mock_arduino.cpp

) that provides:

Mock implementations of Arduino functions (pinMode, digitalWrite, millis)
Helper functions for setting and advancing mock time
Test fixtures for pin operations

Unit Test Structure

Tests use conditional compilation (#ifdef UNIT_TEST) to adapt production code for testing:

Controller classes often have separate constructors for test and production environments
Hardware-dependent code is abstracted and mockable
Google Mock allows verification of hardware interactions

Testing Command Example

To run a specific test:

pio test -e test -f test_thermometer

Library Dependencies

The project uses the following Arduino libraries:

HX711 (v0.7.5): For load cell amplifiers
DallasTemperature (v3.11.0): For temperature sensors
PID (v1.2.1): For implementing PID control
hd44780 (v1.3.2): For LCD display
TaskManagerIO (v1.4.3): For task scheduling
OneWire: For OneWire devices
Wire: For I2C communication

For testing, it uses:

Google Test/Mock (v1.15.2): For unit testing

CLAUDE.md

CLAUDE.md

Build and Development Commands

Building the Project

Testing

Code Quality Tools

Docker Development Environment

System Architecture

Core Components

Hardware Abstraction Layer

Key Design Patterns

Distillation Process Flow

Testing Strategy

Mock Arduino Implementation

Unit Test Structure

Testing Command Example

Library Dependencies

Related Skills

Markdown Converter

Nano Banana Pro

1password

CLAUDE.md

Build and Development Commands

Building the Project

Testing

Code Quality Tools

Docker Development Environment

System Architecture

Core Components

Hardware Abstraction Layer

Key Design Patterns

Distillation Process Flow

Testing Strategy

Mock Arduino Implementation

Unit Test Structure

Testing Command Example

Library Dependencies