# HomeHub

HomeHub is a lightweight home-automation hub for connecting local devices, cloud services, and custom automations from a single dashboard. It is designed to run on a Raspberry Pi, home server, or small always-on machine.

## Overview

HomeHub provides a local-first control plane for lights, sensors, switches, thermostats, cameras, and automation rules. It exposes a web dashboard, REST API, MQTT bridge, and rule engine so devices from different ecosystems can work together without depending on a single vendor.

## Features

- Local web dashboard for rooms, devices, scenes, and automations
- MQTT support for sensors, switches, and custom integrations
- Device discovery for common LAN-based smart devices
- Rule engine with triggers, conditions, schedules, and actions
- Scene support for grouped device states
- User accounts with role-based access
- Optional cloud webhook support for remote integrations
- Event history and device state logging
- Backup and restore for configuration
- Docker and bare-metal installation support

## Install

### Requirements

- Node.js 20+
- SQLite 3
- MQTT broker such as Mosquitto
- Linux, macOS, or Raspberry Pi OS

### Docker

```bash
docker run -d \
  --name homehub \
  -p 8080:8080 \
  -v homehub-data:/data \
  -e HOMEHUB_CONFIG=/data/config.yml \
  ghcr.io/example/homehub:latest
```

Open the dashboard at:

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

### From Source

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

## Usage

Start the server:

```bash
npm start
```

Run in development mode:

```bash
npm run dev
```

Create an admin user:

```bash
npm run user:create -- --email admin@example.com --role admin
```

Add an MQTT device by publishing discovery metadata:

```bash
mosquitto_pub -t homehub/discovery/kitchen-light/config -m '{
  "name": "Kitchen Light",
  "type": "switch",
  "state_topic": "home/kitchen/light/state",
  "command_topic": "home/kitchen/light/set"
}'
```

Example automation:

```yaml
automations:
  - name: Turn on hallway at sunset
    trigger:
      type: sun
      event: sunset
    condition:
      type: occupancy
      room: hallway
      state: occupied
    action:
      type: device.set
      device: hallway-light
      state:
        power: true
        brightness: 70
```

## Configuration

HomeHub reads configuration from `config.yml` by default. Set `HOMEHUB_CONFIG` to use a different file.

```yaml
server:
  host: 0.0.0.0
  port: 8080
  public_url: http://homehub.local:8080

database:
  path: /data/homehub.sqlite

mqtt:
  url: mqtt://localhost:1883
  username: homehub
  password: change-me
  discovery_prefix: homehub/discovery

auth:
  session_secret: replace-with-a-long-random-value
  allow_registration: false

logging:
  level: info
  retain_days: 30

integrations:
  weather:
    provider: open-meteo
    latitude: 40.7128
    longitude: -74.0060

backup:
  enabled: true
  directory: /data/backups
  schedule: "0 3 * * *"
```

Common environment variables:

| Variable | Description | Default |
| --- | --- | --- |
| `HOMEHUB_CONFIG` | Path to the YAML configuration file | `./config.yml` |
| `HOMEHUB_DATA_DIR` | Directory for database, uploads, and backups | `./data` |
| `HOMEHUB_LOG_LEVEL` | Log level: `debug`, `info`, `warn`, or `error` | `info` |
| `HOMEHUB_PORT` | HTTP server port | `8080` |

## License

MIT