# Hearth Hub

Hearth Hub is a self-hosted home-automation service that connects lights, switches, sensors, thermostats, and other smart devices through a single local interface. It provides a web dashboard, automation rules, schedules, and an HTTP API without requiring a cloud account.

## Features

- Local-first device control and automation
- Responsive web dashboard
- Rules based on device state, time, sunrise, and sunset
- Scenes for coordinating multiple devices
- Real-time updates over WebSockets
- MQTT device discovery and messaging
- REST API for custom integrations
- Persistent event and state history
- Optional remote access behind a reverse proxy
- Docker and native installation options

## Requirements

- Node.js 20 or later
- npm 10 or later
- An MQTT broker such as Mosquitto
- SQLite 3

## Installation

### Docker Compose

Create a `compose.yaml` file:

```yaml
services:
  hearth:
    image: ghcr.io/example/hearth-hub:latest
    restart: unless-stopped
    ports:
      - "8080:8080"
    environment:
      HEARTH_CONFIG: /data/config.yaml
    volumes:
      - ./data:/data
    depends_on:
      - mqtt

  mqtt:
    image: eclipse-mosquitto:2
    restart: unless-stopped
    ports:
      - "1883:1883"
    volumes:
      - ./mosquitto.conf:/mosquitto/config/mosquitto.conf
```

Create `mosquitto.conf`:

```conf
listener 1883
allow_anonymous true
```

Start the services:

```bash
docker compose up -d
```

Open `http://localhost:8080` to complete setup.

> Anonymous MQTT access is convenient for local testing but is not recommended on an untrusted network.

### From Source

```bash
git clone https://github.com/example/hearth-hub.git
cd hearth-hub
npm ci
cp config.example.yaml config.yaml
npm run build
npm start
```

By default, Hearth Hub listens on port `8080` and stores its database in `./data/hearth.db`.

## Usage

### Add a Device

Devices that support MQTT discovery appear automatically in **Settings → Devices**. To add a device manually:

1. Open **Settings → Devices**.
2. Select **Add device**.
3. Choose a device type.
4. Enter its MQTT state and command topics.
5. Select **Save**.

### Create a Scene

Scenes set several devices to predefined states. For example, a “Movie Night” scene might dim the living-room lights, close the blinds, and turn on the television outlet.

Create scenes from **Automation → Scenes**, or define them in `config.yaml`.

### Create an Automation

The following automation turns on the porch light when motion is detected after sunset:

```yaml
automations:
  - id: porch-motion
    name: Porch light on motion
    when:
      - device: porch-motion
        state: detected
    conditions:
      - after: sunset
      - before: "23:30"
    actions:
      - device: porch-light
        set:
          power: true
      - delay: 5m
      - device: porch-light
        set:
          power: false
```

After changing the configuration, reload it without restarting:

```bash
curl -X POST http://localhost:8080/api/config/reload
```

### REST API

Get the current state of all devices:

```bash
curl http://localhost:8080/api/devices
```

Turn on a device:

```bash
curl -X PUT http://localhost:8080/api/devices/kitchen-light/state \
  -H "Content-Type: application/json" \
  -d '{"power":true}'
```

When authentication is enabled, include an API token:

```bash
curl http://localhost:8080/api/devices \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```

## Configuration

Hearth Hub reads configuration from `config.yaml`. Set `HEARTH_CONFIG` to use a different path.

```yaml
server:
  host: 0.0.0.0
  port: 8080
  base_url: http://localhost:8080
  trusted_proxies: []

database:
  path: ./data/hearth.db
  retention_days: 30

mqtt:
  url: mqtt://localhost:1883
  client_id: hearth-hub
  username: null
  password: null
  discovery_prefix: homeassistant

location:
  latitude: 43.6532
  longitude: -79.3832
  timezone: America/Toronto

security:
  authentication: true
  session_secret: change-me
  api_tokens: []

logging:
  level: info
  format: pretty
```

### Environment Variables

Environment variables override values from `config.yaml`.

| Variable | Description | Default |
|---|---|---|
| `HEARTH_CONFIG` | Configuration file path | `./config.yaml` |
| `HEARTH_HOST` | Address to listen on | `0.0.0.0` |
| `HEARTH_PORT` | HTTP port | `8080` |
| `HEARTH_DATABASE_PATH` | SQLite database path | `./data/hearth.db` |
| `HEARTH_MQTT_URL` | MQTT broker URL | `mqtt://localhost:1883` |
| `HEARTH_MQTT_USERNAME` | MQTT username | Not set |
| `HEARTH_MQTT_PASSWORD` | MQTT password | Not set |
| `HEARTH_LOG_LEVEL` | Logging level | `info` |

### Secrets

Do not commit credentials or tokens to source control. In production, supply secrets through environment variables, Docker secrets, or a protected environment file.

If Hearth Hub is exposed outside your local network, place it behind an HTTPS reverse proxy, enable authentication, use a strong session secret, and secure the MQTT broker with credentials and network restrictions.