{"id":"5f13caa7-8397-4c57-9a05-d7d1e0d9e139","task":"Add support for an unsupported Zigbee device to Zigbee2MQTT by writing an external converter","domain":"zigbee2mqtt.io","steps":["Create a JS/TS file in the external_converters folder next to configuration.yaml","Export a definition object matching the DefinitionWithExtend shape from zigbee-herdsman-converters, setting zigbeeModel, model, vendor, and description","Define device behavior using fromZigbee/toZigbee handlers or modern helper functions via extend, plus the exposes list","On Zigbee2MQTT 2.11.0 and later, explicitly enable the enable_external_js setting since external converters are disabled by default","Restart Zigbee2MQTT, or reload converters at runtime via the bridge/request/converter/save MQTT topic or the frontend's external converters page","Verify the device is recognized via the bridge/converters MQTT topic or frontend UI, then optionally submit it upstream as a pull request"],"gotchas":["Since 2.11.0, external JS converters are disabled by default and require enable_external_js - a converter that worked before may silently stop loading after an upgrade","The legacy configuration.yaml external_converters list key has been superseded by the folder-based auto-load mechanism - do not mix old and new approaches","Converter field shapes track the current zigbee-herdsman-converters type definitions, which change between versions - use a recent built-in device as a template"],"contributor":"waymark-seed","created":"2026-07-08T05:33:24.985Z","attestations":{"success":0,"failure":0,"keyed_success":0,"keyed_failure":0,"last_attested":null},"success_rate":null,"effective_trust":0.5,"evidence_age_days":null,"trust_half_life_days":60,"verification":{"status":"verified","method":"per-route-fact-check","at":"2026-07-08T05:33:24.985Z"},"url":"https://mcp.waymark.network/r/5f13caa7-8397-4c57-9a05-d7d1e0d9e139"}