Managers, mixins, pairing helpers and small runtime pieces (hand-written reference)
Written 2026-11-08 for the documentation coverage work (P3273, queue item 5), continuing MODULES_FLOW_ENERGY_AND_LAYERS. Each entry says in our own words what the module is for, how it is bounded and where it is wired. "Importers" counts the other files under lib/, drivers/ and app.js that require() it on master at the time of writing; 0 means the module is currently not loaded by anything (kept for reference, candidate for a later review, never removed without a check).
Diagnostics, energy and small device helpers
lib/diagnostics/DeviceDiagSnapshot.js(P3198) — writes one compact, anonymised line per paired device to the app log so a user diagnostic report always carries the device identity (manufacturer name, product id, endpoints, clusters, DPs seen, recent errors, a few raw EF00 frames, unmapped ones first). It fires at boot (staggered), every 6 hours per device, when a DP the driver does not own shows up for the first time, and at the end of pairing. State lives in a WeakMap keyed by the device, so it is freed with the device; at most 24 DPs, 3 errors, 12 frames of 24 bytes and 1600 characters per line. IEEE addresses, Homey ids, device or zone names and emails are never written, and every entry point is wrapped so it never throws. Importers: 4.lib/energy/PowerEstimator.js(P3170) — pure helpers for the optional app-side power estimate (enable_virtual_energyon plug and switch bases). Two models: linear (standby plus rated power scaled by the dim level) and a measured lookup table that is only allowed for an exact manufacturer + product couple with a recorded source (the table starts empty, nothing is invented). Energy is integrated from the previous sample with a capped gap, so a restart or a sleep never books hours of phantom kWh, and the total never goes down. Homey's own energy approximation (usageOn/usageOff in the manifest and the user settings) stays the preferred path for devices without a power meter. Importers: 1.lib/garage/garageTrigger.js(P3144, P3159) — tells which garage door openers want DP1 as a "move the door" pulse instead of an open/close boolean. Only four exact_TZE608_*names with product id TS0603 are on that list (from the zigbee-herdsman-converters Tuya definitions); for them every open or close request writes DP1 = true, and DP3 stays the contact. Any other opener keeps the earlier open/close behaviour, and there is deliberately no prefix match. Importers: 1.lib/lighting/ColorEffectManager.js— runs timed colour effects on RGB lights (rainbow, breathe, strobe, fade, pulse and custom sequences) by stepping hue and level from the app; one effect per device, stopped explicitly or when another starts. Idea inspired by the ZigWS2812 controller project, code our own. Importers: 1.
Managers
lib/managers/AutonomousMigrationManager.js— SDK3 cannot move a paired device to another driver, so this manager makes the current driver behave closer to the right one instead: it reads the advertised clusters, guesses the device type and power source, works out which capabilities the better-fitting driver would have, then adds the missing ones, sets up the matching bindings and parsers. It only adds; it does not remove what the device already has. Importers: 2.lib/managers/CapabilityFallbackManager.js— installed byBaseUnifiedDeviceon every device built on it. It wrapssetCapabilityValueso a value for a capability the device does not have is skipped quietly (multi-variant devices, for example a 2-gang switch receiving a third gang), null and NaN values are dropped, alarm and on/off values become booleans, humidity and battery are clamped to 0–100, dim to 0–1, temperature to -100–1000, and an SDK error is logged instead of thrown. It also drops anymeasure_*ormeter_*number above 30 000 as a Tuya error value. Open lead L-P3273-01: that ceiling also hits real values (sunlight above 30 000 lux onmeasure_luminance, a cumulativemeter_powerabove 30 000 kWh), which would freeze the capability on its last value; it is present on master, stable-v5 and bastien-home. Importers: 1.lib/managers/DriverMigrationManager.js— compares a device's identity and cluster analysis with the identification database to name the best driver and a confidence. When the device sits on a clearly worse driver, it tells the user through a Homey notification which driver to re-pair with; it never moves the device itself. Importers: 3.lib/managers/IASZoneEnhanced.js— IAS Zone (cluster 0x0500) handling for contact, motion, smoke, water leak and vibration sensors: answers zone enroll requests, listens for zone status change notifications, decodes the status bits (alarm 1/2, tamper, low battery) and updates the matching alarm capabilities, and can read the status on demand. Importers: 4.lib/managers/IEEEAddressManager.js— one place to read the device's and the Homey coordinator's IEEE addresses, and to read, verify and write the IAS CIE address. It accepts the different attribute spellings found in the wild, normalises and validates addresses, retries, and no longer falls back to a hard-coded address (that broke enrollment); Homey 8.1.1 and later write the CIE address during pairing anyway. Importers: 6.lib/managers/IEEEAdvancedEnrollment.js— extends the address manager with the full enrollment sequence: rewrite the CIE address (zero then write), send a proactive enroll response, answer enroll requests, poll the zone state until it reports enrolled (bounded wait), find the IAS Zone cluster on endpoints 1, 2, 0 or any other, and send the "normal operation mode" command. Importers: 6.lib/managers/IntelligentDataManager.js— per-device data housekeeping: works out a profile (sensor, switch, battery or mains), tries several time-sync methods in order (ZCL Time cluster, Tuya legacy time frame, manual attribute write) and repeats the sync on a schedule, then configures attribute reporting by device type with longer intervals on battery devices and adapts polling to how active the device is. Importers: 2.lib/managers/MotionCascadeManager.js— optional "path lighting": a motion or presence sensor is linked to one light (and optionally the next room's light); motion turns them on, optionally at a dim level, every new motion restarts the off timer, and the lights turn off after the configured minutes without motion. It hooks the same central point that handles motion flow cards, owns its timers and cleans them on unlink. Importers: 1.lib/managers/PowerSourceDetector.js— decides whether a device is mains powered from its driver id and product id patterns (switch, dimmer, plug and outlet families such as TS0001–TS0004, TS011F, TS0121), and for battery devices chooses a battery reporting mode (an ECO mode for longer battery life unless the user set an interval). Importers: 2.lib/managers/UniversalFlowCardManager.js— small shared registrar for the app's generic "smart" flow cards so each driver does not repeat the same registration code; a missing card is logged, not thrown. Importers: 1.lib/managers/VirtualEnergyManager.js— the older way of simulating energy for devices without a metering chip, enabled by thevirtual_energy_enabledsetting: a timer accumulates estimated consumption. Writes go through the safe capability setter when available, and it never overwrites a real meter capability. New code usesVirtualEnergyMeterMixininstead. Importers: 1.
Memory bounds
lib/memory/BoundedCollections.js(P3068) —BoundedFifoMapandBoundedFifoSetare realMapandSetsubclasses with a hard size ceiling: adding a new key when full first drops the oldest one, updating an existing key never evicts, and below the ceiling they behave exactly like the built-ins.boundedPush(arr, item, max)does the same for arrays. Pure, no timers, never throws on bad input; used by long-lived caches to stay inside the Homey heap (about 64 MB). Importers: 13.
Mixins
lib/mixins/CapabilityManagerMixin.js— shared capability writing for Tuya devices: a safe setter that applies the user calibration, refuses physically impossible values and implausible jumps per capability (temperature -40–80 °C with at most 10 °C per step, humidity, soil humidity, battery, luminance, power, voltage, current, energy), updates "last seen", and registers and cleans up capability listeners. Importers: 1.lib/mixins/CoreCapabilityMixin.js(P2330) — two helpers (sub-capability and per-gang flow triggers) for drivers that do not inherit fromBaseUnifiedDevice; it only fires cards that are really declared, through the app's flow loader. Importers: 0.lib/mixins/DeviceEnhancementsMixin.js— a set of about twenty opt-in improvements, each switched on by a setting or by the presence of a capability: temperature and humidity offsets, power-on behaviour, dimmer minimum/maximum and transition time, thermostat schedule, radar settings, valve position, power factor, link quality and more. Importers: 0.lib/mixins/LockControlMixin.js(P130) — makes thelockedcapability writable: the lock command goes first through the device I/O facade as a Tuya DP (DP1 by default, overridable), then the plain Tuya command path, then the ZCL Door Lock cluster, and the UI is updated after a successful send. Importers: 2.lib/mixins/NaturalLightMixin.js— when theenable_natural_lightsetting is on, adjustslight_temperaturethrough the day to follow the daylight colour cycle; owns its timer and stops after the device is deleted. Importers: 0.lib/mixins/PeriodicAutoEnricherMixin.js— refreshes values only (it no longer adds capabilities): 10 minutes after init and then every 4 hours it reads the ZCL attribute behind each capability the device already has, for devices that only report on change or go stale after sleeping. Importers: 2.lib/mixins/PowerSwitchFeaturesMixin.js— adds the two common Tuya switch settings, power-on state on DP12 (off, on, remember) and backlight mode on DP2 (off, normal, inverted), with read and write helpers for flow cards and a fallback write path; it does not replace the switch base's own settings handling. Importers: 1.lib/mixins/SmartEnrichmentMixin.js— looks up the device's manufacturer name and model id in the mapping database and adds the capabilities of the matching category; skips quietly when either id is missing. Importers: 0.lib/mixins/TuyaThermostatEnhancedMixin.js— on init, asks a radiator valve or thermostat which optional DPs it answers (boost DP101, frost protection DP10, child lock DP40, open-window detection DP8) and only then adds the matching capabilities and listeners, so a valve that lacks a feature never gets a dead control. DP numbers follow the Z2M TS0601 thermostat definitions. Importers: 1.
Pairing helpers
lib/pairing/AntiFallbackGeneric.js— tells whether a device landed on a generic or fallback driver and, from the clusters on endpoint 1, suggests a better family (Tuya EF00, IAS Zone, On/Off). A suggestion only, nothing is moved. Importers: 1.lib/pairing/AutoDetectionPairingWizard.js— scores candidate drivers for a new device from manufacturer and product id patterns and from its capabilities, returns the best match with a confidence and a set of default settings for common devices. Importers: 1.lib/pairing/DynamicEndpointDiscovery.js(P2410) — many Tuya devices do not use endpoint 1. This module lists the endpoints and clusters the node advertised in its pairing interview (the only safe "advertisement" an app sees), summarises them for logs, and picks the functional endpoint, preferring the one with the Tuya cluster when asked. Importers: 3.lib/pairing/EventDeduplicator.js— drops the same capability value arriving twice within a short window (300 ms by default), so two report paths for one press do not fire a flow twice. Importers: 2.lib/pairing/TuyaTimeSyncEngine.js— some Tuya sensors stay silent until they get the time. It sends a Tuya time frame on the Tuya cluster, or a ZCL Time answer (seconds since 2000-01-01), on endpoint 1 or the first endpoint, with manufacturer-aware choice of epoch. Importers: 3.