= TCPLighting = This plugin integrates a [http://www.tcpi.com/connected-by-tcp Connected By TCP] LED lighting gateway with a Vera controller. Once a device for the gateway is created, the plugin in turn creates child devices (of type ''Dimming'' or ''SwitchPower'', as appropriate) for each connected bulb. Since the bulbs are created as standard devices, they are available for control via scenes, mobile apps, etc. '''Important:''' In the 3.0.74 TCP gateway firmware update, TCPi disabled the API that version 1.x of this plugin used. This is an automatically pushed update, that not everyone received at the same time. Version 2.0 of this plugin, which uses a secure local API seems to correct this problem. However, the 2.0 plugin will not work with prior gateway firmware versions. If for whatever reason, your gateway is running a earlier firmware version, you can try manually installing the v1.x plugin, which is attached below. __Pre-Installation__ Set up your ''Connected By TCP'' LED gateway and bulbs as per the instructions provided with the devices. Ensure that everything is working (i.e. lights can be controlled using the smartphone apps or gateway web interface) prior to installing the plugin. The Vera and TCP gateway Ethernet cables should be plugged into the same router/access point/hub, so as to ensure that the Vera can reach the TCP hub from a TCP/IP connectivity perspective. __Installation (Marketplace/UI5)__ '''Note:''' Only use this version if your Connected By TCP gateway is running firmware version 3.0.74 or later. 1. Install the [http://apps.mios.com/plugin.php?id=6176 TCPLighting app] from the MiOS App Marketplace (i.e. the ''Apps / Install Apps'' page). 2. Wait for the Luup restart to complete. 3. Go into the TCPLighting device configuration UI (wrench icon). You should see a "Pair" button - but don't click it yet ;-) 4. If you are lucky, the auto-discovery feature will have detected the ''Connected By TCP'' gateway and configured its IP address. 5. If the auto-discovery failed, you will see the message ''No gateway IP address specified, autodiscovery failed'' in the gateway device UI. Some of the reasons why this might happen, and how to manually configure the gateway IP address, are outlined in the Auto-Discovery section below. 6. Press the green sync button on your Connected by TCP gateway. 7. Click the "Pair" button on the TCP Lighting config UI. Wait a few seconds. If the pairing is successful, the plugin will then poll the gateway and create child devices for each bulb. If a bulb's room name matches that of a Vera room, it will be automatically added to the room. __Auto-Discovery__ The ''Connected By TCP'' LED gateway supports a subset of the [http://en.wikipedia.org/wiki/Simple_Service_Discovery_Protocol Simple Service Discovery Protocol (SSDP)] which is part of the [http://en.wikipedia.org/wiki/Universal_Plug_and_Play Universal Plug and Play (UPnP)] architecture. In theory, this should allow this plugin to automatically determine the IP address of the gateway without user intervention. However, there are several reasons why this may not work in practice: 1. SSDP uses IP multicasts to search for devices providing UPnP services. Depending on how your Vera and local network are configured, the multicast requests may not reach the gateway. For example, your router may not be configured to forward multicasts from the wired to the wireless segments of your network. This is also discussed in the documentation for [http://forum.micasaverde.com/index.php?action=profile;u=5055 futzle]'s [http://code.mios.com/trac/mios_belkin-wemo Wemo Plugin]. 2. VeraLite controllers have a slightly odd network interface configuration which results in situations where the multicast responses may not come back on the expected interface. This is described [http://forum.micasaverde.com/index.php/topic,13890.msg104717.html#msg104717 here]. A workaround is described [http://forum.micasaverde.com/index.php/topic,16905.msg132502.html#msg132502 here], but this pretty well defeats the benefits of auto-discovery, given the steps involved. If auto-discovery doesn't work for you, then you can manually specify an IP address by updating the advanced properties of main TCP Lighting gateway device (click the wrench icon, go to the ''Advanced tab'', and enter the gateway's IP address in the ''IP'' field). You may need to check the DHCP client table of your home router to find the IP address of the gateway. Another way of getting the IP address is to open a command window on a PC that is on the same network as the lighting gateway, enter the command '''ping lighting''' and note the IP address that the lighting host name resolves to. If you still can't connect, try enabling remote access via the Connected By TCP / Greenwave mobile app. One user has reported that this seemed to make things work. __v2.0.1 Release Notes:__ * Fixed error in logging code. __v2.0 Release Notes:__ * In the 3.0.74 TCP gateway firmware update, TCPi disabled the API that version 1.x of this plugin used. This is an automatically pushed update, that not everyone received at the same time. Version 2.0 of this plugin, which uses a secure local API seems to correct this problem. However, the 2.0 plugin will not work with prior gateway firmware versions. If for whatever reason, your gateway is running a earlier firmware version, you can try manually installing the v1.x plugin. * This is an unsupported hobbyist project. I am in no way connected with [http://www.tcpi.com/ TCPi] (the makers of the Connected By TCP gateway and bulbs) or [http://getvera.com/ Vera Control, Ltd]. Please do not ask them for support with this plugin. * Code is based on an undocumented API. __v1.0.2 Release Notes:__ * Supports the XML output format of the v2.x firmware that is pre-loaded on many Connected By TCP gateways that have never been auto-updated to any more recent firmware, such as 3.0.39 (supported by v1.x of this plugin) and the 3.0.74 update that removed the local HTTP interface (supported by v2.x of this plugin). __v1.0.1 Release Notes:__ * Fixes JSON file issue for UI7. __v1.0 Release Notes:__ * First version available in the MiOS app Marketplace. * Functionally the same as v0.4, except that it will now auto-update by virtue of being in the app marketplace. __v0.4 Release Notes:__ * New approach to flagging offline bulbs. Instead of being rendered invisible, the name off offline bulbs are now prefixed with "[Offline]". The offline labeling can be modified through the ''OfflineDeviceNameFormat'' state variable. The format string is as per that used by the Lua [http://www.lua.org/pil/20.html string.format] function, where the %s placeholder is replaced with the device name. For example, if the bulb named "Front Entry Light" goes offline, the default format string of ''[Offline] %s'' will cause the device name to be displayed as "[Offline] Front Entry Light" if the status of the bulb cannot be retrieved. Changing the value of the ''OfflineDeviceNameFormat'' state variable to ''%s is unavailable'' would result in a display name of "Front Entry Light is unavailable". A prefix was chosen as the default format string, simply because the Vera UI truncates longer names, thus a suffix would not be displayed in some cases. * The auto-discovery feature has been made more robust through retry logic. When polling the gateway with a previously auto-discovered gateway IP fails, the IP address is cleared, which will trigger a new auto-discovery attempt at the next polling interval. See the notes on Auto-Discovery if you are having trouble getting this feature to work. __v0.3 Release Notes:__ * Better handling of unknown room names, i.e room names from the Connected By TCP Gateway that do not match Vera room names. The plugin will now only update the room name if a match is found. Previous versions erroneously set the room number to zero in such a case. __v0.2 Release Notes:__ * Includes more robust handling of devices and gateways going offline and coming back online. Device numbers should now be retained so that scenes, etc. are not broken. Polling continues after a failed HTTP request to the gateway. * Experimental and partial implementation of gateway SSDP auto-discovery. * Gateway device will now get a default name assigned. * Bulbs will have manufacturer and model attributes set. * Logging is a little less verbose. __v0.1 Release Notes:__ * This is my first attempt at a Vera plugin, so please do not hesitate to provide constructive criticism. * This is an unsupported hobbyist project. I am in no way connected with [http://www.tcpi.com/ TCPi] (the makers of the Connected By TCP gateway and bulbs) or [http://getvera.com/ Vera Control, Ltd]. Please do not ask them for support with this plugin. * Code is based on an undocumented HTTP API. * Only tested on a Veralite with UI5. * Only tested with A19 dimmable bulbs. * Default polling interval is 60 seconds. Therefore, any changes made outside of the Vera environment (using a remote or the ''Connected By TCP / Greenwave Reality'' apps) may take up to 60 seconds to be reflected in the Vera UI. Ditto for new bulbs. __To-Do:__ * Store code in [http://code.mios.com/trac/mios_tcplighting/browser code.mios.com] SVN repository. [Done] * Gateway auto-discovery via SSDP. [Done] * Additional gateway and light variables settings. [Done] * Testing with multiple gateways. * Energy metering (maybe). __Manual Installation of Version 2.0.1 (UI5)__ '''Note:''' Only use this version if your Connected By TCP gateway is running firmware version 3.0.74 or later. 1. Download the [http://code.mios.com/trac/mios_tcplighting/raw-attachment/wiki/WikiStart/TCPLighting%20Plugin%20v2.0.1.zip TCPLighting Plugin 2.0.1] zip file attached below. 2. Upload all of the plugin XML, JSON and LUA files using the ''Apps / Develop Apps / Luup files'' page. Make sure to click the "Restart Luup after upload" checkbox 3. Wait for the Luup restart to complete. 4. If you don't have a TCPGateway device set up from a previous installation, use the Apps / Develop Apps / Create Device page to create a new device for the gateway. Simply enter D_TCPLightingGateway1.xml in the Upnp Device Filename field and click the "Create Device" button. Wait for the Luup restart to complete and refresh the Vera UI for good measure. 5. Go into the TCPLighting device configuration UI (wrench icon). You should see a "Pair" button - but don't click it yet ;-) 6. If you are lucky, the auto-discovery feature will have detected the ''Connected By TCP'' gateway and configured its IP address. 7. If the auto-discovery failed, you will see the message ''No gateway IP address specified, autodiscovery failed'' in the gateway device UI. Some of the reasons why this might happen, and how to manually configure the gateway IP address, are outlined in the Auto-Discovery section below. 8. Press the green sync button on your Connected by TCP gateway. 9. Click the "Pair" button on the TCP Lighting config UI. Wait a few seconds. If the pairing is successful, the plugin will then poll the gateway and create child devices for each bulb. If a bulb's room name matches that of a Vera room, it will be automatically added to the room. __Manual Installation of Version 1.0.2 (UI5)__ '''Note:''' Only use this version if your Connected By TCP gateway is running a firmware version ''prior to'' 3.0.74. 1. Download the [http://code.mios.com/trac/mios_tcplighting/raw-attachment/wiki/WikiStart/TCPLighting%20Plugin%20v1.0.2.zip TCPLighting Plugin 1.0.2] zip file attached below. 2. Upload all of the plugin XML, JSON and LUA files using the ''Apps / Develop Apps / Luup files'' page. Make sure to click the "Restart Luup after upload" checkbox 3. Wait for the Luup restart to complete. 4. If you don't have a TCPGateway device set up from a previous installation, use the Apps / Develop Apps / Create Device page to create a new device for the gateway. Simply enter D_TCPLightingGateway1.xml in the Upnp Device Filename field and click the "Create Device" button. Wait for the Luup restart to complete and refresh the Vera UI for good measure. 5. If you are lucky, the auto-discovery feature will have detected the ''Connected By TCP'' gateway and configured its IP address. 6. If the auto-discovery failed, you will see the message ''No gateway IP address specified, autodiscovery failed'' in the gateway device UI. Some of the reasons why this might happen, and how to manually configure the gateway IP address, are outlined in the Auto-Discovery section below. __Acknowledgements__ Many thanks to: * [http://forum.micasaverde.com/index.php?action=profile;u=93494 ctguess] for [http://forum.micasaverde.com/index.php/topic,22555.0.html the forum posting that describes how to control these bulbs]. * [http://home.stockmopar.com/author/stockmopar/ stockmopar] for figuring out [http://home.stockmopar.com/updated-connected-by-tcp-api/ how to access the secure local API for gateway firmware version 3.0.74], which led to v2.0 of this plugin. * [http://forum.micasaverde.com/index.php?action=profile;u=5055 futzle] for the clear and concise description of the [http://code.mios.com/trac/mios_belkin-wemo multicast forwarding issue]. * [http://forum.micasaverde.com/index.php?action=profile;u=36261 migi] and [http://forum.micasaverde.com/index.php?action=profile;u=5055 futzle] for their comments on the [http://forum.micasaverde.com/index.php/topic,13890.msg104717.html#msg104717 multiple IPs assigned to the VeraLite Ethernet port]. * [http://forum.micasaverde.com/index.php?action=profile;u=105841 macfly92] for figuring out [http://forum.micasaverde.com/index.php/topic,16905.msg132502.html#msg132502 how modify the firewall rules for a VeraLite] to fix the multicast problem. * [http://forum.micasaverde.com/index.php?action=profile;u=14758 RichardTSchaefer] for clarifying the behavior of ''luup.set_failure'' (and helping me avoid going down a dead-end.). * [http://forum.micasaverde.com/index.php?action=profile;u=143613 ecsherwo] for the insight regarding enabling remote access. * [http://forum.micasaverde.com/index.php?action=profile;u=144650 jpope42] for helping identify the importance of having the Vera and TCP gateway plugged into the same device. * [http://forum.micasaverde.com/index.php?action=profile;u=147161 JoeyD] for providing a fix to the JSON issue that prevented the plugin from working with UI7 (corrected in v2.0 and v1.0.1). * [http://forum.micasaverde.com/index.php?action=profile;u=143327 justroach] for providing log entries that helped find an error with some logging code (corrected in v2.0.1). * [http://forum.micasaverde.com/index.php?action=profile;u=147498 rEVOLVE] for helping to sort out XML issues with Connected By TCP gateways using their pre-loaded 2.x firmware.(corrected in v1.0.2).