ioBroker.hass/CLAUDE.md

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

# 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.