# Emberleaf

Emberleaf is a lightweight controller and roast logger for small-batch tea roasting. It helps home producers and tea studios run repeatable roast profiles, monitor temperature, record batch notes, and export roast history.

> Emberleaf can control heating equipment. Never leave a roast unattended, and always use hardware-rated safety cutoffs.

## Features

- Create reusable temperature and duration profiles
- Monitor bean temperature and heater output in real time
- Support manual and automatic roast modes
- Record tea origin, cultivar, harvest, weight, and tasting notes
- Export batch history as CSV or JSON
- Connect to supported USB serial temperature controllers
- Simulate hardware for profile testing

## Install

Emberleaf requires Python 3.11 or later.

```bash
git clone https://github.com/example/emberleaf.git
cd emberleaf
python -m venv .venv
source .venv/bin/activate
pip install -e .
```

On Windows:

```powershell
.venv\Scripts\activate
pip install -e .
```

Verify the installation:

```bash
emberleaf --version
```

## Usage

Create a configuration file:

```bash
emberleaf init
```

List available roast profiles:

```bash
emberleaf profiles
```

Run a roast in simulation mode:

```bash
emberleaf roast profiles/oolong-finish.yaml --simulate
```

Start a live roast:

```bash
emberleaf roast profiles/oolong-finish.yaml \
  --tea "Spring Tieguanyin" \
  --weight 250
```

A profile contains one or more timed stages:

```yaml
name: Oolong Finish
description: Gentle finishing roast for rolled oolong
stages:
  - name: Warm
    target_c: 85
    duration: 10m
  - name: Develop
    target_c: 105
    duration: 25m
  - name: Finish
    target_c: 115
    duration: 8m
  - name: Cool
    target_c: 35
    duration: 12m
    heater: false
```

Review recent batches:

```bash
emberleaf history --limit 10
```

Export roast records:

```bash
emberleaf export --format csv --output roasts.csv
```

## Configuration

By default, Emberleaf reads `emberleaf.yaml` from the current directory. Use `--config` to specify another file.

```yaml
roaster:
  name: Workshop Roaster
  capacity_g: 500
  controller:
    type: serial
    port: /dev/ttyUSB0
    baud_rate: 9600
  temperature:
    unit: celsius
    sample_interval_ms: 1000
    maximum_c: 160
  safety:
    emergency_cutoff_c: 170
    sensor_timeout_seconds: 5

storage:
  database: ./data/emberleaf.sqlite3
  export_directory: ./exports

logging:
  level: info
  file: ./logs/emberleaf.log
```

Common settings:

| Setting | Description | Default |
| --- | --- | --- |
| `roaster.capacity_g` | Maximum batch weight in grams | `500` |
| `controller.port` | Serial device connected to the controller | Auto-detected |
| `temperature.sample_interval_ms` | Temperature polling interval | `1000` |
| `temperature.maximum_c` | Highest selectable profile temperature | `160` |
| `safety.emergency_cutoff_c` | Temperature that forces heater shutdown | `170` |
| `safety.sensor_timeout_seconds` | Delay before shutdown after sensor loss | `5` |
| `storage.database` | SQLite roast-history database | `./data/emberleaf.sqlite3` |
| `logging.level` | Log verbosity: `debug`, `info`, `warning`, or `error` | `info` |

Configuration values can also be overridden with environment variables:

```bash
export EMBERLEAF_CONTROLLER_PORT=/dev/ttyACM0
export EMBERLEAF_LOG_LEVEL=debug
emberleaf roast profiles/oolong-finish.yaml
```

## Safety

Use an independent thermal fuse or hardware cutoff appropriate for your roaster. Software safeguards are supplemental and must not be treated as the only protection against overheating, fire, or equipment failure.