= 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. __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. __Installation (UI5)__ 1. Download and unzip the attached zip file. 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. Once the upload and Luup restart are completed, use the ''Apps / Develop Apps / Create Device'' page to create a new device for the gateway. a. Enter '''D_TCPLightingGateway1.xml''' in the ''Upnp Device Filename'' field. b. To try out the experimental gateway auto-discovery feature, leave the ''IP'' field blank. See the notes on Auto-Discovery below. c. If you know it, you can also enter the IP of your gateway in the ''IP'' field. 5. Wait for the Luup restart to complete. 6. Refresh the Vera UI for good measure. 7. When the gateway device is initialized, it will 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. Note that the device UI for the bulbs is often partially rendered when first created. A browser refresh normally fixes this. __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. __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 case. * 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 your 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. [Partial/In Progress] * Additional gateway and light variables settings. [Done] * Testing with multiple gateways. * Energy metering (maybe). __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://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.).