0.31.1 • Published 2 weeks ago

homebridge-tydom

Licence

MIT

Version

0.31.1

Deps

Size

528 kB

Vulns

Weekly

Stars

Summary Dependency Versions

homebridge-tydom

Homebridge plugin to manage Tydom hardware by Delta Dore from Apple HomeKit.

Talks to an existing Tydom gateway (required) through node-tydom-client, over Delta Dore's relay or directly on your LAN.
Discovers your hardware — nothing has to be listed by hand — and propagates changes made from a wall switch, a remote or the Tydom app into HomeKit as they happen.
Exposes the TYXAL+ alarm as a HomeKit security system, including per-zone switches and opening detectors.
Relays alarm events to a Discord webhook, so you get notified about an alarm HomeKit did not arm.

Requirements


Homebridge	v2.0 or later
Node.js	v22, v24 or v26
Hardware	A Tydom 1.0 / 2.0 gateway and a Tydom account

Upgrading from v0.29 or earlier? See Migrating to v0.30. Your accessories, rooms and automations are preserved; the requirements above are what changed.

Installation

Install through the Homebridge UI, or add the plugin to your Homebridge install — e.g. with homebridge/docker-homebridge, in ./volumes/homebridge/package.json:

{
  "private": true,
  "description": "This file keeps track of which plugins should be installed.",
  "dependencies": {
    "homebridge-tydom": "^0.30.0"
  }
}

Then configure the platform, either in the Homebridge UI or directly in config.json:

{
  "platforms": [
    {
      "platform": "Tydom",
      "hostname": "mediation.tydom.com",
      "username": "001A25123456",
      "password": "YourPassw0rd"
    }
  ]
}

Finding your credentials

Your username is the MAC address of your gateway: 001A25 followed by the 6-character home ID shown in the mobile app. Separators and case do not matter — 00:1a:25:12:34:56 works too.

Your password is the gateway's own, which is not the one you sign in to the Tydom app with. Newer setups have it generated by the app and never show it to you.

Rather than extract it, add your account e-mail and let the plugin fetch it for you:

{
  "platform": "Tydom",
  "hostname": "mediation.tydom.com",
  "username": "001A25123456",
  "email": "you@example.com",
  "password": "YourDeltaDoreAccountPassw0rd"
}

With email set, password is read as your Delta Dore account password: at startup the plugin signs in to Delta Dore, looks up the gateway named in username, and uses the gateway password it gets back. Nothing else changes, and your account password is never sent to the gateway. Leave email out — the default — and password keeps its old meaning of the gateway's own password.

The account has to already own that gateway. To check a pair without waiting on Homebridge:

pnpm resolve-credentials you@example.com 'YourDeltaDoreAccountPassw0rd' 001A25123456

If you would rather extract the gateway password by hand, you still can, by inspecting the app's traffic with an SSL proxy following this guide from @aure-olivier.

If your account has several houses

username is what picks the house. One Delta Dore account can hold several — a home, a holiday flat, a relative's place — and each is one gateway with its own MAC. Point username at the MAC of the house you want this Homebridge instance to expose, and that is the one you get. Adding email does not change that: the account lookup is scoped to the MAC you named, and hands back that gateway's password specifically.

To find the MAC of each house, open the Tydom app's home list and read the 6-character home ID next to each one; the MAC is 001A25 followed by that. An account holding three homes gives you three MACs, and each resolves to its own distinct gateway password:

Maison            ->  001A25 AAAAAA
Appartement       ->  001A25 BBBBBB
Chalet            ->  001A25 CCCCCC

Pick the one you want and put it in username. Note that the account only ever confirms a gateway you name — there is no public Delta Dore API that lists the houses on an account, and the lookup carries no house name either, so the home ID from the app is how you tell them apart.

Being able to see a house is not the same as holding its credentials. A house attached to your account but registered by someone else's comes back from the lookup without a password, and the plugin will tell you so rather than pretend the MAC is wrong:

Delta Dore returned no password for gateway 001A25XXXXXX. The account can see that house
but does not hold its credentials — sign in with the account that registered the gateway,
or set "password" to the gateway password directly and leave "email" out.

As that says, the fallback is to drop email and give that house's gateway password directly.

Each house gets its own accessory namespace, derived from that home ID, so switching username from one house to another retires the first house's accessories and publishes the second's rather than mixing them up. Expect a batch of Deleting missing accessory lines in the log the first time you do it — that is the sweep clearing out the house you moved away from.

A platform block is one house at a time; the plugin is declared singular, so the Homebridge UI allows a single Tydom block. To expose two houses at once you would need a second Homebridge instance, or a hand-written second platform block run as a child bridge.

Both secrets can be supplied out of band instead, base64-encoded, which is usually what you want in a container:

HOMEBRIDGE_TYDOM_PASSWORD=$(echo -n "YourPassw0rd" | base64)
HOMEBRIDGE_TYDOM_PIN=$(echo -n "123456" | base64)

They take precedence over the corresponding config fields.

Options

