Mac Home Automation

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.

• Dimmable: a checkbox to make a channel dimmable or not. A channel with this turned off will turn on for any level command above 0 and off for a level of 0. It will also respond to the on/off commands as you would expect.
• Default Ramp Rate: If no rate value is specified in the command from XTension any change in value will take place in this amount of time. The value is in seconds and the default is 0.5
• Limit Max Brightness to: Sometimes it is helpful to be able to limit the maximum brightness of specific channels. This can also be used to tune color outputs but is most helpful in keeping some strips or other LEDs from overheating and reducing their lifespan. This is a percent value and is used to scale the values as sent in a standard dim or bright command. For example, your commands will still go from 0 to 100% but will be scaled by this percent so that 100% is really only 80% or whatever you enter here.
• On Powerup: How do you want the output to behave at powerup. The default is to return to the last level it was at when power was removed, however it may be useful to have some channels startup either always on or always off to avoid having things turn on when you’re sleeping if there is a short power hit overnight.

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:

• Unused: If set to Unused the GPIO will not be shown in any interfaces and no unit will be created for it in XTension.
• Input Pullup: A pullup resistor to the 3.3v is used and you should connect the pin to the board GND to switch the state. Like an alarm system the unit will be ON when the connection is broken and off or safe when connected to GND.
• Input Pulldown: A pulldown resistor to GND is used and you should connect the pin to the 3.3v rail on the board to switch the state. In this case the input will show as off when disconnected and on when connected to 3.3v. Note that connecting this to a voltage higher than 3,3v or any other source may damage the board. Use the 3.3v source outputs on the first group of removable headers. You may also wish to use a current limiting resistor inline to reduce the risk of damage to the device should you short the connection to ground while setting up wires and such. Recommend that you use the pullup under normal circumstances.
• Analog Voltage Input: GPIOs 8 and 9 support analog voltage inputs in the range of 0 to 3.3v. In order to sense the voltage the power supplies of the board and whatever is creating the input must share a ground. The numerical output is not completely linear and so cannot be converted to an exact voltage but some simple math will get you approximately there. See the ESP32 analog input specs for more information. While the input is protected against over voltage it is still possible to damage or destroy the board by attaching higher than 3.3v to this input.
• Button To Gnd: Like the input pullup this is a specific input for a button that connects to GND when pushed. It is different from the Input Pullup in that it includes some debouncing to keep it from firing many times while you’re pressing. The output is an On event when the button is pushed and no event when the button is released except in the case of a Hold action. (BETA: the interface contains interface elements from the PWM device that are not valid for the GPIO only device. The multi-tap and hold actions may not yet be sent to XTension or other sources.)
• Button To V+: Same as Button To Gnd except that the connection should be to the 3.3v rail on the board.
• Touch Button: GPIOs 1, 3, 4, 5, 8 and 9 support touch sensing and translating that to the on/off state of a button in XTension. Since every sensor you might connect this too will have a different untouched capacitance a “Touch Threshold” will need to be set. (BETA: There is not yet a simple way of displaying the current capacitance value so setting the threshold may require some experimentation. You can also set the input to the Touch Capacitance type and watch the value in XTension as you touch the sensor and release it then change it back to Touch Button entering a decent value you discovered in the other test.)
• Touch Capacitance: Instead of a button with a threshold as the Touch Button this creates an analog unit in XTension that will display the current value as sensed. Might be useful for other kinds of detection or proximity or some such.
• Switch To Gnd: A switch connected from the GPIO to GND. Same debouncing as the Button above but will send an off or on depending on the state of the switch.
• Switch to V+: Same as the Switch To Gnd but for when you need to use the 3.3v output as the other side of the switch.
• Counter, Sensor To GND: A counter input when the sensor will make connection to GND for the count. You can set the input to increment the counter on the rising, falling or both edges of the input. The count, if any, will be reported after the reporting interval that is set in seconds in the interface. This is useful for things like flow sensors or electricity sensors that output a pulse.
• Counter, Sensor To V+: Same as the Counter to GND above but expects the sensor to switch to 3.3v instead of GND. (BETA: The web interface for setting the edge detection and interval does not properly display for this selection. If you need to set this up, set it up as a counter to gnd setting the needed values there and save the settings. Then change the settings to Counter to V+ and save again. The previous settings will be preserved.)
• DHT-22 Temp/Humidity Sensor: Any of the first 8 GPIO can have a DHT-22 or similar style temperature/humidity device connected to it. They should be powered from the 3.3v and gnd available on the board and have their data line connected to the GPIO input. A Temperature and Humidiy unit will be created in XTension and will show on the main page interface. If you are using a board mounted sensor no other hardware is required. If you are using a bare DHT device it may be necessary to add a pullup or pulldown resistor to the data line in order for it to work properly. See the DHT data sheets for using this. I do not recommend using the cheaper DHT-11 sensors they have horrible stability and accuracy and are not worth saving a few bucks there. Get the better DHT-22 or AM2302 which are basically the same devices.
• Radio Receiver: a 433mhz or 315mhz receiver device can be connected to any of the first 8 GPIO pins. Note that only a single radio is supported per board so you cannot have both types on the same GPIO board. For better reception, reception indication and transmission capabilities please consider using the radio expansion card. This input type is excellent at receiving many of the 433mhz alarm and remote control devices out there. The transmission capability is more limited. (BETA: transmission is not yet enabled for the expander card) Any device that is received will cause a unit in XTension to be created for it’s ID number and you can attach logic and actions there. If the device is a simple button or event like motion sensing you can use the unit as it is after changing it’s name. If the device has on and off like some remotes or a door/window sensor then you should trigger both and let XTension create the 2 units. Then change the address of the ON unit to be the address of the ON unit, a colon and the address of the off unit. Like “12345:67890” or whatever the address of the 2 units are. Then delete the unit that was created for the OFF event. That single unit will now turn on and off with the reception of the 2 commands. I fund the range of most such devices to be quite excellent but you can add any number of additional GPIO devices with a radio to your network as needed to cover the entire area. If a transmitter is received by more than one of the physical GPIO radios only the single unit will be created and it can increase the reliability of the reception. In other words, it will not create a unit for the GPIO receiver in the living room and another for the receiver in the bedroom. There will be only one unit with those ID numbers and whichever receiver receives it first will trigger the change. Unfortunately there is no information about where the low battery bit is in the devices that support that so when the low battery happens the unit will stop receiving it’s updates as the address will have changed. To work around this XTension radio button units have a low battery address field that you can also fill in with the on and off values when the battery is low. If those are received then the device will continue to function but set the low batt flag. The only way to discover this is to run the device on low batteries or to run it from a bench supply and crank the voltage down until the low batt detector is triggered. Not all devices will even check for low battery so some experimentation here may be necessary. When choosing devices keep in mind that devices that are advertised as “learning” may not work unless you can program them with some other 433 transmitter. They will not transmit a unique ID number necessary until they learn one from another device. Just about any non-learning remote or alarm device on 433mhz work great. Note also that there are so many of these devices and they vary so much from device to device that some may have better range than others and some may not work at all. I recommend ordering a single device to test and not a case of something first in case it turns out not to be supported.
• IR Receiver: An IR receiver device (not just a simple phototransistor) can be connected to any of the first 8 GPIO inputs. Powered from the 3.3v and gnd rail on the device with the data output connected to the GPIO pin. (more info on this as well as an Expander card to support multiple inputs and even outputs is in the works) When you point a remote at it and press a button a unit in XTension will be created with the code of the button as it’s address and will receive an ON event whenever the same code is received again. Not all remotes may be supported but only those with the most common modulation rates and such but is a way to get a remote output from a remote to do some other action in XTension.
• Servo: A servo control output on any of the first 8 GPIO pins. The hertz of the output as well as the max and minimum position outputs are configurable in the interface once selecting this. Most servos are 5v and so must have their own power supply to power them. This will also better serve to isolate the noise generated by the motors. When powering one via an external power supply the gnd side of that power supply must be connected to the gnd output of the GPIO card so that the 2 devices can send data to each other. Otherwise it will not see the control pulses. The ground to the board power supply and the data connection from the GPIO pin to the pwm input on the servo is all that is required. The device in XTension will have a min/max value of what you set in the interface and controlling it will set the location of the servo. (BETA: as of this moment there is no rate control, the servo will change immediately and as fast as it can from the one position to the other. Future builds will have the ability to set a rate and possibly a curve for the change so that it can be more smooth.) This PWM could also be used to control brushless motor speed via a proper ESC using the output from the card as the input to the ESC. (BETA: As of the current beta this is totally untested, I have yet to get to the part on the list where I even connect one to the board, but the software is as complete as it can be without testing)
• Output (LOW at power on): GPIO output with the value set to LOW at startup. See limitations on output current and voltage above. At startup the output will be connected to GND. Additionally there is a “reverse logic” button that will reverse how the interface and XTension show and control the output. It will still startup as LOW however, the interface will just show the output as ON if that is selected.
• Output (HIGH at power on): Same as the above except that the output will be HIGH or connected to 3.3v at startup.
• Output Return To Previous State: Same as the above but the output will return to it’s last controlled state when the device is powered on. Note that when starting from a power off state there may be some uncertainty of the output state until the firmware has loaded. If you need to make sure that an output is on or off when powered down please use an external pull up and pull down resistor in addition to the setting to make sure there are no quick changes when powering on. When rebooting via the web interface while changing values the state is preserved and no flickering should occur.
• Output Analog Voltage: GPIO 5 and 7 support outputting an analog voltage between 0 and 3.3v. Make sure you properly limit the current output from this. The unit in XTension will let you set the level. See the ESP32 DAC documentation for more info on what is possible and how to properly use it.
• Encoder Lines: 2 optical encoders can be connected to the GPIO pins. Each one will require 2 inputs an A and a B with the common attached to the 3.3v rail. (BETA: in the PWM device these can be used to directly control the level of outputs, they serve no function yet in the GPIO board but will eventually be able to create a unit in XTension for them or to directly control a separate PWM dimmer device.) Most encoders also have a push button output which could be connected to another GPIO pin to get that input into XTension.

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:

• Device Name: The name of this specific device which will be used when creating units in XTension and displayed on the web pages. This should be descriptive but not too long as it is limited to 30 characters. Once you enable the XTension connection in the next step any units created will have this name prepended to their function or other names. You can change the name of the device after the initial creation of units in XTension but the name change will not be forced to already existing units. Therefore it makes sense to set the name to something more useful first. Once the units are created you can edit their name to be anything that is more useful or descriptive to you. The name from the device is just the startup default when creating them so that they are more easily identified.
• XTension Connection: It is possible to use the device or just setup the device without connecting to XTension. This way you can delay the creation of units until you have setup the various inputs and outputs or if you don’t have an XTension instance to talk to yet. This does limit the functionality of the device.
• XTension Device ID: Each GPIO or other board has a unique ID that is created from the MAC address of the WiFi. This is used when creating units associated with this board in XTension. It is editable so that if you need to replace one board with another you can just set it’s ID to be the same as the old board and therefore all the units in XTension will pick up the new board as if nothing had changed. If you are not replacing a board you probably do not want to change this. It must be 6 characters in length but could be changed to something descriptive if you wish to be able to see the unit addresses and know immediately which device they are attached to without looking at their names.
• mDNS/Bonjour Name: The .local address the device will create on the network. This should be changed to something useful and much be changed if you have more than one device on the network as they must be unique.
• AP Name in Setup Mode: The name of the WiFi access point that will be created when in setup mode. Generally you won’t need to change this, but if for some reason you want to have multiple devices in setup mode at the same time then this will allow you to tell them apart when connecting to it.
• Check For Updates: Once a week the device will request a small json file from the server checking to see if a firmware update is available for it. If so it will write a note to the XTension log that you should log in and update it. No device info other than the device type and board revision are sent to the server, no data is colected on the server apart from the standard apache logs that would show the IP address the request originated from. If you do not wish to have the device make this check, or if you are setup where there is no internet connection you may wish to turn this off.

