NOTE: These instructions are preliminary for those testing the beta units. This documentation is not complete and will change with future firmware updates.
The XTension 6 Channel PWM Dimmer Module provides 6 Channels of frequency adjustable, reasonably high current, PWM for controlling LED or other 12 or 24 volt volt lighting. Outputs can also be set to non-dimmable to control devices that do not want to be PWM’ed. Other voltages can also be used by using a separate power supply for the LEDs and the PWM Module itself. 9 channels of highly configurable GPIO are also available for controlling or reading other information. Up to 16 1-wire temperature sensors can also be connected.
An instance of XTension running on the same subnet as the device is required. Only one instance of the XTension Kits Plugin needs to be setup to support any number of XTension kit devices on the same subnet.
In XTension visit the Interface Status window and click the New Interface button in the toolbar. Select “XTension Kits” from the plugin/Device popup. Give the interface a descriptive name and save it. Now back in the Interface Status window check the enabled checkbox next to the new entry you just created.
When the device is powered up for the first time, the Setup button is pressed or there are no wifi networks configured, it will start it’s configuration access point. When in Setup Mode the LED will flash quickly twice every second. See the “Status LED Patterns” section below for more info on the status LED. From your mobile device or with a laptop join this wifi network. A captive portal will display with a subset of settings for the device. From here you can enter up to 3 wifi networks to connect to. The device will chose the one with the best signal strength. Here you should also give the device a better name and bonjour/mDNS name than the defaults. If you wish you can also set a static IP address or change other networking parameters at this point. Click the save and restart button to make your changes live. The device will restart and if it connects properly to wifi the captive portal will disappear and your device will reconnect to the previously selected WiFi network.
Once the device has joined your WiFi you can visit the built in control and config web server with any browser. On the main page you will see controls for all 6 output channels bot simple on/off as well as setting the value. If you have configured any GPIO for inputs or outputs their values or controls will also be shown here. If you have 1-wire temperature sensors of DHT-22 sensors setup they will also display here.
The default PWM frequency for all the output channels if 5kHz. This is high enough that you will never see a flicker in the controlled LED’s. For some balasted LED bulbs like 12v MR16 style or others that frequency is far too high and they will overheat or not operate properly at all. Before using any ballasted LEd bulb please verify that the device is handling the PWM frequency OK and it not overheating or otherwise causing a problem.
The frequency can be changed in 4 groups. Channel 1 is it’s own group, Channels 2 & 3 are set together, Channel 4 is it’s own group, and Channels 5 & 6 are set together.
Channels 1, 2 and 3 or 4, 5 and 6 can be groups as an RGB color channel. If this is setup then another unit will be created in XTension that shows as being fully color capable. Since LEd strip lights tend to be very blue or green heavy and the red channel tends to be under powered you can set multipliers as compensation for each color channel when calculating the levels. If the red needs to be bumped up you can set the Red compensation to 1.2 and any read level will be multipled by that before going to the output. You can set the blue channel to 0.7 and then the blue output would be reduced by that amount before being sent to the output.
Up to 3 pairs of outputs can be configued as warm white/cool white devices. Any channel can be selected as the warm or cool channel in the popups. They do not have to be sequential or in any particular order. A min and max color temperature can be entered which theoritcally should be the color temperature of your warm and cool leds. With these setup another unit will be created in XTension that shows the standard color temperature controls with a slider for color temperature and will respond to any of the color temperature commands. The levels of the warm and cool leds will be set as a ratio given your color temperature request.
Each channel can then be given a descriptive name.
Once you have completed the PWM channel settings click the Save and Restart button at the bottom and wait for the status to finish waiting for the device to re-appear.
In order to use 1-wire sensors you must enable them on this page. Here you can also set the time for scanning the buss as well as choose if the outputs should be F or C. Note that this setting also affects any DHT-22 devices that you might connect to other GPIO pins.
In order to use the GPIO pins you must enable them on this page.
There are 9 GPIO pins brought out to the 12 pin removable header on the top of the device. In addition to a GND pin, access to 3.3v and the 1-wire bus. They have different capabilities as available in the popup. Those with special capabilities like Touch Sensing or Analog Input will have that listed next to the type popup as well as being available in that popup.
See the section below about GPIO Ratings and Safe Usage for more information. GPIO capabilities are different for each pin, some supporting higher level functions and more interesting connections. See the table below for more info and also the user interface on the web page though that is incomplete as of this beta version.
GPIO Function Description:
The pins brought out to the screw terminals have extra protection to try to protect the CPU from excessive voltage or spikes from static but it is still definitely possible to damage or destroy the CPU by using these improperly. The aux GPIO on the expander connector may have other limitations and not support all the functionality. (BETA: As of this beta version the capabilities of these are not limited in the UI so you can select functions they won’t support.) The maximum current output per GPIO pin should be limited to 12ma and the total output from all the GPIO pins should be limited to 40ma. In reality the ESP32 seems to support quite a bit more than this without damage but if you do that you are taking your fate into your own hands. If you need to run more than a 5mm led from a GPIO pin directly you should use the GPIO to turn on a transistor or mosfet. There are many diagrams and tutorials available for safely connecting such things to an esp32 or arduino. In the case of an NPN channel mosfet no other hardware is required, in the case of a transistor a 1k or so resistor in between the GPIO output and the transistors gate is required or the transistor will burn itself out fairly quickly.
A more common use of the GPIO may be controlling relays. Please do not connect a relay directly to a GPIO pin as it will draw too much current and the back EMF pulses from the coil will eventually destroy the ESP32 chip. A transistor or mosfet control as well as a snubber circuit is absolutely required to control such a thing from a GPIO output. There are many inexpensive logic level relay boards available on the internet that are optically isolated and can be used directly from the GPIO pins. A 3.3v relay board can be powered from the 3.3v output on the board itself as long as the entire current usage with all the relays on doesn’t exceed an amp. The GPIO output can be used to control a 3.3v board of this type as well as a 5v board of this type, but if a separate power supply is needed the grounds must be connected to the ground on the GPIO board or they cannot talk to each other. 12 volt relays can probably be used also and possibly powered from the same 12v power supply that is used to power the GPIO board. The boards I have tested with however have not been activated by the level of output possible at 3.3v that is output from the GPIO. I have had success by removing the jumper on the boards that connect the relay power with the logic power and powering the logic on the board from the 3.3v supply and the relay power directly from the 12v supply. This has let me use several 12v relay modules successfully here, but there are so many out there that your experience may be different. I will create a page with details on how to separate the 2 power sections on most of the relay boards at some point or drop me a note if you need that sooner.
Repeat! Do NOT just connect the coil of a relay to a GPIO output. It will damage or destroy the ESP32.
Most device settings including WiFi can be set from this page:
After making any changes you must click the Save and Restart button to make them live. If you navigate to another page of the interface after making changes they will not be saved.
You can manually upload firmware update files, or start an over the internet update from the firmware update page. When you load the page the current firmware version, current web interface version and the hardware revision of your board are displayed. A check for update is started and if there is firmware available for your specific device and hardware revision it will be displayed here and a button will show to let you start that update automatically over the internet.
Note that when doing an update over the internet the device may restart twice as the web interface and firmware are loaded in separate steps.
Most software updates will include both a Firmware file, The file name will end in .bin and include somewhere in the name the hardware revision. For example a firmware update for the initial unit with a hardware revision of “GPIO2” will be named something like “gpio firmware.134.GPIO2.bin. The web firmware will also include the hardware revision but will end in “.spiffs”
Unless an update has specific instructions to the contrary you should load the firmware file first, and then the web interface file.
Once a file is uploaded the hardware revision is validated and if it matches the software is loaded. Upon success the device will reboot and the page will reload showing the new firmware version. If you have a second web interface file load it at this time.
The GPIO device has a status LED that will flash different patterns depending on the connection state. During startup the LED will do a quick breathing animation to let you know that the hardware and firmware has loaded.
If the device has no WiFi networks configured or at any time if you press the setup button it will go into setup mode and advertise it’s own configuration wifi access point for you to conenct to. When in Setup Mode the Status led will flash twice quikly every second.
During the connection to WiFi the status LED will flash 1 second on and 1 second off. Normally it takes about 15 seconds or less to connect to the network. If this continues for much more than that you should check the SSID and password you entered and that the WiFi is within range. You can press the setup button during this process to skip the connection and restart the Setup access point.
If the wifi has connected but no XTension has found the device the status LED will quickly flash once a second. This is also displayed if the XTension connection checkbox on the device settings web page is turned off.
In normal operation with a valid XTension connection the LED will be dimly lit to indicate that everything is working properly. You can configure the brightness of the LED or even set it to 0 if you do not wish the LED to be lit all the time. This setting is available on the settings web page. If the wifi drops or the connection to XTension is lost the LED will change to the appropriate state to indicate that.