External Converter Script for OzNexis Smart Light Switches & GPOs in Zigbee2MQTT
If you're integrating OzNexis Zigbee Smart Switches or GPOs into your Home Assistant environment using Zigbee2MQTT (Z2M), you may find that certain advanced features—such as full LED color customizing, switch mode changing (toggle vs. momentary), backlight controls, or power-on behavior—require a specialized communication script, known in Zigbee2MQTT as an External Converter.
Overview: Why is an External Converter Script Needed?
1. What does the script do?
The script acts as a custom External Converter (communication protocol) for Zigbee2MQTT. It translates raw data points from the physical switch into recognized Zigbee2MQTT entities and features. This enables full control over functions including:
- Customizing LED status light colors and brightness levels (ON/OFF state colors).
- Switching between toggle and momentary physical switch modes.
- Configuring backlight behavior, key sounds, and child lock options.
- Accessing accurate energy metering, power-on behavior settings, and multi-gang controls.
2. Which devices need this script?
-
Required for: All OzNexis Zigbee light switches, dimmers, fan controls, curtain switches, and GPOs operating via Zigbee2MQTT.
3. Are there any risks?
There is no risk to installing or running this script. It simply acts as a software mapping layer inside Zigbee2MQTT to ensure all endpoints and functions are properly recognized by Home Assistant.
Step-by-Step Installation Guide
Follow these steps to add the OzNexis External Converter script to your Zigbee2MQTT interface:
Step 1: Open Zigbee2MQTT and Step 2: Navigate to Settings
In your Home Assistant side panel, click on Zigbee2MQTT to load the main panel. Then, in the top right navigation bar of the Zigbee2MQTT interface, click on Settings:
Step 3: Open the External Converters Tab
Within the Settings sub-menu, locate and click on External Converters:
Step 4: Add a New Converter
Under Add or update external converter, ensure the dropdown menu is set to N/A - Create new converter:
Step 5: Name the Script and Step 6: Paste the Script Code and Save
In the Name input box, give your script file a name ending with .js, then copy the entire Script code block provided below, paste it into the Code window, and click Save:
Script: Click HERE.
