# HomeHub

HomeHub is a lightweight home-automation hub for connecting local devices, running automations, and exposing a simple API for dashboards, scripts, and voice assistants.

It is designed for small homes, apartments, labs, and self-hosted setups where local control and predictable behavior matter more than cloud-only integrations.

## Features

- Local device discovery over mDNS, MQTT, and HTTP
- Rule-based automations using triggers, conditions, and actions
- Support for lights, switches, sensors, thermostats, plugs, and custom devices
- MQTT broker integration
- REST API for external tools and dashboards
- Web UI for monitoring device state and automation history
- Configurable rooms, scenes, schedules, and device groups
- Event log with automation trace output
- Optional HTTPS and token-based API authentication

## Install

### Requirements

- Node.js 20 or newer
- npm 10 or newer
- An MQTT broker, such as Mosquitto, if using MQTT devices

### From Source

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

Create a local configuration file:

```bash
cp config.example.yaml config.yaml
```

Start the hub:

```bash
npm start
```

By default, the web UI is available at:

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

## Usage

Start HomeHub in development mode:

```bash
npm run dev
```

Run with a specific config file:

```bash
homehub --config ./config.yaml
```

Check connected devices:

```bash
homehub devices
```

Run automation validation before starting:

```bash
homehub validate
```

Example automation:

```yaml
automations:
  - id: hallway-night-light
    name: Hallway night light
    trigger:
      type: motion
      device: hallway_motion
      state: detected
    conditions:
      - type: time
        after: "22:00"
        before: "06:30"
    actions:
      - type: turn_on
        device: hallway_lamp
        brightness: 35
      - type: delay
        seconds: 120
      - type: turn_off
        device: hallway_lamp
```

## Configuration

HomeHub uses a YAML configuration file. The default path is `config.yaml`.

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

security:
  apiToken: change-me
  requireAuth: true

mqtt:
  enabled: true
  url: mqtt://localhost:1883
  username: homehub
  password: example-password
  discoveryPrefix: homehub/discovery
  statePrefix: homehub/state
  commandPrefix: homehub/command

storage:
  path: ./data/homehub.db
  retainEventsDays: 30

rooms:
  - id: living_room
    name: Living Room
  - id: hallway
    name: Hallway

devices:
  - id: hallway_motion
    name: Hallway Motion Sensor
    room: hallway
    type: motion_sensor
    protocol: mqtt
    topics:
      state: sensors/hallway/motion

  - id: hallway_lamp
    name: Hallway Lamp
    room: hallway
    type: light
    protocol: mqtt
    topics:
      state: lights/hallway/state
      command: lights/hallway/set

logging:
  level: info
```

### Environment Variables

Configuration values can also be provided with environment variables:

| Variable | Description | Default |
| --- | --- | --- |
| `HOMEHUB_CONFIG` | Path to the config file | `config.yaml` |
| `HOMEHUB_HOST` | Server bind address | `0.0.0.0` |
| `HOMEHUB_PORT` | Server port | `8080` |
| `HOMEHUB_API_TOKEN` | API token used for authenticated requests | none |
| `HOMEHUB_LOG_LEVEL` | Log level: `debug`, `info`, `warn`, or `error` | `info` |

## API

List devices:

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

Turn on a device:

```bash
curl -X POST \
  -H "Authorization: Bearer $HOMEHUB_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"state":"on","brightness":80}' \
  http://localhost:8080/api/devices/hallway_lamp/state
```

## Development

Run tests:

```bash
npm test
```

Run linting:

```bash
npm run lint
```

Format code:

```bash
npm run format
```

## License

MIT