Industrial icemaker control system with async FSM, physics-based simulation, and React dashboard.

• Async State Machine: Event-driven FSM controlling the ice-making cycle (CHILL → ICE → HEAT → repeat)
• Hardware Abstraction: Supports real Raspberry Pi GPIO/sensors or mock implementations for development
• Physics-Based Simulator: Realistic thermal model for testing without hardware
• REST + WebSocket API: Real-time state updates and control via FastAPI
• React Dashboard: Live temperature charts, relay status, and cycle control

┌─────────────────────────────────────────────────────────────┐
│                     React Frontend                          │
│  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐       │
│  │  State   │ │  Temp    │ │  Relay   │ │ Controls │       │
│  │ Display  │ │  Chart   │ │  Status  │ │          │       │
│  └──────────┘ └──────────┘ └──────────┘ └──────────┘       │
└─────────────────────────┬───────────────────────────────────┘
                          │ WebSocket + REST
┌─────────────────────────┴───────────────────────────────────┐
│                     FastAPI Backend                         │
│  ┌──────────────────────────────────────────────────────┐  │
│  │                    Controller                         │  │
│  │  ┌─────────┐  ┌─────────────┐  ┌─────────────────┐   │  │
│  │  │   FSM   │  │    HAL      │  │ Thermal Model   │   │  │
│  │  │ States  │  │ GPIO/Sensors│  │   (Simulator)   │   │  │
│  │  └─────────┘  └─────────────┘  └─────────────────┘   │  │
│  └──────────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────────┘

• Python 3.9+
• Node.js 18+ (for frontend development)
• uv (recommended) or pip

The easiest way to get started is using the setup script:

# Clone the repository
git clone <repo-url>
cd icemaker

# Run setup (auto-detects platform)
./setup.sh

The setup script will:

• Detect if running on Raspberry Pi or development machine
• Install uv if not present (or fall back to pip)
• Install appropriate dependencies (including RPi.GPIO on Pi)
• Create .env with correct environment settings

# With uv (recommended)
uv run python -m icemaker

# Or with virtual environment
source .venv/bin/activate
python -m icemaker

# Terminal 1: Start backend with simulator
uv run python -m icemaker --simulator

# Terminal 2: Start frontend dev server
cd frontend && npm run dev

Open http://localhost:5173 to view the dashboard.

git clone <repo-url> icemaker
cd icemaker
./setup.sh --service

This installs dependencies and sets up a systemd service that starts on boot.

sudo systemctl start icemaker    # Start the service
sudo systemctl stop icemaker     # Stop the service
sudo systemctl status icemaker   # Check status
journalctl -u icemaker -f        # View logs

By default, the water priming sequence is skipped on startup (assumes the system is already primed). To run the priming sequence on first boot:

# One-time priming
ICEMAKER_PRIMING_ENABLED=true uv run python -m icemaker

# Or set in config/production.yaml:
# startup:
#   priming_enabled: true

# Upgrade pip and install
pip install --upgrade pip
pip install ".[rpi]"

# Set environment
export ICEMAKER_ENV=production

# Run
python -m icemaker

icemaker/
├── setup.sh               # Automated setup script
├── config/                # YAML configuration files
│   ├── default.yaml       # Default settings
│   ├── development.yaml   # Dev environment (simulator enabled)
│   └── production.yaml    # Production settings (real hardware)
├── src/icemaker/
│   ├── core/              # FSM, states, events, controller
│   ├── hal/               # Hardware abstraction layer
│   ├── simulator/         # Physics-based thermal model
│   └── api/               # FastAPI routes and WebSocket
├── tests/
│   ├── unit/              # Unit tests
│   └── integration/       # Integration tests
└── frontend/              # React + TypeScript dashboard

The system follows this state flow:

1. OFF - System powered off (initial state)
2. POWER_ON - Water priming sequence (optional, skipped by default)
3. STANDBY - Ready, waiting for manual start

4. CHILL (prechill) - Cool plate to 32°F
5. ICE - Make ice at -2°F with water recirculation
6. HEAT - Harvest ice by heating plate to 38°F
7. CHILL (rechill) - Cool to 35°F before next cycle
8. Check bin:
   • If full → IDLE (auto-restarts when bin empties)
   • If not full → repeat from step 4

Configuration is loaded from YAML files with environment variable overrides:

• config/default.yaml - Base defaults
• config/development.yaml - Development settings (simulator enabled)
• config/production.yaml - Production settings (matches hardware values)

# Run all tests
uv run pytest tests -v

# Run unit tests only
uv run pytest tests/unit -v

# Run integration tests only
uv run pytest tests/integration -v

# Run with coverage
uv run pytest tests --cov=icemaker

MIT