Flow helpers, energy, pairing helpers and I/O layers (hand-written reference)
Written 2026-11-03 for the documentation coverage work (P3254, queue item 5), continuing MODULES_CORE_AND_CLUSTERS, MODULES_DEVICES_AND_DIAGNOSTICS and MODULES_DYNAMIC_AND_FEATURES. Each entry says what the module is for, when it runs and what it must never do. They are optional layers: none is required for pairing, and a failure in any of them must leave the native Homey path working. See CODE_REFERENCE for the header line of every file and DOC_COVERAGE for what is still undocumented.
Energy
lib/energy/PowerSourceResolver.js— pure functions (no timers) that answer "how many watts is this device using" with one fixed precedence: a real meter reading, then a value calculated from voltage × current (× power factor, summed over phases), then the power the user typed in, then a per-couple default, a per-driver rule and finally a per-class default fromdata/energy/default-power.json. Defaults are labelled as estimates and always lose to a measured value.lib/energy/mainsEnergy.js— builds the Homeyenergyobject for a device that has just been confirmed as mains powered. Some switch and dimmer drivers declare batteries in their manifest because they also host battery variants; for the mains devices of those drivers (on/off only, no power meter) it hands the resolver's default to Homey as an approximation the user can still edit. Only constant and linear-dim curves are passed.
Mesh view
lib/features/ZigbeeMeshMap.js— builds the mesh "spider web" shown in the app settings (master only). It is a passive snapshot of this app's paired devices and the link quality / signal values Homey already knows; it never sends neighbour-table requests, which would flood sleepy devices. Homey does not give apps the coordinator's neighbour table, so links are last-hop quality to Homey, and any parent router it draws is marked as inferred, never shown as a real hop.
Flow cards
lib/flow/ActuatorFlowHelper.js— shared helpers for "turn on/off/toggle/set" action cards. A command goes first through the device's own capability listener (the normal Homey send path), then the value is mirrored on the capability; device helpers and the I/O facade are fallbacks. A missing device shape is resolved softly instead of failing the flow.lib/flow/DeviceSettingAction.js— the app-level "set a device setting" action. It offers only editable manifest settings (number, checkbox, dropdown, text), converts and clamps the value to the setting type, saves it and then calls the device'sonSettings()with the changed key, because Homey does not call it for changes made by code and that call is what pushes the value to the hardware. Error messages are localised (en, fr, nl, de).lib/flow/FlowCardDeviceResolve.js— small helpers that normalise a dropdown argument to an id and build the trigger state from the tokens, so a per-button trigger card only fires for the button that was pressed (an empty state made every button card fire, or none).lib/flow/FlowCardGetters.js— thin re-export of the safe card getter and the stub installer from the Homey compensation layer plus the flow heuristics. It never patches the Zigbee driver prototype itself (that is owned bylib/drivers/ZigBeeDriverFlowCardPatch.js).lib/flow/ManifestDriverFlowIndex.js— Homey compiles everydriver.flow.compose.jsoninto the root app manifest with adriver_id=filter, sodriver.manifest.flowis empty at runtime. This index is built once from the root manifest (references only, bounded by the number of drivers) so that card auto-wiring and capability-trigger discovery still find each driver's cards. Callers try the driver manifest first.lib/flow/PlaceholderActionWiring.js— some generated action cards used to log and return success without doing anything. A small static map (config/flow/placeholder-action-wiring.json) links such cards to a standard capability or method, and the command goes through the device's own capability listener. Unmapped cards keep their old behaviour; a command that was really sent and failed is now reported as an error.lib/flow/SceneRecallCards.js— adds a raw "scene recalled" trigger (scene number and endpoint tokens) for any remote that sends a ZCL Scenes recall or a current-scene report, next to the existing button cards. Duplicate reports from two detectors on the same device are merged within 500 ms.lib/flow/SwitchActuatorFlowAutoWire.js— scans the switch, wall-switch and plug drivers' cards by name pattern (per-gang on/off/toggle, all on/off, "gang is on") and registers a run listener where one is missing, so Then cards always execute. Gang commands go through the shared gang control helper; each card is registered only once.
Endpoints, health and pairing helpers
lib/green_power.js— central rules for utility endpoints: never bind, configure reporting or read attributes on endpoint 242 (Green Power) or endpoint 0 (device management), and ignore Green Power proxy device ids. Drivers ask it for the list of usable endpoints.lib/health/DeviceHealthDashboard.js— builds a cached (30 s) summary of the app's devices: counts by state (healthy, stale, dead), a network health score, low (20 %) and critical (10 %) battery lists and simple trends. Read-only; it only aggregates what the health monitor already knows.lib/helpers/CapabilityCleanup.js— removes capabilities that cannot belong to a device class (for example on/off or dim on a sensor, luminance on a socket), left over from a wrong driver or a wrong guess. It works from a small per-class deny list.lib/helpers/ColorConverter.js— converts a colour temperature (mireds or kelvin) to an approximate RGB value with the usual black-body approximation, for bulbs that only accept colour and not white temperature.lib/helpers/CustomPairingHelper.js— handlers for a custom pairing view when several drivers match the same fingerprint: it keeps the discovered device, lists the candidate drivers and lets the user pick one. SDK3 style (uses the driver'shomey, no global require).lib/helpers/DeviceHintsDatabase.js— a hint table from manufacturer name to the recommended driver, device type, protocol and expected capabilities (sometimes a DP map). It is advisory for the identification helpers and never overrides the manifest's exact mfr+pid placement.lib/helpers/IntelligentDPAutoDiscovery.js— compatibility path that re-exports the hardened DP learner inlib/sensors/IntelligentDPAutoDiscovery.js, so old imports keep working.lib/helpers/ManufacturerCatalog.js— groups manufacturer names and prefixes into product categories (plug, USB outlet, motion, climate…) with their typical capabilities and flow ideas. Used for grouping and suggestions, not for pairing.lib/helpers/PairingHelper.js— gives the user feedback during a standard pairing session (searching, found, nothing found) instead of a silent screen.lib/helpers/QuietMainsAvailPoll.js— pure check that tells whether a mains device (Sonoff mini/basic family by model id, no battery capability) is one of the quiet ones that rarely report, so availability is confirmed by a light poll instead of being marked unavailable.lib/helpers/TuyaOnOffSettingsSync.js— read-only start-up sync of the Tuya on/off manufacturer attributes (child lock 0x8000, indicator mode 0x8001, power-on state 0x8002) into the existing device settings. Each attribute is read on its own, only valid values are stored and nothing is written to the device. The standard ZCL start-up on/off attribute is a different contract and is not handled here.lib/helpers/VirtualCapabilities.js— values derived in the app when the hardware does not provide them: apparent power, power factor, energy cost and daily energy (reset at midnight), plus last-seen and signal strength.lib/helpers/powerUtils.js— battery best-practice helpers. The app treats devices as hybrid, so battery capabilities are not removed from mains devices any more; when a device has both a battery percentage and a battery alarm, the percentage is kept and the alarm removed (Homey best practice).
Raw data and I/O layers
lib/interpreters/UniversalRawInterpreter.js— decodes raw Zigbee data that does not go through the standard Homey paths: ZCL frames from unknown clusters, manufacturer-specific commands, non-standard Tuya DP frames, raw IAS zone status. It parses the frame control and global commands and returns a description; it does not set capabilities on its own.lib/io/healZigbeeNodeIdentity.js— when Homey loses the IEEE address on the Zigbee node after a re-pair (the "missing IEEE address" error that left dimmer controls dead), it puts the address back on the node from every known source so the device can send again. Short cache to avoid repeating the work.lib/layers/LayerInterface.js— common contract for the non-native channels (Tuya 0xEF00, 0xE000–0xE002, manufacturer clusters, raw frames): read, write, command and report, time-boxed, never throwing, with a per-layer circuit breaker that disables a failing layer for a cooldown and logs once per transition. Native ZCL clusters are not wrapped.lib/layers/LegacyLayerAdapters.js— exposes the existing low-level bridge and the RX/TX chain through that contract without changing them. The native ZCL path comes first and is called directly; the non-native paths are wrapped so they cannot block pairing or device init.lib/layers/ReconnectBurstCoalescer.js— after a power cut, wall switches send relay, backlight and button-mode reports within a few dozen milliseconds. Inside such a burst the last value per capability wins (short coalescing window) so nothing is lost and the intermediate stampede is not applied.lib/layers/commitCapability.js— single entry point for incoming values (Tuya DP, IAS, battery reporters): battery goes through the battery ingest path, other values through the cross-layer confirmation, with a plain safe setter as last resort, so the signal-fusion layer really sees production traffic.
Lighting
lib/lighting/AdaptiveLightingCurve.js— pure maths for the app's adaptive lighting: colour temperature follows the sun's elevation (warm near the horizon, cool at midday) inside a 2000–5600 K envelope, then is clamped to what the bulb can render, with brightness kept between 35 % and 100 %. No timers or I/O; shared by Zigbee, Tuya DP and Tuya Wi-Fi lights through the standardlight_temperaturecapability.