Field	Type	Default	Description
`hostname`	`string`	—	`mediation.tydom.com` for the relay, or your gateway's LAN address (see Connecting locally). Required.
`username`	`string`	—	Gateway MAC address, e.g. `001A25123456`. This is what selects the house — see If your account has several houses. Required.
`email`	`string`	—	Delta Dore account e-mail. Set it to have the gateway password fetched for you, which also changes what `password` below means. See Finding your credentials.
`password`	`string`	—	Your Delta Dore account password if `email` is set, otherwise the gateway's own password. Required, unless supplied via the environment.
`pin`	`string`	—	TYXAL+ alarm PIN. Without it the alarm reports its state but cannot be armed or disarmed.
`locale`	`"fr" \| "en"`	`"fr"`	Language of the labels Delta Dore supplies for zones, detectors and thermostat modes.
`refreshInterval`	`number`	`14400`	Seconds between full state refreshes. The gateway pushes changes as they happen, so this is only a safety net; clamped to a minimum of 60.
`staleAfter`	`number`	`300`	Seconds a device reading is served from memory before HomeKit's next query triggers a background re-read. `0` reads through on every query, as releases before 0.30 did. See Reading state.
`includedDevices`	`string[]`	`[]`	If non-empty, ignore every device not listed.
`excludedDevices`	`string[]`	`[]`	Devices to leave out, applied after the include list.
`includedCategories`	`string[]`	`[]`	Same, by HAP category number.
`excludedCategories`	`string[]`	`[]`	Same, by HAP category number.
`webhooks`	`Webhook[]`	`[]`	See Webhooks.
`settings`	`Record<deviceId, object>`	`{}`	Per-device overrides. See Device settings.
`debug`	`boolean`	`false`	Log every gateway request and every characteristic read and write.

Device ids are printed in the Homebridge log at startup:

[Tydom] Found new tydom device named="Kitchen" with deviceId=1234567 (id=…)

Environment variables:

Variable	Description
`HOMEBRIDGE_TYDOM_PASSWORD`	Gateway or account password, base64-encoded. Overrides `password`.
`HOMEBRIDGE_TYDOM_EMAIL`	Delta Dore account e-mail, in plain text. Overrides `email`.
`HOMEBRIDGE_TYDOM_PIN`	TYXAL+ PIN, base64-encoded. Overrides `pin`.
`HOMEBRIDGE_TYDOM_LOCALE`	`fr` or `en`. Overrides `locale`.

Reading state

The gateway is push-first: it tells the plugin when something changes rather than waiting to be asked. So device readings are held in memory and served straight to HomeKit, which queries far more often than anything actually changes — a Tydom box is a small embedded device, and hammering it with a request per query is what makes it drop local clients.

Because there is no polling loop to fall back on, a missed push would otherwise leave HomeKit wrong until the next full refresh, hours later. So a query that finds its reading older than staleAfter returns the held value immediately and re-reads in the background, pushing the corrected value out when it arrives. Staleness is bounded by staleAfter; nothing waits on the gateway except the very first read of each device.

If you would rather trade the traffic for a guaranteed-fresh read every time, set staleAfter to 0.

Connecting locally

Pointing hostname at your gateway's IP (e.g. 192.168.0.42) skips Delta Dore's relay: lower latency, and it keeps working when the relay is down. Two caveats:

The gateway serves a self-signed certificate, so Node must be started with NODE_TLS_REJECT_UNAUTHORIZED=0.
Tydom 2.0 firmware sometimes copes badly with several local clients at once, and can lock you out of the mobile app.

Device settings

settings is keyed by numeric device id. Which keys a device accepts depends on what it is:

Key	Applies to	Description
`name`	any	Rename the accessory.
`category`	any	Pin the device to a HAP category, bypassing hardware detection. See Category overrides.
`trigger`	switches	Publish a stateless switch that returns to off, rather than a toggle.
`smokeDetector`	temperature sensors	Publish as a smoke detector instead.
`delay`	garage doors	Travel time in milliseconds. Defaults to `20000`.
`autoCloseDelay`	garage doors	Close again this many milliseconds after opening. Off by default.
`pin`	alarm	PIN for this alarm, overriding the platform-level one.
`aliases`	alarm	Which armed-zone combinations map to HomeKit's Home and Night. See Security system.
`sensors`	alarm	Set to `false` to drop the companion accessory holding the opening detectors. On by default.
`legacy`	alarm	Force the CTX60 protocol. Detected automatically — only set this if detection is wrong.

Security system

HomeKit offers three armed modes — Home, Night and Away — while Tydom arms an arbitrary set of zones. aliases declares which combination means what; anything else, including a partial arm you have not described, reads as disarmed rather than claiming the house is protected. Away means every zone.

{
  "settings": {
    "1521931577": {
      "pin": "123456",
      "aliases": { "stay": [3], "night": [2, 3] }
    }
  }
}

Zone names come from the gateway: whatever you named the zone in the Tydom app, falling back to Delta Dore's own label in your configured language, falling back to Zone 1, Zone 2… They cannot be renamed from this plugin.