• Web Server Port: The port the web server should run on. Defaults to 80 and really no reason to change it unless you are dealing with routers or wifi devices with very strange limitations.
• Web Server Security: uses basic authentication for controlling and configuring the device. You should never expose the built in web server to the internet as a whole and even if you turn this on it will not make things that much more secure. Generally you would not need this on a local network unless you suspect guests might find it and mess with it and yet are incapable of capturing the plain text sending of the password when you log in.

• WiFi Settings: Here you can enter up to 3 WiFi SSID’s and passwords for networks that the device should connect to. It will do a scan for available networks upon startup and anytime the wifi connection is dropped and will connect to the network that has the best signal strength of any that are found.

• Network Settings: In general I would recommend setting up a static IP address for any such devices, but it is not strictly necessary with the XTension connection being stateless and the availability of the Bonjour name on the network. If you do wish to set it up as such the settings are in this section.

• Device Status Units: by default the device will send it’s signal strength and CPU temperature to units in XTension. These can be helpful or just interesting to see how well the device is working but if they create too much noise or you simply don’t care to see those values you can turn them off here and then delete the units from XTension.

• Status LED: See below for status LED patters that can tell you what the device is doing. These settings further control how the Status LED is handled.
  • In Proper Connected and Operating State… When connected and working properly you can set the LED to be dimly lit indicating visually that everything is OK and power is on, or if having the LED visible is not desirable you can have it turn off in this state.
  • Led Dim/Bright Level: The LED dim and bright levels can be configured so that they are visible or not too bright. If you set the bright and dim too similarly to each other however you won’t be able to see when the LED is flashing information at you.
  • Echo Status LED: (Beta: this is unimplemented for the GPIO but will eventually echo the status LED pwm on the first GPIO pin so that an LED external to the enclosure could be setup to show the state. This is implemented for the PWM dinner devices and will use PWM channel 1 as the LED output for this purpose)
  • Turn On Find Me Mode: this causes the LED to flash between the bright and dim levels very quickly so that the physical device you are talking to can be identified when you might have several together. It does not require a save and restart. The find me mode can be turned on and off in real time.

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.