{"_id":"@codzelerate/homebridge-bosch-nefit-easy","name":"@codzelerate/homebridge-bosch-nefit-easy","dist-tags":{"latest":"2.1.3"},"versions":{"2.1.3":{"name":"@codzelerate/homebridge-bosch-nefit-easy","version":"2.1.3","description":"Homebridge plugin for the Bosch Nefit Easy thermostat using bosch-xmpp. Node.js 22+ compatible.","main":"dist/index.js","types":"dist/index.d.ts","scripts":{"build":"tsc","watch":"tsc --watch","prepare":"test -d dist || npm run build"},"keywords":["homebridge-plugin","nefit","bosch","thermostat","homekit","xmpp","nefit-easy"],"author":{"name":"Codzelerate","email":"hello@codzelerate.com"},"license":"MIT","repository":{"type":"git","url":"git+https://github.com/Codzelerate/homebridge-bosch-nefit-easy.git"},"bugs":{"url":"https://github.com/Codzelerate/homebridge-bosch-nefit-easy/issues"},"homepage":"https://github.com/Codzelerate/homebridge-bosch-nefit-easy#readme","engines":{"homebridge":"^2.0.0","node":"^22 || ^24"},"dependencies":{"bosch-xmpp":"^2.0.0"},"devDependencies":{"@types/node":"^22.0.0","homebridge":"^2.0.0","typescript":"^5.0.0"},"peerDependencies":{"homebridge":"^2.0.0"},"gitHead":"4b8f22faaac669550628369eede66974453e01f0","_id":"@codzelerate/homebridge-bosch-nefit-easy@2.1.3","bundleDependencies":["bosch-xmpp"],"_nodeVersion":"24.12.0","_npmVersion":"11.6.2","dist":{"integrity":"sha512-5xW6GHi7UQ76nrfvluXpkor29rL6dNhYDLuJbBhXN2lJlCpYqLt3XgDIkNQ0afRwBu/MjrD86WKCBtPJTKzl4Q==","shasum":"a22de324eb9039d082095dd9e4890702533fa34e","tarball":"https://registry.npmjs.org/@codzelerate/homebridge-bosch-nefit-easy/-/homebridge-bosch-nefit-easy-2.1.3.tgz","fileCount":1150,"unpackedSize":3880507,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQC5Xb+v76RcmthvFvDh/wPYkuK9ItX7px9RTddOs/MX0QIhANeIP0wryDl+FJ/PDL5KMWRVNB+yfe50+/0KBJsp+mxl"}]},"_npmUser":{"name":"sunil.zacharia","email":"sunil.zacharia@codzelerate.com"},"directories":{},"maintainers":[{"name":"sunil.zacharia","email":"sunil.zacharia@codzelerate.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/homebridge-bosch-nefit-easy_2.1.3_1780161287590_0.0919092657110645"},"_hasShrinkwrap":false}},"time":{"created":"2026-05-30T17:14:47.432Z","2.1.3":"2026-05-30T17:14:47.905Z","modified":"2026-05-30T17:14:48.128Z"},"maintainers":[{"name":"sunil.zacharia","email":"sunil.zacharia@codzelerate.com"}],"description":"Homebridge plugin for the Bosch Nefit Easy thermostat using bosch-xmpp. Node.js 22+ compatible.","homepage":"https://github.com/Codzelerate/homebridge-bosch-nefit-easy#readme","keywords":["homebridge-plugin","nefit","bosch","thermostat","homekit","xmpp","nefit-easy"],"repository":{"type":"git","url":"git+https://github.com/Codzelerate/homebridge-bosch-nefit-easy.git"},"author":{"name":"Codzelerate","email":"hello@codzelerate.com"},"bugs":{"url":"https://github.com/Codzelerate/homebridge-bosch-nefit-easy/issues"},"license":"MIT","readme":"# @codzelerate/homebridge-bosch-nefit-easy\n\n[![npm version](https://img.shields.io/npm/v/@codzelerate/homebridge-bosch-nefit-easy.svg)](https://www.npmjs.com/package/@codzelerate/homebridge-bosch-nefit-easy)\n[![npm downloads](https://img.shields.io/npm/dt/@codzelerate/homebridge-bosch-nefit-easy.svg)](https://www.npmjs.com/package/@codzelerate/homebridge-bosch-nefit-easy)\n[![Homebridge](https://img.shields.io/badge/Homebridge-v2.x-purple)](https://homebridge.io)\n[![Node.js](https://img.shields.io/badge/Node.js-22%2B-brightgreen)](https://nodejs.org)\n[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)\n\nA **Homebridge v2** plugin that integrates the **Bosch Nefit Easy** thermostat with Apple HomeKit. Built on the [`bosch-xmpp`](https://github.com/robertklep/bosch-xmpp) library — fully compatible with Node.js 22 and 24.\n\n> This plugin replaces the deprecated `homebridge-nefit-easy` package, which relied on `nefit-easy-core` and `node-xmpp-client` — both broken on Node.js 22+.\n\n---\n\n## Features\n\n- Real-time temperature monitoring via HomeKit\n- Set target temperature directly from the Home app or Siri\n- Heating on/off control\n- Persistent XMPP connection — no per-poll reconnections\n- Automatic reconnect on connection failure\n- Configurable polling interval\n- Runs as an isolated **child bridge** for maximum stability\n- Full [Homebridge UI X](https://github.com/homebridge/homebridge-config-ui-x) support — no manual JSON editing required\n- Built-in debug logging toggle for troubleshooting\n\n---\n\n## Requirements\n\n| Requirement | Version |\n|---|---|\n| [Homebridge](https://homebridge.io) | v2.0 or later |\n| Node.js | 22 or 24 |\n| Bosch Nefit Easy thermostat | Any generation |\n\n---\n\n## Installation\n\n### Via Homebridge UI (Recommended)\n\n1. Open the Homebridge UI in your browser\n2. Go to the **Plugins** tab\n3. Search for **@codzelerate/homebridge-bosch-nefit-easy**\n4. Click **Install**\n\n### Via Terminal\n\n```bash\nnpm install -g @codzelerate/homebridge-bosch-nefit-easy\n```\n\n---\n\n## Finding Your Credentials\n\nYour credentials are found inside the **Nefit Easy mobile app**:\n\n1. Open the Nefit Easy app on your phone\n2. Tap the **hamburger menu** (☰) in the top-left\n3. Go to **Settings → About**\n\nYou will find:\n- **Serial Number** — a numeric string (e.g. `123456789`)\n- **Access Key** — an alphanumeric string displayed below the serial number\n\nThe **Password** is the one you chose when you first set up the Nefit Easy app during initial installation.\n\n---\n\n## Configuration\n\n### Using the Homebridge UI\n\nAfter installation, click **Settings** on the plugin to open the configuration form. Fill in your credentials and click Save.\n\n### Manual JSON Configuration\n\nAdd the following to the `accessories` array in your Homebridge `config.json`:\n\n```json\n{\n  \"accessories\": [\n    {\n      \"accessory\": \"BoschNefitEasy\",\n      \"name\": \"Thermostat\",\n      \"serialNumber\": \"YOUR_SERIAL_NUMBER\",\n      \"accessKey\": \"YOUR_ACCESS_KEY\",\n      \"password\": \"YOUR_PASSWORD\",\n      \"pollingInterval\": 60,\n      \"debug\": false\n    }\n  ]\n}\n```\n\n---\n\n## Configuration Parameters\n\n### Required\n\n#### `accessory`\n**Type:** `string` — **Must be** `\"BoschNefitEasy\"`\n\nThe Homebridge accessory identifier. This value must match exactly — it tells Homebridge which plugin to use for this accessory entry.\n\n---\n\n#### `name`\n**Type:** `string` — **Default:** `\"Thermostat\"`\n\nThe display name for the thermostat as it will appear in the Apple Home app and throughout HomeKit. Choose something meaningful if you have multiple thermostats (e.g. `\"Ground Floor Thermostat\"`).\n\n---\n\n#### `serialNumber`\n**Type:** `string`\n\nThe serial number of your Nefit Easy thermostat. This is used to identify your device on the Bosch XMPP backend. Found in the Nefit Easy app under **Settings → About**.\n\n---\n\n#### `accessKey`\n**Type:** `string`\n\nThe access key associated with your thermostat. Together with the serial number and password, this forms the three-part credential set required to authenticate with the Bosch backend. Found in the Nefit Easy app under **Settings → About**.\n\n---\n\n#### `password`\n**Type:** `string`\n\nThe password you chose when you first configured the Nefit Easy app. This is not the password to your Bosch account — it is a device-specific password set during the thermostat's initial app pairing.\n\n---\n\n### Optional\n\n#### `pollingInterval`\n**Type:** `integer` — **Default:** `60` — **Range:** `10–600`\n\nHow often (in seconds) the plugin polls the thermostat for updated temperature and status readings. The plugin maintains a persistent XMPP connection, so polling is lightweight. Lower values give more responsive HomeKit updates; higher values reduce network traffic.\n\n| Value | Behaviour |\n|---|---|\n| `10` | Near real-time updates — suitable for active monitoring |\n| `60` | Default — good balance of responsiveness and efficiency |\n| `300` | Minimal traffic — suitable for passive monitoring |\n\n---\n\n#### `debug`\n**Type:** `boolean` — **Default:** `false`\n\nWhen enabled, the plugin writes detailed diagnostic information to the Homebridge log, including:\n\n- Raw API response payloads from the thermostat\n- XMPP connection steps and timing\n- Every HomeKit characteristic read and write\n- Full error stack traces on failure\n\n**Enable this only when troubleshooting.** Debug output is verbose and will fill your logs quickly during normal operation.\n\n---\n\n## HomeKit Capabilities\n\nThe plugin exposes a single **Thermostat** service with the following characteristics:\n\n| Characteristic | Access | Range | Description |\n|---|---|---|---|\n| Current Temperature | Read | — | Live indoor temperature as reported by the thermostat sensor |\n| Target Temperature | Read / Write | 5–30 °C, step 0.5 °C | The desired temperature setpoint |\n| Current Heating State | Read | Off / Heat | Whether the boiler burner is currently active |\n| Target Heating State | Read / Write | Off / Heat | Set to Off to drop setpoint to minimum; set to Heat to resume |\n| Temperature Display Units | Read | Celsius | Always reported in Celsius |\n\n---\n\n## Child Bridge (Recommended)\n\nRunning the plugin as a **child bridge** isolates it in a separate process. If the XMPP connection hangs or the plugin crashes, it will not affect your main Homebridge instance or other accessories.\n\nTo enable via the Homebridge UI:\n\n1. Go to **Plugins** → find **Homebridge Bosch Nefit Easy** → click the **⋮ menu**\n2. Select **Bridge Settings**\n3. Toggle **Use Child Bridge** on\n4. Save and restart Homebridge\n5. Open the Apple Home app and pair the new bridge using your Homebridge PIN\n\n---\n\n## Known Limitations\n\n- **Cooling and Auto modes are not supported.** The Nefit Easy is a heating-only device. Only Off and Heat states are exposed in HomeKit.\n- **Turning Off via HomeKit** drops the target temperature to 5 °C (the minimum) rather than fully disabling the thermostat. The Nefit Easy does not support a hard-off command over the XMPP API.\n- **Weekly schedules are not exposed.** The thermostat's built-in programs continue to run on the device itself. This plugin controls the manual setpoint only.\n- **Multiple heating circuits are not supported.** The plugin always targets `hc1`. If your installation has multiple circuits, only the first will be controlled.\n- **Credentials are stored in plain text** in `config.json`. Ensure your Homebridge host is on a trusted network and access is appropriately restricted.\n\n---\n\n## Migrating from homebridge-nefit-easy\n\n1. Open the Homebridge UI → **Plugins** tab\n2. Uninstall `homebridge-nefit-easy`\n3. Install `@codzelerate/homebridge-bosch-nefit-easy`\n4. Re-enter your credentials in the plugin settings (same serial number, access key, and password)\n5. Restart Homebridge\n\n---\n\n## Troubleshooting\n\n### The plugin connects but shows NaN temperatures\n\nEnable **Debug Logging** in the plugin settings and restart. Check the log for the `Raw uiStatus response` line and share the output.\n\n### Connection keeps failing with a timeout\n\n- Verify your serial number, access key, and password are correct (copy-paste from the app to avoid typos)\n- Check that your Homebridge host has outbound internet access to `wa2-mz36-qrmzh6.bosch.de` on port `5222`\n- The Bosch backend occasionally has maintenance windows — try again after a few minutes\n\n### The accessory disappeared from HomeKit after updating\n\nIf you switched from `homebridge-nefit-easy` (old plugin), HomeKit sees it as a brand new accessory. Remove the old thermostat tile in the Home app and pair the new one.\n\n---\n\n## Changelog\n\nSee [CHANGELOG.md](CHANGELOG.md) for the full version history.\n\n---\n\n## Built by Codzelerate\n\nThis plugin is developed and maintained by [**Codzelerate**](https://www.codzelerate.com?utm_source=github&utm_medium=plugin&utm_campaign=@codzelerate/homebridge-bosch-nefit-easy) — a software development studio focused on smart home automation, IoT integrations, and Apple platform development.\n\nFor questions, bug reports, or feature requests, please [open an issue](https://github.com/Codzelerate/@codzelerate/homebridge-bosch-nefit-easy/issues) on GitHub.\n\n---\n\n## License\n\nMIT © [Codzelerate](https://www.codzelerate.com?utm_source=github&utm_medium=plugin&utm_campaign=@codzelerate/homebridge-bosch-nefit-easy)\n","readmeFilename":"README.md","_rev":"1-176a914aa47c102478174f4fbf41adc0"}