A Zigbee2MQTT converter for a nameless switch

The switch has no useful model string. Zigbee2MQTT interviewed it, filed it under a generic Tuya device, and then published battery percentages whenever I pressed gang 2. The cluster traffic was fine. The converter was guessing.

What the frames actually are

I turned on debug for a day and pressed one gang at a time. Datapoint 1 through 4 are the buttons, each a boolean. Datapoint 10 is a battery percentage that arrives on its own schedule, not on a click. The stock converter had collapsed those into one expose because the manufacturer name was empty and the fingerprint matched a remote it already knew.

External converter

I left the herd alone and dropped a file into data/external_converters. The interesting part is the fz map, not a new quirk in the coordinator.

const fz = require('zigbee-herdsman-converters/converters/fromZigbee');
const exposes = require('zigbee-herdsman-converters/lib/exposes');
const e = exposes.presets;

module.exports = [
  {
    fingerprint: [{modelID: 'TS0044', manufacturerName: '_TZ3000_example'}],
    model: 'bench-four-gang',
    vendor: 'bench',
    description: 'Four-gang switch, local converter',
    fromZigbee: [fz.ignore_basic_report, fz.battery],
    toZigbee: [],
    exposes: [e.battery(), e.action(['1_single', '2_single', '3_single', '4_single'])],
  },
];

The fingerprint in the note is the shape, not a device I expect anyone else to own. The real manufacturer token stays in the converter on the broker host. Publishing it here would only help the next interview pick the wrong file.

Action values are events, not state. Home Assistant automations should fire on the action changing, and the converter should not retain a fake "on" for a gang that is only a button.

What went wrong first

My first converter reported each gang as a switch. The wall plate does not latch. Zigbee2MQTT then showed four switches stuck on after a single press, and a blueprint toggled the hall light twice. Events fixed it. Battery stays a separate numeric expose and updates a few times a day.

After the file loaded, I re-interviewed the device once. Old retained discovery messages had to be cleared or Home Assistant kept the phantom switches next to the new action sensor.