zigbee-herdsman-converters

Before submitting a pull request, run the following commands to ensure your changes pass linting, build, and testing requirements. If any command fails, the PR will likely be rejected.

1. pnpm run check --fix: Runs linting and automatically fixes issues where possible.
2. pnpm run build: Compiles the project.
3. pnpm test: Executes the test suite.

To develop or test changes locally, you must install pnpm and use it to install dependencies with the frozen lockfile to ensure environment consistency.

Prerequisites:

• Node.js and npm installed

Steps:

1. Install pnpm globally.
2. Run pnpm install --frozen-lockfile in the repository root.

npm install -g pnpm
pnpm install --frozen-lockfile

Some Sengled flood lights (like model E13-A21) include a custom manufacturer-specific cluster manuSpecificSengledMotionSensor (ID 0xfc01) for motion sensing control.

Available attributes and controls:

• trigger_condition: Choose between dark (0) or weak_light (1) conditions using m.enumLookup.
• enable_auto_on_off: A binary toggle to enable/disable automatic turning on when motion is detected.
• motion_status: A binary attribute that reports whether motion is currently detected.
• off_delay: A numeric value (30 to 14400 seconds) determining how long the light stays on after motion is triggered.

All these controls require the manufacturer code 0x1160.

For certain Ledvance plugs that include an energy meter, the device frequently reports six electrical measurement divisor/multiplier constants that do not change. To reduce radio traffic by approximately 75%, you can use the silenceDivisorReporting extension.

This extension is an optimization that runs after the electricityMeter() extension during the configuration phase. It uses setupAttributes to manage reporting for the following attributes in the haElectricalMeasurement cluster:

• acPowerDivisor
• acPowerMultiplier
• acCurrentDivisor
• acCurrentMultiplier
• acVoltageDivisor
• acVoltageMultiplier

Note: This is an optimization and is designed not to fail the device configuration run if it encounters errors.

The exposes property in a definition tells the system what features and properties a device has. This is used to generate documentation and to inform the UI/API about available controls.

You can use various helper classes to define these capabilities:

• Binary: For on/off or boolean states.
• Switch: For switches.
• Light: For dimmable or RGB lights.
• Numeric: For numeric values (temperature, humidity, etc.).
• Enum: For fixed sets of values.
• Climate: For thermostat/climate control.
• Cover: For motorized covers/blinds.
• Lock: For door locks.
• Fan: For fan speed controls.
• Text: For string values.
• List: For lists of items.
• Composite: For grouping multiple properties.
• Feature: For generic features.

exposes can be an array of Expose objects or a function that returns them based on the device state.

Many Profalux remotes do not support standard battery reporting. For these devices, battery voltage is retrieved via a polling mechanism.

• Polling Interval: Once every 24 hours (60 * 60 * 24 seconds).
• Voltage Range: The voltage is converted to a percentage based on a range of 2200mV to 3100mV.
• Implementation: The system polls the genPowerCfg cluster for the batteryVoltage attribute.

In version 22.0.0, addDefinition was renamed to addExternalDefinition, and importing zigbee-herdsman-converters no longer exposes all definitions directly. To access definitions, you must import from the devices index and prepare them using zhc.prepareDefinition.

(await import('zigbee-herdsman-converters/devices/index')).default.forEach((baseDefinition) => {
    const d = zhc.prepareDefinition(baseDefinition);
});

The Centralite HA thermostat (3156105) supports a heat_pump_mode option.

• Option: heat_pump_mode (Binary)
• Default: true
• Usage: Set this to false if you are NOT using heat pump mode.

When heat_pump_mode is enabled (via options.heat_pump_mode), the converter applies translations to the runningState attribute of the hvacThermostat cluster to ensure compatibility.

// Example configuration option for model 3156105
options: [
    new exposes.Binary("heat_pump_mode", exposes.access.SET, true, false).withDescription(
        "Set this false if you are NOT using heat pump mode (default true).",
    ),
],

The light_brightness_move converter allows for continuous brightness movement (fading).

• Key: brightness_move or brightness_move_onoff.
• Input Formats:
  • Number: A positive number moves brightness up at the specified rate; a negative number moves it down. A value of 0 stops the movement.
  • String: Supports `

The light_colortemp_move converter allows for continuous color temperature movement.

• Key: colortemp_move or color_temp_move.
• Input Formats:
  • Number: Positive moves to warmer (higher Mireds), negative moves to cooler (lower Mireds). 0 stops movement.
  • String: Supports `

To trigger a factory reset for Philips Hue devices, use the philips_hue_factory_reset action. This requires providing the target extended_pan_id and an array of 6-character hex serial_numbers.

Example Payload Structure:

{
  "extended_pan_id": "0x0011223344556677",
  "serial_numbers": ["aabbcc", "ddeeff"]
}