# Hearth Hub

Hearth Hub is a self-hosted home-automation hub that connects lights, sensors, switches, thermostats, and other smart-home devices through a single local interface. It provides device control, schedules, scenes, and event-based automations without requiring a permanent cloud connection.

## Features

- Unified dashboard for devices, rooms, and scenes
- Local-first operation with optional remote access
- Rule-based automations using triggers, conditions, and actions
- Schedules with timezone and sunrise/sunset support
- MQTT device discovery and control
- Zigbee support through Zigbee2MQTT
- Reusable scenes such as `Away`, `Movie Night`, and `Good Morning`
- Real-time device updates over WebSockets
- REST API for custom integrations
- SQLite by default, with PostgreSQL support for larger installations
- Automatic configuration backups
- Docker and native Node.js installation options

## Requirements

- Node.js 20 or later
- npm 10 or later
- Linux, macOS, or Windows
- An MQTT broker such as Mosquitto for MQTT or Zigbee devices
- Docker and Docker Compose for the recommended installation method

## Installation

### Docker Compose

Create a project directory:

```sh
mkdir hearth-hub
cd hearth-hub
```

Create a `compose.yaml` file:

```yaml
services:
  hub:
    image: ghcr.io/example/hearth-hub:latest
    container_name: hearth-hub
    restart: unless-stopped
    ports:
      - "8080:8080"
    environment:
      HEARTH_TIMEZONE: America/Toronto
      HEARTH_MQTT_URL: mqtt://mqtt:1883
    volumes:
      - ./data:/app/data
      - ./config:/app/config
    depends_on:
      - mqtt

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

Create `mosquitto.conf`:

```conf
listener 1883
allow_anonymous true
persistence true
persistence_location /mosquitto/data/
```

Start the services:

```sh
docker compose up -d
```

Open `http://localhost:8080` and follow the setup wizard to create the administrator account.

> Anonymous MQTT access is convenient for local testing but is not recommended on untrusted networks. Configure Mosquitto authentication before exposing the broker beyond your private network.

### Native Installation

Clone the repository and install dependencies:

```sh
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
```

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

For a persistent installation, run Hearth Hub under a process manager such as systemd or PM2.

## Usage

### Adding Devices

1. Open **Settings → Integrations**.
2. Enable the integration for your device protocol.
3. Put the device into pairing or discovery mode.
4. Select the discovered device and assign it to a room.
5. Give it a clear name, such as `Kitchen Ceiling` or `Front Door Sensor`.

MQTT devices can also be added manually by defining their state and command topics.

### Creating a Scene

Scenes apply several device states at once. For example, a `Movie Night` scene might dim the living-room lights, close the blinds, and turn on the television outlet.

1. Open **Scenes** and select **New Scene**.
2. Choose the devices to include.
3. Set the desired state for each device.
4. Save the scene and run it from the dashboard or an automation.

### Creating an Automation

Automations contain one or more triggers, optional conditions, and one or more actions.

Example: turn on the hallway light when motion is detected after sunset.

```yaml
name: Hallway motion after dark
enabled: true

triggers:
  - type: device_state
    device: hallway_motion
    property: motion
    equals: true

conditions:
  - type: sun
    after: sunset
    offset: "-00:15:00"

actions:
  - type: device_command
    device: hallway_light
    command: turn_on
    parameters:
      brightness: 65

  - type: delay
    duration: "00:03:00"

  - type: device_command
    device: hallway_light
    command: turn_off
```

Automations can be created in the web editor or stored as YAML files in the configured automations directory.

### REST API

After creating an API token under **Settings → Security**, devices can be controlled programmatically:

```sh
curl -X POST http://localhost:8080/api/v1/devices/kitchen-light/commands \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"command":"turn_on","parameters":{"brightness":80}}'
```

Do not store API tokens in scripts committed to source control.

## Configuration

Hearth Hub reads configuration from `config.yaml`. Environment variables override file-based settings.

```yaml
server:
  host: 0.0.0.0
  port: 8080
  public_url: http://localhost:8080
  trust_proxy: false

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

database:
  driver: sqlite
  path: ./data/hearth.db

mqtt:
  enabled: true
  url: mqtt://localhost:1883
  username: hearth
  password_file: ./secrets/mqtt-password
  client_id: hearth-hub
  discovery_prefix: homeassistant

automation:
  directory: ./config/automations
  reload_on_change: true

backups:
  enabled: true
  directory: ./data/backups
  schedule: "0 3 * * *"
  keep: 14

logging:
  level: info
  format: pretty
```

### Environment Variables

| Variable | Description | Default |
| --- | --- | --- |
| `HEARTH_HOST` | Address the HTTP server binds to | `0.0.0.0` |
| `HEARTH_PORT` | Dashboard and API port | `8080` |
| `HEARTH_TIMEZONE` | IANA timezone used by schedules | `UTC` |
| `HEARTH_DATABASE_URL` | SQLite or PostgreSQL connection URL | `sqlite:./data/hearth.db` |
| `HEARTH_MQTT_URL` | MQTT broker URL | `mqtt://localhost:1883` |
| `HEARTH_MQTT_USERNAME` | MQTT username | unset |
| `HEARTH_MQTT_PASSWORD_FILE` | File containing the MQTT password | unset |
| `HEARTH_LOG_LEVEL` | `debug`, `info`, `warn`, or `error` | `info` |
| `HEARTH_CONFIG` | Path to the main configuration file | `./config.yaml` |

### Secrets

Passwords and tokens should be supplied through secret files or environment variables. Restrict access to files containing secrets:

```sh
chmod 600 ./secrets/*
```

Avoid exposing Hearth Hub, its database, or the MQTT broker directly to the internet. For remote access, use a VPN or a reverse proxy with TLS and authentication.

## Updating

For Docker installations:

```sh
docker compose pull
docker compose up -d
```

For native installations:

```sh
git pull
npm ci
npm run build
npm run migrate
npm restart
```

Back up the `data` and `config` directories before upgrading between major versions.

## Troubleshooting

View Docker logs:

```sh
docker compose logs -f hub
```

Verify MQTT connectivity:

```sh
mosquitto_sub -h localhost -t "#" -v
```

If a device stops updating, confirm that the MQTT broker is reachable, the device topics have not changed, and the integration remains enabled. Set `logging.level` to `debug` for additional diagnostics.

## License

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