67 lines
2.4 KiB
Markdown
67 lines
2.4 KiB
Markdown
# CLAUDE.md
|
|
|
|
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
|
|
|
## Project Overview
|
|
|
|
ioBroker.hass is an ioBroker adapter that connects Home Assistant to ioBroker via WebSocket API. It reads Home Assistant entities/services and exposes them as ioBroker objects, and forwards ioBroker state changes back as Home Assistant service calls.
|
|
|
|
## Commands
|
|
|
|
```bash
|
|
# Build TypeScript
|
|
npm run build
|
|
|
|
# Run all tests (Mocha)
|
|
npm test
|
|
|
|
# Run only package validation tests
|
|
npm run test:package
|
|
|
|
# Lint
|
|
npm run lint
|
|
|
|
# Format check
|
|
npx prettier --check .
|
|
|
|
# Translate adapter strings
|
|
npm run translate
|
|
|
|
# Release (patch/minor/major)
|
|
npm run release-patch
|
|
npm run release-minor
|
|
npm run release-major
|
|
```
|
|
|
|
## Architecture
|
|
|
|
TypeScript class-based adapter. Source in `src/`, compiled output in `build/`.
|
|
|
|
- **src/main.ts** — `HassAdapter` class extending `Adapter`. Daemon mode entry point. Handles:
|
|
- Connecting to Home Assistant and syncing entities/services into ioBroker objects
|
|
- `parseStates()` — maps HASS entities, attributes, and services to ioBroker channels/states
|
|
- `onStateChange()` — converts ioBroker commands (`ack=false`) into HASS `callService()` calls, supporting both direct values (single-field services) and JSON-stringified objects (multi-field services)
|
|
- Object/state synchronization via `syncObjects`/`syncStates`
|
|
|
|
- **src/lib/hass.ts** — `HASS` class extending `EventEmitter`. WebSocket client for Home Assistant with:
|
|
- Auto-reconnect (3s delay)
|
|
- Message ID tracking for request-response correlation
|
|
- Methods: `getConfig`, `getStates`, `getServices`, `getPanels`, `callService`
|
|
- Events: `connected`, `disconnected`, `error`, `state_changed`
|
|
|
|
The codebase uses **callback-based async** (no promises/async-await).
|
|
|
|
## Testing
|
|
|
|
Tests use Mocha with two ioBroker-specific frameworks:
|
|
- `@iobroker/legacy-testing` — spins up a js-controller instance for integration tests (`test/testAdapter.js`)
|
|
- `@iobroker/testing` — validates package.json and io-package.json structure (`test/testPackageFiles.js`)
|
|
|
|
## Configuration
|
|
|
|
Adapter config (defined in `io-package.json`): `host`, `port`, `password` (long-lived access token), `secure` (boolean for wss).
|
|
|
|
## CI
|
|
|
|
GitHub Actions runs lint on Node 22, adapter tests on Node 20/22/24 across Linux/Windows/macOS. Deploys to npm on semantic version tags via OIDC trusted publishing.
|