Nik Afiq
94ab7ea42b
- Added command handler for processing Discord interactions related to lights and switches. - Implemented command registration for light control commands: list, on, off, and toggle. - Created a gRPC client for communicating with the home automation gateway. - Developed application logic for handling light and switch commands, including listing, turning on/off, and toggling lights. - Introduced telemetry setup for OpenTelemetry integration. - Added configuration loading for Discord token, gateway address, and OpenTelemetry endpoint. - Defined core driven ports for interacting with the home automation gateway.
160 lines
3.6 KiB
Markdown
160 lines
3.6 KiB
Markdown
# discord-bot
|
|
|
|
`discord-bot` is a Discord slash-command service that talks to
|
|
`ha-gateway` over plaintext gRPC and exposes common Home Assistant actions in
|
|
Discord.
|
|
|
|
## How It Works
|
|
|
|
Runtime flow:
|
|
|
|
1. The bot starts a Discord session and registers slash commands.
|
|
2. A user runs a slash command such as `/light list` or `/light on`.
|
|
3. The Discord adapter routes the interaction to the app layer.
|
|
4. The app layer calls `ha-gateway` through the secondary gRPC adapter.
|
|
5. `ha-gateway` talks to Home Assistant and returns the result.
|
|
6. The bot formats the response back into a Discord message.
|
|
|
|
The service follows the same hexagonal structure as `ha-gateway`:
|
|
|
|
- `cmd/bot`: process bootstrap
|
|
- `internal/adapters/primary/discord`: slash command registration and handlers
|
|
- `internal/app`: command orchestration and response formatting
|
|
- `internal/adapters/secondary/gateway`: gRPC client for `ha-gateway`
|
|
- `internal/core/ports/driven`: app-facing gateway interface
|
|
- `internal/config`: env loading
|
|
- `internal/telemetry`: OpenTelemetry setup
|
|
|
|
## Command Behavior
|
|
|
|
- List commands respond as regular channel messages.
|
|
- Action commands use deferred ephemeral replies, then send a follow-up result.
|
|
- Light autocomplete is backed by `ListLights` from `ha-gateway`.
|
|
- Switch autocomplete support exists in code, but there is currently no switch
|
|
action command that uses it.
|
|
|
|
## Common Commands
|
|
|
|
### List lights
|
|
|
|
```text
|
|
/light list
|
|
```
|
|
|
|
Shows all discovered lights in a fixed-width block. Each line includes:
|
|
|
|
- state emoji: `🟢` on, `🔴` off, `⚠️` unavailable or other state
|
|
- friendly name
|
|
- raw state
|
|
- supported color modes
|
|
- kelvin range when available
|
|
|
|
Example output shape:
|
|
|
|
```text
|
|
🟢 Desk Lamp on color_temp,xy 2000-6535K
|
|
🔴 Closet off hs,color_temp 2202-4000K
|
|
⚠️ Hall Group unavailable color_temp 2000-6535K hue-group
|
|
```
|
|
|
|
### Turn on a light
|
|
|
|
```text
|
|
/light on light:<entity> brightness:80 color_temp:3000
|
|
```
|
|
|
|
Options:
|
|
|
|
- `light`: required, autocomplete enabled
|
|
- `brightness`: optional, `1-100`
|
|
- `color_temp`: optional, `2000-6535`
|
|
|
|
The bot responds with a confirmation such as:
|
|
|
|
```text
|
|
Turned on `Desk Lamp` (brightness 80%, 3000K).
|
|
```
|
|
|
|
### Turn off a light
|
|
|
|
```text
|
|
/light off light:<entity> transition:3
|
|
```
|
|
|
|
Options:
|
|
|
|
- `light`: required, autocomplete enabled
|
|
- `transition`: optional, `0-30` seconds
|
|
|
|
### Toggle a light
|
|
|
|
```text
|
|
/light toggle light:<entity>
|
|
```
|
|
|
|
Option:
|
|
|
|
- `light`: required, autocomplete enabled
|
|
|
|
### List switches
|
|
|
|
```text
|
|
/switch list
|
|
```
|
|
|
|
Shows discovered switches in a fixed-width block with:
|
|
|
|
- state emoji
|
|
- friendly name
|
|
- raw state
|
|
- device class
|
|
|
|
## Configuration
|
|
|
|
Environment variables:
|
|
|
|
- `DISCORD_TOKEN`: required Discord bot token
|
|
- `GUILD_ID`: optional guild ID; if set, commands are registered to that guild
|
|
- `HA_GATEWAY_ADDR`: required gRPC address for `ha-gateway`
|
|
- `OTEL_ENDPOINT`: optional OTLP gRPC endpoint; empty disables telemetry
|
|
|
|
Example env file: [`.env.example`](/Users/nik-macbookair/repo/home-service/discord-bot/.env.example)
|
|
|
|
## Local Run
|
|
|
|
Create an env file and fill in real values:
|
|
|
|
```bash
|
|
cp discord-bot/.env.example discord-bot/.env
|
|
```
|
|
|
|
Then run:
|
|
|
|
```bash
|
|
cd discord-bot
|
|
go run ./cmd/bot
|
|
```
|
|
|
|
## Build
|
|
|
|
```bash
|
|
cd discord-bot
|
|
go build ./...
|
|
```
|
|
|
|
## Docker
|
|
|
|
Build from the repo root:
|
|
|
|
```bash
|
|
docker build -f discord-bot/Dockerfile -t discord-bot:dev .
|
|
```
|
|
|
|
## Current Limitations
|
|
|
|
- no switch on/off/toggle command is exposed yet
|
|
- the bot depends on `ha-gateway` being reachable and healthy
|
|
- list formatting is optimized for monospace code blocks, not rich embeds
|
|
- authentication/authorization is whatever Discord and the internal network
|
|
provide; the bot does not add another auth layer itself
|