# Hearth Hub

Hearth Hub is a self-hosted home-automation hub for connecting lights, sensors, switches, thermostats, and cameras through a single local dashboard. It is designed to run on a Raspberry Pi, mini PC, or home server and can automate devices without relying on cloud services.

## Features

- Local-first automation engine
- MQTT device support
- Zigbee coordinator integration
- Scene and schedule management
- Web dashboard for desktop and mobile
- Rule-based automations with conditions and actions
- Device grouping by room
- Event history and audit logs
- Optional remote access through a reverse proxy
- YAML-based configuration with environment overrides

## Install

### Requirements

- Node.js 20 or newer
- npm 10 or newer
- MQTT broker such as Mosquitto
- Optional: Zigbee USB coordinator

### From Source

```bash
git clone https://github.com/example/hearth-hub.git
cd hearth-hub
npm install
npm run build
npm start
```

The dashboard will be available at:

```text
http://localhost:8080
```

### Docker

```bash
docker run -d \
  --name hearth-hub \
  -p 8080:8080 \
  -v hearth-data:/app/data \
  -v ./config.yaml:/app/config.yaml \
  --restart unless-stopped \
  example/hearth-hub:latest
```

## Usage

Open the web dashboard and create an admin account on first launch. After setup, add integrations from the **Settings > Integrations** page.

Common workflows:

1. Add rooms such as Kitchen, Bedroom, Garage, and Office.
2. Pair or register devices.
3. Assign devices to rooms.
4. Create scenes for common states like `Movie Night` or `Away`.
5. Create automations using triggers, conditions, and actions.

Example automation:

```yaml
automations:
  - name: Turn on entry light after sunset
    trigger:
      type: motion
      device: hallway-motion
      state: detected
    conditions:
      - type: sun
        after: sunset
    actions:
      - type: device
        device: entry-light
        command: turn_on
        brightness: 70
```

## Configuration

Hearth Hub loads configuration from `config.yaml` by default. You can override the path with the `HEARTH_CONFIG` environment variable.

```bash
HEARTH_CONFIG=/etc/hearth-hub/config.yaml npm start
```

Example configuration:

```yaml
server:
  host: 0.0.0.0
  port: 8080

storage:
  path: ./data/hearth.db

mqtt:
  enabled: true
  url: mqtt://localhost:1883
  username: hearth
  password: change-me

zigbee:
  enabled: true
  adapter: /dev/ttyUSB0
  channel: 15

logging:
  level: info
  retention_days: 30
```

### Environment Variables

| Variable | Description | Default |
| --- | --- | --- |
| `HEARTH_CONFIG` | Path to the configuration file | `./config.yaml` |
| `HEARTH_PORT` | HTTP server port | `8080` |
| `HEARTH_LOG_LEVEL` | Log level: `debug`, `info`, `warn`, or `error` | `info` |
| `HEARTH_DATA_DIR` | Directory for database and runtime data | `./data` |

## License

MIT