# homebridge-plejd

HomeKit support for the Plejd BLE platform using Homebridge.

See `ARCHITECTURE.md` for full technical reference (BLE protocol, payload format, encryption, connection lifecycle, cloud API, data types, known gotchas, etc.).

## Quick Reference

```bash
npm run build      # Build TypeScript to dist/
npm test           # Run all tests
npm run test:watch # Run tests in watch mode
npm run lint       # ESLint with zero warnings policy
npm run dev        # Build, link, and run with nodemon
```

## Architecture Overview

### Source Files

| File | Purpose |
|------|---------|
| `src/index.ts` | Plugin registration entry point |
| `src/PlejdHbPlatform.ts` | Homebridge platform implementation, device discovery |
| `src/PlejdHbAccessory.ts` | Individual HomeKit accessory handler |
| `src/plejdService.ts` | BLE communication with Plejd mesh (core complexity) |
| `src/plejdApi.ts` | Plejd cloud API client for remote configuration |
| `src/utils.ts` | Crypto utilities (AES, challenge-response) and device helpers |
| `src/constants.ts` | Device model definitions and protocol constants |
| `src/model/` | TypeScript interfaces (`Device`, `Site`, `UserInputConfig`) |

### Data Flow

```
HomeKit → PlejdHbAccessory → PlejdHbPlatform → PlejdService → BLE Mesh
                                    ↑
                              PlejdRemoteApi (cloud config)
```

## Device Types

Device classification is based on `outputType`:
- `LIGHT` - Dimmable devices (Lightbulb service with brightness)
- `RELAY` - On/off switches (Switch service)

For cloud-connected users, device types are automatically determined by the Plejd API's `outputType` field.

For manual configuration, users select "Light" or "Relay" in the config UI, which maps to `outputType`.

## Coding Conventions

### TypeScript

- ES2022 target with ESM modules
- Strict mode enabled
- Use `.js` extensions in imports (for ESM compatibility)

### Style

- Zero ESLint warnings policy (`npm run lint`)
- Async/await over raw promises
- Explicit type annotations for function parameters
- Use `Result<T, E>` pattern for operations that can fail

### Testing

- Tests in `tests/*.spec.ts`
- Jest with ts-jest
- Current test files:
  - `tests/plejdService.spec.ts` - BLE service tests
  - `tests/utils.spec.ts` - Utility function tests

### Error Handling

- Use try/catch with specific error logging
- BLE operations use `race()` helper for timeout protection
- Device blacklisting for repeated failures

## Common Patterns

### Adding a New Device Type

Device classification is based on `outputType` from the Plejd API:
- `LIGHT` - Dimmable devices (Lightbulb service with brightness)
- `RELAY` - On/off switches (Switch service)

For cloud-connected users, device types are automatically determined by the Plejd API.

For manual configuration, users select "Light" or "Relay" in the config UI.

No code changes are needed for new Plejd hardware models.

### Adding a New BLE Command

1. Add command code to `PlejdCommand` enum in `src/plejdService.ts`
2. Add handler in `handleNotification()` switch statement
3. Test with actual device to verify payload format

### Adding a Configuration Option

1. Add to `PlatformConfig` interface usage in `src/PlejdHbPlatform.ts`
2. Handle in `configurePlejd()` or `configureDevices()`
3. Update plugin config schema if using Homebridge Config UI

## Related Projects

Two external repositories contain mature Plejd implementations with additional features. Consult these when implementing new functionality:

### pyplejd (Python)
Location: `../extern/pyplejd/`

Python implementation of the Plejd BLE protocol. Contains:
- Cover/blind support (`pyplejd/interface/plejd_cover.py`)
- Thermostat support (`pyplejd/interface/plejd_thermostat.py`)
- Motion sensor support (`pyplejd/interface/plejd_motion_sensor.py`)
- Button event handling (`pyplejd/interface/plejd_button.py`)
- BLE payload encoding (`pyplejd/ble/payload_encode.py`)

### hass-plejd (Home Assistant)
Location: `../extern/hass-plejd/`

Home Assistant custom component. Contains:
- Climate entities (`custom_components/plejd/climate.py`)
- Cover entities (`custom_components/plejd/cover.py`)
- Binary sensors (`custom_components/plejd/binary_sensor.py`)
- Sensors (`custom_components/plejd/sensor.py`)
- Event handling (`custom_components/plejd/event.py`)

These implementations have features not yet ported to homebridge-plejd due to lack of test hardware.