{"id":48187,"library":"iobroker.hannah","title":"ioBroker Hannah Adapter","description":"Bidirectional gRPC bridge between ioBroker and the Hannah voice assistant (v0.13.0, released 2025-06-05). Replaces the prior MQTT-based integration, solving retained-message and wildcard-subscription problems. Streams device states, presence, and text commands in real time; supports device discovery via ioBroker enums, extra state prefixes, notifications, and Blockly blocks. Requires ioBroker js-controller ≥ 5.0, Node.js ≥ 22, and a running Hannah Core instance on the default gRPC port 50051. Releases are irregular but frequent (7 versions in 2 months).","status":"active","version":"0.13.0","language":"javascript","source_language":"en","source_url":"https://github.com/NurPech/ioBroker.hannah","tags":["javascript","hannah","gRPC","voice assistant","ioBroker"],"install":[{"cmd":"npm install iobroker.hannah","lang":"bash","label":"npm"},{"cmd":"yarn add iobroker.hannah","lang":"bash","label":"yarn"},{"cmd":"pnpm add iobroker.hannah","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"gRPC client for bidirectional stream to Hannah Core","package":"@grpc/grpc-js","optional":false},{"reason":"ioBroker adapter framework","package":"@iobroker/adapter-core","optional":false}],"imports":[{"note":"ioBroker adapters are CommonJS-only; ESM is not supported.","wrong":"import utils from '@iobroker/adapter-core';","symbol":"utils","correct":"const utils = require('@iobroker/adapter-core');"},{"note":"Adapter is a named export, not the default.","wrong":"const Adapter = require('@iobroker/adapter-core');","symbol":"Adapter","correct":"const { Adapter } = require('@iobroker/adapter-core');"},{"note":"createAdapter is a factory; call it directly in adapter.js.","wrong":"const adapter = createAdapter();","symbol":"createAdapter","correct":"const createAdapter = require('@iobroker/adapter-core').Adapter;"}],"quickstart":{"code":"const utils = require('@iobroker/adapter-core');\nconst grpc = require('@grpc/grpc-js');\nconst protoLoader = require('@grpc/proto-loader');\n\nconst PROTO_PATH = __dirname + '/lib/hannah.proto';\nconst packageDefinition = protoLoader.loadSync(PROTO_PATH, {\n  keepCase: true,\n  longs: String,\n  enums: String,\n  defaults: true,\n  oneofs: true,\n});\nconst hannahProto = grpc.loadPackageDefinition(packageDefinition).hannah;\n\nclass HannahAdapter extends utils.Adapter {\n  constructor(options) {\n    super({\n      ...options,\n      name: 'hannah',\n    });\n    this.on('ready', this.onReady.bind(this));\n    this.on('stateChange', this.onStateChange.bind(this));\n    this.on('unload', this.onUnload.bind(this));\n  }\n\n  async onReady() {\n    const host = this.config.host || '127.0.0.1';\n    const port = this.config.port || 50051;\n    const client = new hannahProto.AgentConnect(`${host}:${port}`, grpc.credentials.createInsecure());\n    \n    const stream = client.connect();\n    stream.on('data', (msg) => {\n      if (msg.command === 'setState') {\n        this.setState(msg.id, msg.val, true);\n      }\n    });\n    stream.on('error', (err) => console.error('gRPC error:', err));\n    \n    this.subscribeStates('*');\n    this.setState('info.connection', true, true);\n  }\n\n  onStateChange(id, state) {\n    if (state && !state.ack) {\n      // forward to Hannah\n    }\n  }\n\n  onUnload(callback) {\n    callback();\n  }\n}\n\nif (require.main !== module) {\n  module.exports = (options) => new HannahAdapter(options);\n} else {\n  new HannahAdapter();\n}","lang":"javascript","description":"Shows minimal ioBroker adapter setup with gRPC connection and state handling."},"warnings":[{"fix":"Upgrade Node.js to version 22 or later.","message":"Node.js >= 22 required; the adapter uses modern JS features and @grpc/grpc-js versions that drop older Node.js support.","severity":"breaking","affected_versions":">=0.1.0"},{"fix":"Install and configure a Hannah Core instance with gRPC enabled (port 50051).","message":"Adapter no longer uses MQTT; previous MQTT-based integration is incompatible. Users must migrate to gRPC.","severity":"breaking","affected_versions":">=0.1.0"},{"fix":"Remove any trailing asterisks from extra state prefixes in adapter configuration.","message":"Extra state prefixes must be exact ioBroker state ID prefixes; trailing wildcards (*) are automatically appended by the adapter, do not include them in the config.","severity":"gotcha","affected_versions":">=0.1.0"},{"fix":"If you use info.connection as a trigger, add a small delay or wait for a confirm message from Hannah.","message":"The adapter sets info.connection to true on gRPC stream open, not after the initial snapshot is sent. Hannah may receive state data slightly after connection is reported.","severity":"gotcha","affected_versions":">=0.1.0"}],"env_vars":null,"search_vec":"'-05':18 '-06':17 '2':86 '2025':16 '22':65 '5.0':63 '50051':77 '7':83 'adapt':3 'assist':13,92 'base':24 'bidirect':4 'block':56,57 'bridg':6 'command':41 'control':62 'core':70 'default':74 'devic':36,46 'discoveri':47 'enum':50 'extra':51 'frequent':82 'grpc':5,75,90 'hannah':2,11,69,89 'instanc':71 'integr':25 'iobrok':1,8,49,59,93 'irregular':80 'javascript':88 'js':61 'js-control':60 'messag':29 'month':87 'mqtt':23 'mqtt-base':22 'node.js':64 'notif':54 'port':76 'prefix':53 'presenc':38 'prior':21 'problem':34 'real':43 'releas':15,78 'replac':19 'requir':58 'retain':28 'retained-messag':27 'run':68 'solv':26 'state':37,52 'stream':35 'subscript':33 'support':45 'text':40 'time':44 'v0.13.0':14 'version':84 'via':48 'voic':12,91 'wildcard':32 'wildcard-subscript':31","created_at":"2026-06-07T16:55:20.996905+00:00","updated_at":"2026-06-07T16:55:20.996905+00:00","problems":[{"fix":"Run 'npm install @grpc/grpc-js' in the adapter directory or reinstall the adapter from ioBroker admin.","cause":"Missing native gRPC dependency; npm install did not install all packages.","error":"Error: Cannot find module '@grpc/grpc-js'"},{"fix":"Ensure Hannah Core is running and accessible on the configured host:port. Check firewall rules and verify the port (default 50051).","cause":"Hannah Core is not running or gRPC port is blocked/firewalled.","error":"Error: 14 UNAVAILABLE: failed to connect to all addresses"}],"ecosystem":"npm","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":null,"cli_version":null,"type":"library","homepage":"https://github.com/NurPech/ioBroker.hannah","github":"https://github.com/NurPech/ioBroker.hannah","docs":null,"changelog":null,"pypi":null,"npm":"iobroker.hannah","openapi_spec":null,"status_page":null,"smithery":null,"categories":["ai-ml","devops"],"base_url":null,"auth_type":null,"provenance":{"verified_status":null,"verified_at":null,"last_verified":"2026-06-07","next_check":"2026-09-05","install_tag":null}}