# Hearth Hub

Hearth Hub is a self-hosted home-automation service that connects lights, sensors, switches, thermostats, and other smart devices behind a single local API. It provides rule-based automations, schedules, scenes, and a responsive web dashboard while keeping household data on your network.

## Features

- Local-first control with no required cloud account
- Automatic discovery for supported devices
- Rules based on device state, time, occupancy, and sensor readings
- Reusable scenes for lighting, climate, and security
- Sunrise, sunset, interval, and calendar schedules
- MQTT integration for custom hardware and existing deployments
- REST API and WebSocket event stream
- Responsive web dashboard
- Multiple homes, rooms, and user roles
- Configuration stored in readable YAML
- Docker and native installation options

## Requirements

- Node.js 20 or later
- npm 10 or later
- A Linux, macOS, or Windows host connected to the home network
- Optional: an MQTT broker such as Mosquitto
- Optional: Docker 24 or later

## Installation

### Docker

Create a directory for persistent data:

```bash
mkdir -p hearth-hub/data
cd hearth-hub
```

Create a `compose.yaml` file:

```yaml
services:
  hub:
    image: ghcr.io/hearth-hub/hearth-hub:latest
    container_name: hearth-hub
    restart: unless-stopped
    network_mode: host
    volumes:
      - ./data:/app/data
    environment:
      TZ: America/Toronto
```

Start the service:

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

Open `http://localhost:8080` and follow the setup wizard.

> Host networking is recommended because some device discovery protocols rely on multicast traffic. On systems without host networking, expose port `8080` and configure devices manually.

### Native installation

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

The dashboard is available at `http://localhost:8080`.

For development:

```bash
npm run dev
```

## Usage

### Add a device

Open **Settings → Devices → Discover** to scan the local network. Select a discovered device, assign it to a room, and give it a recognizable name.

MQTT devices can also be added manually:

```yaml
devices:
  - id: kitchen-temperature
    name: Kitchen Temperature
    room: kitchen
    adapter: mqtt
    type: temperature-sensor
    stateTopic: home/kitchen/temperature
    unit: °C
```

Restart the hub or reload the configuration after making manual changes.

### Create a scene

Scenes apply several device states at once:

```yaml
scenes:
  evening:
    name: Evening
    actions:
      - device: living-room-lamp
        state:
          power: true
          brightness: 45
          colorTemperature: 2700
      - device: hallway-light
        state:
          power: true
          brightness: 20
```

Activate the scene from the dashboard:

```bash
curl -X POST http://localhost:8080/api/scenes/evening/activate \
  -H "Authorization: Bearer $HEARTH_TOKEN"
```

### Create an automation

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

```yaml
automations:
  - id: hallway-motion-at-night
    name: Hallway motion after sunset
    enabled: true
    triggers:
      - type: state
        device: hallway-motion
        property: motion
        equals: true
    conditions:
      - type: sun
        after: sunset
        before: sunrise
    actions:
      - type: device
        device: hallway-light
        state:
          power: true
          brightness: 25
      - type: delay
        duration: 2m
      - type: device
        device: hallway-light
        state:
          power: false
```

Automations can be tested from **Automations → Run now** without waiting for their trigger.

## Configuration

The default configuration file is `data/config.yaml`. Hearth Hub creates it during the initial setup.

```yaml
server:
  host: 0.0.0.0
  port: 8080
  baseUrl: http://localhost:8080

home:
  name: Home
  latitude: 43.6532
  longitude: -79.3832
  timezone: America/Toronto

storage:
  database: data/hearth.db
  retentionDays: 30

discovery:
  enabled: true
  interval: 15m

mqtt:
  enabled: true
  url: mqtt://localhost:1883
  clientId: hearth-hub
  username: hearth
  passwordEnv: HEARTH_MQTT_PASSWORD

logging:
  level: info
  format: pretty
```

### Environment variables

Environment variables override matching YAML settings.

| Variable | Default | Description |
| --- | --- | --- |
| `HEARTH_HOST` | `0.0.0.0` | Address used by the HTTP server |
| `HEARTH_PORT` | `8080` | Dashboard and API port |
| `HEARTH_CONFIG` | `data/config.yaml` | Configuration file path |
| `HEARTH_DATA_DIR` | `data` | Persistent data directory |
| `HEARTH_LOG_LEVEL` | `info` | Logging level |
| `HEARTH_MQTT_PASSWORD` | — | MQTT broker password |
| `HEARTH_SECRET` | generated | Secret used to sign sessions and tokens |

Store secrets in environment variables instead of committing them to `config.yaml`. Use a long, random value for `HEARTH_SECRET` in production.

### Reloading configuration

Most device, scene, and automation changes can be applied without restarting:

```bash
curl -X POST http://localhost:8080/api/system/reload \
  -H "Authorization: Bearer $HEARTH_TOKEN"
```

Changes to the server address, port, database path, or encryption settings require a restart.

## Backup and Restore

Back up the entire data directory:

```bash
docker compose stop
tar -czf hearth-hub-backup.tar.gz data
docker compose start
```

To restore, stop Hearth Hub, replace the data directory with the backup contents, and start the service again.

## Security

Hearth Hub is designed for trusted local networks. If remote access is required, place it behind an authenticated HTTPS reverse proxy or a private VPN. Do not expose port `8080` directly to the public internet.

Review connected devices and active API tokens regularly under **Settings → Security**.

## Troubleshooting

View Docker logs:

```bash
docker compose logs -f hub
```

Run the built-in diagnostics:

```bash
npm run diagnose
```

If devices are not discovered, confirm that the host and devices are on the same subnet and that multicast traffic is allowed. For Docker installations, use host networking where supported.

## License

Hearth Hub is available under the MIT License. See `LICENSE` for details.