Luup Control

Latest revision as of 05:05, 13 April 2010

If you didn't already come from the Luup_Intro page, start there to see what Luup Control is intended for.

You can talk to the Luup engine using either standard UPnP actions or with basic HTTP. Either way this can be done on the local network or through the secure FindVera gateway. The gateway allows you to discover and control UPnP devices over the internet using a secure, encrypted connection.

Vera also acts as a UPnP relay. So, for example, if you want to control a UPnP device which is unrelated to Vera, but you don't want to create the XML/SOAP requests and implement the full UPnP protocol, you can simply pull a URL on Vera to have Vera convert the request into standard UPnP and relay it for you. This makes it easy to write lightweight scripts and simple javascript web applets that send UPnP actions. See: lu_action below

UPnP Control Points that can control Vera's home automation devices are Priority projects, and Mi Casa Verde is providing free hardware to makers of these as explained in our Luup launch announcement.

To control Vera you must: 1) Find Vera on the network, 2) Send UPnP actions, and probably 3) Check the current state of all the devices in order to present this in the user interface.

[edit] Finding Vera on the network

You can find Vera using the normal UPnP discovery process.

Or, you can open http://findvera.com/localips.php to get a list of any Vera's that are currently on within the same home network. This way if you want to write a simple shell script that sends a UPnP action you don't need to implement UPnP. Just save the contents of that URL in a variable.

Or, you can prompt the user for his findvera.com username/password and call this URL: https://findvera.com/localips.php?username=whatever&password=whatever.

Or, you can visit findvera.com from a web browser to see a list of Vera's in your home and the IP addresses.

NOTE: Once you know Vera's IP, Vera will always listen on port 49451. The UPnP standard provides that the port can jump around and you discover it using the normal SSDP. However since Vera allows discovery with several simpler methods, the port number is permanently fixed to make it easy.

[edit] Getting the list of UPnP devices you can control

You can do this the usual UPnP way. Note that Vera presents all the devices as a compound device with Vera as the topmost device and all the other devices as children.

Alternatively you can request Vera's configuration file using the GetUserData action or the user_data web request. This is good when you haven't implemented UPnP, but even if you have, it may contain useful information beyond what is in the UPnP device description file.

[edit] Sending UPnP actions

You can use the normal UPnP mechanism.

Or, from outside the home you can send the UPnP request to https://findvera.com by passing the username and password for the findvera service on the URL.

Or, you can use the lu_action web address, either from within the home, or from outside, to be able to send actions without having to use the standard UPnP SOAP/XML. You can also check the state of variables with lu_variable.

See the following section about jobs to understand how Vera handles UPnP actions.

[edit] Luup jobs

As explained here Luup_Plugins_ByHand#run.2Fjob.2Fincoming.2Ftimeout often times UPnP actions are handled asynchronously in jobs. The UPnP architecture does not provide a mechanism for tracking the status of asynchronous jobs. For example, a UPnP Light Switch is turned on/off with the action "SetTarget". But you have no way of knowing if the action was successful or not (maybe the light switch is broken) to tell the user if the action was OK or if it failed.

Luup solves this by adding an extra return argument "JobID" to any UPnP action that results in asynchronous execution. You can then track the status of the job using the lu_status web request or the GetStatus UPnP action. This way if the user turns on a light in your control point you can display a 'busy' icon while the command is being run that turns into an 'OK' or 'FAIL' icon when the job is done, and you can tell the user why it failed.

[edit] Check the current state

You can subscribe to UPnP services to monitor the state of variables as normal in UPnP. Or you can use the GetStatus action or the lu_status web request to get the current state of all active jobs and all UPnP variables.