# HomeHub

HomeHub is a lightweight home-automation hub for connecting smart lights, switches, sensors, thermostats, cameras, and custom MQTT devices from a single local dashboard.

## Features

- Local-first automation engine
- Device discovery over MQTT, Zigbee2MQTT, and HTTP
- Rules based on time, device state, occupancy, and sensor values
- Web dashboard for rooms, scenes, and automations
- REST API for integrations and scripting
- Optional cloud webhook support
- User roles for admins and viewers
- Event history with configurable retention

## Install

### Requirements

- Node.js 20+
- npm 10+
- MQTT broker such as Mosquitto
- Optional: Zigbee2MQTT for Zigbee devices

### Setup

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

The dashboard will be available at:

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

## Usage

Start HomeHub:

```bash
npm start
```

Run in development mode:

```bash
npm run dev
```

Add a device by editing `config.yml` or by enabling discovery in the dashboard.

Example automation:

```yaml
automations:
  - name: Turn on hallway lights after sunset
    when:
      type: sun
      event: sunset
      offset: "-00:15"
    if:
      - device: motion_hallway
        state: occupied
        equals: true
    then:
      - device: hallway_lights
        action: turn_on
        brightness: 70
```

## Configuration

HomeHub uses `config.yml` in the project root by default.

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

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

database:
  path: ./data/homehub.sqlite
  retention_days: 30

security:
  session_secret: change-this-secret
  require_login: true

location:
  latitude: 40.7128
  longitude: -74.0060
  timezone: America/New_York
```

Configuration can also be provided with environment variables:

```bash
HOMEHUB_CONFIG=/etc/homehub/config.yml npm start
```

Common options:

| Option | Description |
| --- | --- |
| `server.port` | Port for the web dashboard and API |
| `mqtt.url` | MQTT broker connection URL |
| `mqtt.discovery` | Enables automatic MQTT device discovery |
| `database.path` | SQLite database file location |
| `database.retention_days` | Number of days to keep event history |
| `security.require_login` | Requires authentication for dashboard access |
| `location.timezone` | Timezone used for schedules and sun events |

## License

MIT