Alongside the alarm, a second accessory is published holding one contact sensor per opening detector (MDO), so you can see which door is open. Set "sensors": false to leave it out.

If the zone switches and detectors show up unlabeled, open the accessory's settings in the Home app and turn on Show as separate tiles. Merged into a single tile, the Home app captions none of an accessory's sub-services — it is a display choice on your side, and no plugin can override it. Note that a zone can only have a room or be an automation target if it is a separate accessory, which it is not; open an issue if you need that.

Category overrides

If a device is detected as the wrong thing — a light switch actually driving a fan, say — pin it:

{
  "settings": {
    "1528565701": { "category": 3 }
  }
}

3 is Categories.FAN. The categories this plugin can publish are 3 fan, 4 garage door, 5 light, 7 outlet, 8 switch, 9 thermostat, 10 sensor, 11 alarm, 12 door, 13 window, 14 shutter. The full HAP list is here.

Webhooks

All security-system events are relayed. Discord is the only supported target.

{
  "webhooks": [
    { "url": "https://discord.com/api/webhooks/123456/abdcdef", "type": "discord" }
  ]
}

Supported hardware

Confirmed working:

Lightbulb (TYXIA 5610, TYXIA 6610)
Dimmable lightbulb (TYXIA 5650)
Fan (TYXIA 6610)
Thermostat (RF4890)
Switch (TYXIA 4620)
Security system (TYXAL+)
Contact sensor, door and window (TYXAL+ MDO BL)

Reported working by the community:

Window coverings (TYXIA 5630, TYXIA 5730, TYXIA 5731)

Also published: outlets, garage door openers, smoke detectors and temperature sensors. Devices are matched on the shape of the metadata the gateway reports, so similar hardware generally works untouched — and adding a new match is a small change, so please open an issue if yours is not recognised.

Migrating to v0.30

Nothing in your config needs to change, and no accessory is re-registered: rooms, names and automations survive the upgrade. What changed:

Homebridge 1.x is no longer supported. v2.0 or later is required.
Node 18 and 20 are no longer supported. v22, v24 or v26.
The plugin ships as pure ESM. This is invisible unless you were importing it programmatically.
locale can now be set in the config; previously only the HOMEBRIDGE_TYDOM_LOCALE environment variable worked, and it was read before the config file, so a locale key in config.json was silently ignored.
refreshInterval, the four include/exclude filters and webhooks now appear in the Homebridge UI. They were always supported, but only reachable by hand-editing config.json.
A bad config no longer takes the bridge down. The platform reports the problem and stays dormant while the rest of Homebridge keeps running.
settings.<id>.zones, documented in earlier READMEs as a way to rename alarm zones, never had any effect and has been removed from the docs. Rename zones in the Tydom app instead.

Troubleshooting

Duplicate accessories, or `Cannot serialize accessory`

Versions up to v0.30.0 handed each newly discovered accessory to Homebridge for caching before registering it, which made the cache write fail:

Failed to save cached accessories to disk: Cannot serialize accessory 'Salon' - missing associated plugin
Accessory 'Salon' has the same UUID as existing accessory 'Salon'. Skipping duplicate.

v0.30.1 fixes the cause, and Homebridge rewrites one entry per accessory on the first scan after upgrading — so most installations recover on their own after a restart. An accessory that was duplicated and then removed from the gateway can be left orphaned in the cache, which only a reset clears. If the warnings persist, stop Homebridge and delete the cache file once:

rm ~/.homebridge/accessories/cachedAccessories

On a child bridge the file is named cachedAccessories.<bridge-username>. This re-registers every accessory, so rooms, names and automations for Tydom devices have to be set up again — which is why it is a last resort rather than a routine upgrade step.

Debugging

Set debug to true in the config, or start Homebridge with:

DEBUG=homebridge-tydom

To also trace the gateway protocol itself:

DEBUG=homebridge-tydom,tydom-client

When opening an issue, please attach a dump of your gateway configuration:

npx tydom-client request /configs/file /devices/data /devices/meta /devices/cmeta \
  --file tydom_output.json --username 001A25XXXXXX --password XXXXXX

Upload the resulting tydom_output.json to a gist. A debug log captured while driving the device from the official Tydom app is even more useful — it shows the requests that are known to work.

Development

pnpm install
pnpm test        # lint, type-check, spec and format:check
pnpm build

Script	Description
`lint`	Static analysis with oxlint
`check`	TypeScript type checking
`spec`	Unit tests with vitest
`format`	Formatting with oxfmt
`build`	Bundle with tsdown
`dev:homebridge`	Run Homebridge against the working tree
`dev:homebridge:insecure`	Same, accepting the gateway's self-signed certificate

Authors

Olivier Louvignes

License

The MIT License

Copyright (c) 2020 Olivier Louvignes <olivier@mgcrea.io>

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in
all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
THE SOFTWARE.

Keywords

homebridge-plugin homebridge homekit tydom delta-dore tyxal tyxia domotics home-automation