Performance helpers, protocol helpers, profiles and pairing pieces (hand-written reference)
Written 2026-11-15 for the documentation coverage work (P3290, queue item 5), continuing MODULES_MANAGERS_MIXINS_AND_PAIRING. 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 nothing loads the module today (kept for reference, candidate for a later review, never removed without a check). Modules only reached through lib/performance/index.js or lib/pairing/index.js count that index as their single importer.
Battery and pairing
lib/battery/button-battery-report.js— two pure checks used byButtonDeviceso a battery tile never shows a made-up value.batteryTileReportIsFresh(value, reportAt, now, maxAgeMs)is true only when the percent is above 0 and a real report time exists that is younger than 24 hours (the same window as the battery-report setting; the setting alone does not prove the radio sent anything).storedBatteryMayRestore(stored, fromReport)lets a stored percent (1–100) be shown after a restart only when a real sample path set the "from report" flag. A stored 100 with no report behind it is therefore not painted. Importers: 1.lib/pairing/UXMessages.js— table of short pairing status texts (device detected, waiting for time sync, clusters incomplete and similar phases) in English, French, Dutch and German, withget(key, lang)falling back to English. Importers: 0.lib/pairing/UniversalPairingManager.js— pairing-time helper that identifies a device from its interview, applies a known quirk (fixed endpoints, cluster replacement), guesses a device type from the clusters and runs a matching configuration step (Tuya DP, switch, light and so on). Pattern ideas come from the ZiGate project; the code is our own. Reached only throughlib/pairing/index.js. Importers: 1.lib/pairing/logPairingIdentity.js(P2366) — many "Unknown Zigbee Device" diagnostics arrive without manufacturer name and product id, so at pairing the driver logs one[PAIR-ID]line per new device with driver id, manufacturer name and product id (ABSENTwhen missing, read from settings first, then device data) and a truncated IEEE address. Used byBaseZigBeeDriverand the 4-button scene switch driver. Lead L-P3290-02: the line also prints the user's device name and part of the IEEE address, which the privacy rule asks to keep out of logs or replace with placeholders. Importers: 2.
Performance helpers (lib/performance/)
All five are classes exported through lib/performance/index.js; none is wired into a device by default today. They are bounded building blocks for the limiter work (queues, budgets, rotation), each with its own stats.
AutoDiscoveryPollingOptimizer.js— adaptive discovery polling: the interval shortens when the network is busy and lengthens when it is quiet, devices wait in a priority queue (with a reason) and are scanned in small batches with a cooldown between polls;start()/stop()own the timer. Importers: 1.DiagnosticLoggerRotation.js— in-memory diagnostic log with levels and categories, rotated when the buffer grows past a size limit or after a set time; older buffers are kept in a capped, compacted archive that can still be filtered withreadArchived(). Importers: 1.FragmentBufferMemoryLimiter.js— accounting for fragment reassembly buffers: eachallocate(device, buffer, bytes)is checked against a per-device and a global memory budget, the least recently used buffers are evicted when a budget is exceeded, and a memory-pressure event is emitted.release,clearDeviceandclearAllfree the bookkeeping. Importers: 1.SmartClusterEngineThrottling.js— queue for cluster reads and writes: per-device queues, a priority order, batching of bulk operations and a rate limit that adapts when the network looks congested; a device that is being throttled is skipped until its slot frees up. Importers: 1.TuyaDPCompression.js— compacts stored DP history: repeated strings become dictionary indexes, numeric series are delta encoded, repeated values are run-length encoded, and small values are packed; every compress function has a matching decompress. Importers: 1.
Declarative profiles
lib/profile-engine/ProfileEngine.js(P-KB2) — loads optional device profiles fromdata/profiles/*.json. A profile matches exact manufacturer + product couples, may list whitelabel vendor/model names, maps DPs to capabilities with conversion steps (optionally writable and on an endpoint), can carry per-firmware or per-manufacturer variants, settings such as power-on behaviour or child lock, small quirks (cluster replacement, extra reporting, attribute fixes) and its source. The format borrows the idea of deCONZ device description files, tuya-local configs and Z2M whitelabels; schema and code are our own. Exposesfind,resolveDps(base merged with the first matching variant),decode,encode,settingWriteand a kill switch. Importers: 1.lib/profile-engine/ProfileLayerAttach.js(P-KB3) — attaches that engine toTuyaZigbeeDeviceafter the native setup. It only fills capabilities the device already has (never adds or removes one, so a thinner interview cannot drop anything), leaves DPs the driver already maps to the driver, applies Z2M-style options (debounce, throttle, filtering, optimistic) only when the user set them, and keeps runtime quirks bounded and best effort. Off switches: device settingprofile_enginefalse, app settingprofile_engine_offtrue, or envPROFILE_ENGINE_OFF=1. Importers: 1.lib/profiles/LinptechES1Profile.js(P2258, P2261, P2267) — settings for the Linptech ES1ZZ(TY) / Moes ZSS-LP-HP02-MS mmWave presence sensor (TS0225, recognised by three verified manufacturer suffixes). Settings are written as ZCL attributes on the manufacturer cluster 0xE002 listed in the interview (fallback 0xE001 if refused) rather than as EF00 DP 9, which the device uses for the distance report. Covers keep time, motion and static sensitivity, LED indicator and distance limits, with value clamping and a write plan per setting key. Used by the mmWave radar driver. Importers: 1.
Protocol helpers (lib/protocol/)
BindingPersistence.js— keeps the list of Zigbee bindings (and group bindings) in the device store, checks after a rejoin which ones are missing and binds them again, and offers lookup helpers. Importers: 0.BitmapMultiFieldParser.js— splits a Tuya DP that packs several settings into one byte or bitmap into named boolean or numeric fields, builds the value back from fields, and updates a single field without touching the others; field layouts are registered per DP. Importers: 0.DPFragmentationHardening.js— reassembles DP payloads that arrive in several frames: sessions per device and DP, duplicate and out-of-order fragments handled, checksum check, missing fragments reported, a capped number of sessions (oldest evicted) and a cleanup timer (every 10 s by default) that drops timed-out sessions. Importers: 0.HardwareDetectionShim.js— run in the background step ofBaseUnifiedDevice: it inspects the interview and a few Tuya DPs, works out power source and whether the device is a USB outlet, and computes corrections (add voltage, current or LED mode on a USB outlet, renameonoff.button2toonoff.usb2, add capabilities for a DP pool). Lead L-P3290-01: it can also remove capabilities (battery on a device it judges AC powered, voltage and current on a driver withusbin its id when the voltage DP was not seen, and the old name in a rename), which goes against the "no capability loss, additive only" rule; to be made add-only with a regression test, on master after the publish hold. Importers: 2.HybridProtocolArbitrator.js— tells whether a device speaks plain ZCL, Tuya EF00 or both (from the clusters on its endpoints) and drops a repeated identical capability value arriving within 300 ms from the other path; the recent-event memory is a bounded map of 512 entries. Used byBaseUnifiedDevice. Importers: 1.MoesZemismartActionMerge.js(P2834) — for Moes and Zemismart devices, which mix ZCL, EF00 DPs, raw frames and late DP learning, it detects the brand from the manufacturer name, enriches the detected protocol info and gives the command router an ordered write path (named ZCL, raw ZCL, Tuya DP, raw EF00, then soft DP detection) plus a ranking boost. Devices marked ZCL-only stay ZCL-only, and no product id is invented. Importers: 3.OccupancySensingEnhancement.js— occupancy zones with a hold time before clearing, sensitivity levels, aggregation of several zones and fusion of PIR and microwave inputs; emits occupied/vacant with a duration. Importers: 0.ScheduleDataEncoder.js— static encode and decode helpers for Tuya schedule DPs: a switch timer slot (hours, minutes, action), a thermostat slot (hours, minutes, temperature), a curtain timer slot and whole weekly schedules made of those slots. Importers: 0.