http://wiki.mios.com/api.php?action=feedcontributions&feedformat=atom&user=AndreimiosMiOS - User contributions [en]2026-06-03T02:51:21ZUser contributionsMediaWiki 1.19.8http://wiki.mios.com/index.php/UI_NotesUI Notes2015-07-03T12:27:33Z<p>Andreimios: /* lu_status */</p>
<hr />
<div>[[Category:Development]]<br />
Here is some general information about getting information to display in a user interface:<br />
<br />
== UPnP messaging system ==<br />
<br />
Vera uses UPnP for all the messaging, such as turning lights on and off. So Vera translates Z-Wave, Insteon, infrared codes, etc., into UPnP actions. If you have already implemented a UPnP stack and can send properly formated UPnP SOAP/XML requests, you can control everything using standard UPnP action invocation. If you did not, Vera provides a simple HTTP GET interface as well, which is discussed below.<br />
<br />
In a nutshell UPnP works like this: You have UPnP devices, which are things that can be controlled and can report their state, like a light switch. And you have UPnP Control Points, which are the things that let a user control UPnP devices, like a touch-screen web pad. The Control Point does this by a) reading the device and descriptions for the UPnP device to see what it can do, and b) invoking actions on the UPnP device (ie telling it to do something), and c) reading and setting variables for the device which describe the current state and/or configuration settings for the device.<br />
<br />
A UPnP device is defined in an XML document called a device description document. To see one, in Vera's setup UI, go to Devices, Luup plugins, Luup Files, and click 'view' file next to D_BinaryLight1.xml. Use Firefox since it has a built-in XML viewer. Notice the tag: <deviceType>urn:schemas-upnp-org:device:BinaryLight:1</deviceType>. This defines the type of device, namely an on/off light switch, which is what you use to know how to represent this device to a user. A device optionally implements one or more services. In this case the services: urn:upnp-org:serviceId:SwitchPower1, urn:micasaverde-com:serviceId:EnergyMetering1 and urn:micasaverde-com:serviceId:HaDevice1.<br />
<br />
A service is a collection of actions which a device implement and which you can invoke from a UPnP Control Point, as well as a collection of variables which always have a current value. The variables describe the current state of the device and/or configuration settings. View the file S_SwitchPower1.xml to see a service. For example, the device urn:schemas-upnp-org:device:BinaryLight:1 implements the service urn:upnp-org:serviceId:SwitchPower1, which has the action SetTarget, which is how you turn the light on and off. The action takes a single argument newTargetValue which can be 0 to turn the light off and 1 to turn it on. The service also has the variable Status which is 0 or 1 depending on whether the light is currently on or off.<br />
<br />
If you open the device description for a dimmable light D_DimmableLight1.xml you'll see that it implements the same service S_SwitchPower1.xml, since you can still turn it on and off, and it also implements the service urn:upnp-org:serviceId:Dimming1, which has an action to set the dim level (SetLoadLevelTarget).<br />
<br />
To test UPnP calls you can use the Intel Device Spy utility available [http://www.intel.com/cd/ids/developer/asmo-na/eng/downloads/upnp/tools/218896.htm?desturl=http://softwarecommunity.intel.com/isn/downloads/zips/IntelToolsForUPnPTechnology_v2.zip here]. It should pick up Vera, show you all the devices, like light switches, thermostats, etc., let you expand the services and see the actions and variables. Click an action, like SetTarget, to specify the arguments and click 'Invoke' to run the action, such as turning on and off the light.<br />
<br />
== JSON vs. XML ==<br />
<br />
The native UPnP protocol uses XML/SOAP. But there are also several times you will request data from Vera that has nothing to do with the UPnP spec. These will be done with data_request's as explained below, such as user_data, lu_status, etc. Internally Vera uses JSON as the native format, but Vera can convert to XML (details follow). In general when you want to view data in a human readable format, such as the device list, it's easiest to use the Firefox browser, and request Vera convert the data to XML. Firefox has a nice browser to display XML in human readable format. If you want to make the JSON data nicely formatted, you can use the web site jsonlint.com. In a UI application which will request data regularly from Vera we recommend retrieving everything in JSON format, not XML, because Vera's CPU is not that powerful and so continuous requests of data in XML format will cause a lot of CPU time to be devoted to converting JSON into XML.<br />
<br />
== Finding Vera on the local network ==<br />
<br />
You can find Vera by using the traditional UPnP discovery process, or you can retrieve this URL:<br>'''https://sta1.mios.com/locator_json.php?username=xxx''' where the username=xxx is optional, but, if specified, it will report all systems that mios.com user xxx can report whether local or remote, and without the username=xxx it only shows the Vera's on the user's local home network.<br />
<br />
Each Vera, when it boots up, reports its internal IP address to the central mios.com server, which tracks this along with the external IP address. '''locator.php''' shows all serial numbers and internal network IP addresses on the same external IP. For example, if '''https://sta1.mios.com/locator_json.php?username=xxx'''.<br />
<br />
== The HTTP interface ==<br />
<br />
Vera listens on port 3480. Vera responds to UPnP actions the normal way, or by making simple HTTP requests. For example, to turn on a light you can either send the UPnP action "SetTarget" to the device using the normal UPnP mechanism, or you can simply put this URL in your web browser, or with wget, or similar: <br />
<br />
http://[ipadress]:3480/data_request?id=lu_action&amp;output_format=xml&amp;DeviceNum=10&amp;serviceId=urn:upnp-org:serviceId:SwitchPower1&amp;action=SetTarget&amp;newTargetValue=1 <br />
<br />
That URL will return the same results of the action as using the normal UPnP architecture. The '''output_format=xml''' on the URL means the data returned should be in XML format. You can instead use '''output_format=json'''<br />
<br />
The service ID's, actions, and arguments are all defined by the UPnP forum. A list of ratified UPnP devices and services is available on the [http://www.upnp.org UPnP Forum]. Mi Casa Verde added its own custom devices and services when there was no existing UPnP standard. A list of these can be found in the [[Luup_UPNP_Files]] header files.<br />
<br />
== Getting the system configuration ==<br />
<br />
Either use the UPnP service/action:<br> '''urn:micasaverde-com:serviceId:HomeAutomationGateway1/GetUserData''' <br />
<br />
or use the built-in request: <br />
<br />
'''http://ipaddress:3480/data_request?id=user_data2&amp;output_format=json''' (or xml) <br />
<br />
This returns the system configuration file for Vera. It's assumed you understand the way Vera categorizes devices with Rooms, Devices, Scenes, etc. When creating a user interface for controlling Vera only, like on a mobile phone, most of the tags can be ignored, since usually you just need the list of rooms and devices.<br />
<br />
== Accessing Vera remotely through the mios server ==<br />
<br />
Native UPnP only works on a local area home network, and cannot be used over the Internet. The mios server provides a secure way to remotely access and control your Vera system using the HTTP interface without having to make any substantial changes to the UI. Everything you can do locally with Vera on port 3480, you can do remotely with mios using the exact same syntax. You only need to ask the user for his username and password and pass them on the URL to the remote access server, along with the serial number of the unit (ie like 12345). For example, the above user_data is the syntax for local access on a home network. To retrieve the same URL over the internet with mios use:<br />
<br />
https://fwd2.mios.com/demovera/myvera123/12345/data_request?id=lu_status&output_format=json (or use fwd1.mios.com)<br />
<br />
assuming demovera is the username and myvera123 is the password that the user chose setting up his mios.com account. Note that since the request is https, the username and password are encrypted because https encrypts the URL's as well as the contents of the page.<br />
<br />
== Building a control-only UI for Vera ==<br />
<br />
If you just want to control Vera, and not modify the configuration, such as with a cell phone interface or web pad, the flow might possibly work like this: <br />
<br />
'''1)''' For the initial setup, you need to ask whether the user wants to (a)&nbsp;access Vera remotely with the mios service, and if so, get the user's username/password; or (b) access Vera directly on the home network. You can use locator.php to show the Vera on the home network. You might want to do an auto-detect. For example, you could use locator.php to see if Vera exists locally, and if not, prompt the user for a mios username and password. You can use locator.php and pass the username to get the serial number and internal IP, and then automatically switch to direct access if locator.php (without the username) indicates that serial number is found on the local network. This would allow the user to automatically switch between local access with Wi-Fi (which is much faster of course) and remote access with mios and the mobile phone network. Or just ask for his mios username and show him all the Vera's he can control, either local or remote.<br />
<br />
'''2)''' Once the connection is established, retrieve the list of rooms, scenes, and devices from Vera (see '''user_data''' below). You can cache this data locally so you don't need to retrieve it and parse it over and over.<br />
<br />
'''3)''' Present the user with the rooms, scenes, devices. In Vera's UI's we show first the rooms and then let the user pick a device or scene in the room. However this data could be presented graphically, such as on a floorplan. Your UI can have Vera store extra tags and data in the configuration database (ie user_data) to store things like coordinates for icons, outlines or rooms and so on.<br />
<br />
'''4)''' If the user picks a scene you can run the scene with the following URL, passing the scene number as '''x''', and it will return an OK if it went okay: <br />
<br />
http://127.0.0.1:3480/data_request?id=lu_action&amp;serviceId=urn:micasaverde-com:serviceId:HomeAutomationGateway1&amp;action=RunScene&amp;SceneNum=x <br />
<br />
'''5)''' If the user picks a device, you use the category which is contained in the user_data to determine what type of controls to present the user. (See [[Luup UPNP Files]] for a list of the categories.) When the user chooses an action, you can send it like this: <br />
<br />
http://ipadress:3480/data_request?id=lu_action&amp;output_format=xml&amp;DeviceNum=10&amp;serviceId=urn:upnp-org:serviceId:SwitchPower1&amp;action=SetTarget&amp;newTargetValue=1 <br />
<br />
For a list of common actions and device types see: [[Luup CP Mandatory Types]] <br />
<br />
Some actions return immediately with an 'OK'. Other jobs may take time to complete and are processed asynchronously. For these asynchronous jobs you will get a job ID back. There are several ways to present this to the user. One possibility is to do what Vera does in the UI, namely to use '''lu_status '''(explained next) to find all active jobs and to put a 'job' icon next to each device to indicate the progress of the job. In this way the user isn't tracking a particular job ''per se'', but just has visual feedback that a device is busy, and if the job icon(s) turn green, that everything went through okay. You could instead track the action individually using the job number that is returned, or use some other method, like making the icon for the device appear animated while it's busy, and turn green or red if the last command succeeded or failed.<br />
<br />
'''6)''' Periodically poll the system with '''lu_status''' (explained below), like this: <br />
<br />
http://ipaddress:3480/data_request?id=lu_status&amp;output_format=json <br />
<br />
That returns the current values of the UPnP variables, which you can use to show the user current status. For example, if the variable Status is 1 for a switch, you can show the 'on' button in a selected state, while 0 shows it in an 'off' state. '''lu_status''' also shows any active jobs for a device.<br />
<br />
==user_data==<br />
<br />
The user_data is the main configuration file that Vera uses to store all the rooms, devices, scenes, timers, events, users, and any other data about the system. You should request the user_data to get whatever data you need to present to the user, at a minimum, for example, you'll need the list of devices, their descriptions, and the categories (light switch, thermostat, etc.). You'll also want the list of scenes to present the user. To fetch the current user_data from Vera use the user_data request, like this:<br />
<br />
Returns JSON (preferred native format):<br />
<br />
http://[ip address]:3480/data_request?id=user_data<br />
<br />
Returns XML:<br />
<br />
http://[ip address]:3480/data_request?id=user_data&output_format=xml<br />
<br />
You can also add a 'DataVersion=TimeStamp' parameter to the URL. It the data has changed since the TimeStamp, all the data is returned. If the data has not changed since the TimeStamp, Vera will return a page with the text 'NO_CHANGES':<br />
<br />
http://[ip address]:3480/data_request?id=user_data&DataVersion=315587159<br />
<br />
The user_data contains the state for all the devices. For example this indicates that the device id #17, called "Switch" is turned off (ie service SwitchPower1, variable Status is 0)<br />
<br />
{<br />
"devices": [<br />
{<br />
"id": 17,<br />
"category": 3,<br />
"room": 1,<br />
"name": "Switch",<br />
"ip": "",<br />
"mac": "",<br />
{<br />
"service": "urn:upnp-org:serviceId:SwitchPower1",<br />
"variable": "Status",<br />
"value": "0" <br />
}<br />
}<br />
]<br />
}<br />
<br />
{{Warning|On UI7 build lu_sdata and lu_status have been deprecated, and you should use "status" instead.}}<br />
<br />
==lu_status==<br />
The UPnP variables describe the state of the devices according to the UPnP specs. When the variables change that information needs to be shown to the user, eg change a Switch icon from off to on. If you are interfacing with Vera using the UPnP stack, you can subscribe to the device's events to receive notifications automatically when a device's state changes. However if you're using the web interface you will need to poll using status request.<br />
<br />
Call lu_status request like so:<br />
<br />
:http://[ip address]:3480/data_request?id=status<br />
<br />
:http://[ip address]:3480/data_request?id=status&output_format=xml<br />
<br />
:http://[ip address]:3480/data_request?id=status&DataVersion=315587159<br />
<br />
<br />
The returned document contains four sets of information, which constantly change to reflect the current status:<br />
* root attributes including DataVersion, which is the status timestamp, plus other attributes such as LoadTime <br />
*the state of the system initialization, such as initialization of the plugin modules.<br />
*a '''subset''' of the user_data that represents the current state of the device's UPnP variables<br />
*the status of any active or recent '''jobs''', such as if a light was successfully turned off<br />
<br />
===Tracking status changes===<br />
If you call lu_status without passing a DataVersion on the URL, you will get the current value of all the UPnP variables for a device. Note that most of the UPnP variables do not ever change. For example, with a light switch, only the variable "SwitchPower:Status" changes, as the switch is turned off and on. There are many other variables, like "Capabilities" which are simply configuration data or settings the user modified. If you pass &DataVersion=1 on the URL, you will only see the UPnP variables which have changed since the Luup engine started. So, if you parse the initial UPnP variables when you first call user_data, you can call lu_status with DataVersion=1. Once you call lu_status the first time, store the DataVersion and on subsequent calls pass it on the URL and you will only get the UPnP variables which have changed since that last DataVersion. Regardless, you will also get the current state of jobs and system initialization.<br />
<br />
On subsequent calls to lu_status, you should also pass back in the LoadTime which you received on the prior call.<br />
<br />
===Controlling the poll timing===<br />
You can also pass in a Timeout value, which means the call will block for up to that many seconds if nothing has changed, and will return immediately when something does. This way you can have infrequent polling, say every 60 seconds by putting a Timeout value of 60, but your UI will be immediately responsive since, when something changes, it returns immediately. You can also add a MinimumDelay, which means that the call will wait for at least that many milliseconds. This is advisable so that in the event there are lots of continuous changes, such as a scene turning off many lights, you won't have lu_status calls returning non-stop consuming all the resources on both the Vera and the UI.<br />
<br />
===Startup status===<br />
The section with the initialization tasks is shown in the startup tag as shown:<br />
<br />
"startup": {<br />
"tasks": [<br />
{<br />
"id": 0,<br />
"status": 2,<br />
"type": "ZWave",<br />
"comments": "No Z-Wave" <br />
},<br />
<br />
The startup tasks begin whenever the Luup engine is reset, such as after the user makes a configuration change. Ever plugin and module in the Luup engine does a startup sequence. The id is not really important. The status numbers are the same as for jobs, so 2 means the module failed to startup. The 'Type' is what you can use to key off of to know which module is being reported, such as "ZWave", and comments are just notes indicating the current state. For example, "No Z-Wave" means there's no Z-Wave dongle connected.<br />
<br />
Once all the plugins have been initialized successfully the startup section will disappear completely from lu_status.<br />
<br />
Note that lu_status also returns UserData_DataVersion, which is the dataversion from user_data. That way you don't need to poll user_data in parallel. Simply retrieve the user_data one time at startup, then poll lu_status, and, if UserData_DataVersion is different from the previous user_data you retrieved, then download user_data again.<br />
<br />
Some notes on building a full replacement, including configuration, are available here [[UI_Notes_Replacement]], however the syntax is not up to date with the Luup architecture.<br />
<br />
===Job status===<br />
The jobs for a device will look like this:<br />
<br />
"devices": [<br />
{<br />
"id": 1,<br />
"Jobs": [<br />
{<br />
"id": "1",<br />
"name": "job#1 :getnodes (0x00D068F0) P:10 S:4",<br />
"icon": "",<br />
"comments": "",<br />
"status": "4" <br />
} <br />
] <br />
},<br />
<br />
The id is the job id number. When you run an action, like turning on a light, if it happens asynchronously, you'll get a job id number. All pending jobs for a device are shown by their id number. The name is just an internal name for the job. Icon is an optional keyword to indicate what sort of icon should be shown to the user. For example, 'getnodes' has no icon, meaning this type of job is generally not of interest to a user. If the icon was 'ON' or 'OFF' that would mean this job is busy turning on or off a light. Comments is notes about the job, if any. This may be shown to a user in a tool tip or similar, but is generally more technical than users would care to know. The status indicates the current state of the job, as shown:<br />
<br />
*job_None=-1, // no icon<br />
*job_WaitingToStart=0, // gray icon<br />
*job_InProgress=1, // blue icon<br />
*job_Error=2, // red icon<br />
*job_Aborted=3, // red icon<br />
*job_Done=4, // green icon<br />
*job_WaitingForCallback=5 // blue icon - Special case used in certain derived classes<br />
<br />
If the status is 0, this means the job is queued but hasn't started. If it's 1 or 5 the job is being executed right now. Generally both 1 and 5 are presented to the user the same way as a 'busy', although technically 1 means Vera is actively talking to the device, and 5 means Vera is waiting for a reply from the device. Status codes 2, 3 and 4 mean the job has finished. 4 means the job went ok, and both 2 and 3 mean it failed. Technically 3 means the job was aborted by another job or an external process, like a user cancelling it, while 2 means it failed due to a problem talking to the device. In both cases this is usually presented the user the same way, as a failure.<br />
<br />
== Categories and device types ==<br />
<br />
The values used in user_data to determine the types of devices are in [[Luup_UPNP_Files]]. In general you can use the category instead of the devicetype since it's an integer and is thus faster to compare:<br />
<br />
== pseudo-code for a UI ==<br />
<br />
Here is some pseudo code to show how the polling mechanism should be properly implemented. The parsing code is, of course, unique to your UI, so placeholder function names are shown here, like FetchAndParse. This shows the flow for handling the polling so you know you get the changes reported correctly.<br />
<br />
variable int DataVersion_lustatus=0<br />
variable int LoadTime=0<br />
variable int DataVersion_userdata=0<br />
<br />
:START<br />
variable boolean FetchUserData=false;<br />
if( DataVersion_userdata==0 ) // If we're on the first loop and haven't retrieved user_data, do it and don't do an lu_status<br />
FetchUserData=true;<br />
else<br />
{<br />
while(true)<br />
{<br />
newdata = FetchAndParse("lu_status&DataVersion="+DataVersion_lustatus+"&LoadTime="+LoadTime);<br />
if( newdata.IsEmpty()==false && newdata.isError()==false )<br />
break; // If we got data, continue on and process it<br />
else<br />
Sleep 1; // If we didn't get anything, or if lu_status failed, just sleep 1 second and stay in the loop to try again<br />
} // End of while loop<br />
<br />
if( newdata.UserData_DataVersion!=DataVersion_userdata )<br />
{<br />
FetchUserData=true;<br />
}<br />
else // Only Parse if userdata is the same, otherwise we're going to reload user_data<br />
{<br />
ParseLuStatus(); // This won't run if user_data has changed<br />
DataVersion_lustatus=newdata.DataVersion<br />
}<br />
} // end of else loop<br />
<br />
if( FetchUserData==true )<br />
{<br />
UI.HourglassAndSuspend(true); // Put a 'busy' hourglass in the UI, display a message in the info panel "Updating data" and suspend all UI stuff since this may take a moment<br />
newdata = FetchAndParse("user_data2");<br />
if( newdata.IsEmpty()==false && newdata.isError()==false )<br />
{<br />
ParseUserData();<br />
DataVersion_lustatus=newdata.DataVersion<br />
LoadTime=newdata.LoadTime<br />
DataVersion_userdata=newdata.DataVersion<br />
}<br />
else<br />
UI.DisplayError("Failed to update data"); // Display in the info panel an error message that the user will see for 10 seconds or so<br />
<br />
UI.HourglassAndSuspend(false); // Put a 'busy' hourglass in the UI, display a message in the info panel "Updating data" and suspend all UI stuff since this may take a moment<br />
}<br />
<br />
Sleep 1; // We know we just parsed user_data or lu_status, so sleep before looping<br />
goto START; // Loop again and start over</div>Andreimioshttp://wiki.mios.com/index.php/UI_NotesUI Notes2015-07-03T12:26:33Z<p>Andreimios: /* user_data */</p>
<hr />
<div>[[Category:Development]]<br />
Here is some general information about getting information to display in a user interface:<br />
<br />
== UPnP messaging system ==<br />
<br />
Vera uses UPnP for all the messaging, such as turning lights on and off. So Vera translates Z-Wave, Insteon, infrared codes, etc., into UPnP actions. If you have already implemented a UPnP stack and can send properly formated UPnP SOAP/XML requests, you can control everything using standard UPnP action invocation. If you did not, Vera provides a simple HTTP GET interface as well, which is discussed below.<br />
<br />
In a nutshell UPnP works like this: You have UPnP devices, which are things that can be controlled and can report their state, like a light switch. And you have UPnP Control Points, which are the things that let a user control UPnP devices, like a touch-screen web pad. The Control Point does this by a) reading the device and descriptions for the UPnP device to see what it can do, and b) invoking actions on the UPnP device (ie telling it to do something), and c) reading and setting variables for the device which describe the current state and/or configuration settings for the device.<br />
<br />
A UPnP device is defined in an XML document called a device description document. To see one, in Vera's setup UI, go to Devices, Luup plugins, Luup Files, and click 'view' file next to D_BinaryLight1.xml. Use Firefox since it has a built-in XML viewer. Notice the tag: <deviceType>urn:schemas-upnp-org:device:BinaryLight:1</deviceType>. This defines the type of device, namely an on/off light switch, which is what you use to know how to represent this device to a user. A device optionally implements one or more services. In this case the services: urn:upnp-org:serviceId:SwitchPower1, urn:micasaverde-com:serviceId:EnergyMetering1 and urn:micasaverde-com:serviceId:HaDevice1.<br />
<br />
A service is a collection of actions which a device implement and which you can invoke from a UPnP Control Point, as well as a collection of variables which always have a current value. The variables describe the current state of the device and/or configuration settings. View the file S_SwitchPower1.xml to see a service. For example, the device urn:schemas-upnp-org:device:BinaryLight:1 implements the service urn:upnp-org:serviceId:SwitchPower1, which has the action SetTarget, which is how you turn the light on and off. The action takes a single argument newTargetValue which can be 0 to turn the light off and 1 to turn it on. The service also has the variable Status which is 0 or 1 depending on whether the light is currently on or off.<br />
<br />
If you open the device description for a dimmable light D_DimmableLight1.xml you'll see that it implements the same service S_SwitchPower1.xml, since you can still turn it on and off, and it also implements the service urn:upnp-org:serviceId:Dimming1, which has an action to set the dim level (SetLoadLevelTarget).<br />
<br />
To test UPnP calls you can use the Intel Device Spy utility available [http://www.intel.com/cd/ids/developer/asmo-na/eng/downloads/upnp/tools/218896.htm?desturl=http://softwarecommunity.intel.com/isn/downloads/zips/IntelToolsForUPnPTechnology_v2.zip here]. It should pick up Vera, show you all the devices, like light switches, thermostats, etc., let you expand the services and see the actions and variables. Click an action, like SetTarget, to specify the arguments and click 'Invoke' to run the action, such as turning on and off the light.<br />
<br />
== JSON vs. XML ==<br />
<br />
The native UPnP protocol uses XML/SOAP. But there are also several times you will request data from Vera that has nothing to do with the UPnP spec. These will be done with data_request's as explained below, such as user_data, lu_status, etc. Internally Vera uses JSON as the native format, but Vera can convert to XML (details follow). In general when you want to view data in a human readable format, such as the device list, it's easiest to use the Firefox browser, and request Vera convert the data to XML. Firefox has a nice browser to display XML in human readable format. If you want to make the JSON data nicely formatted, you can use the web site jsonlint.com. In a UI application which will request data regularly from Vera we recommend retrieving everything in JSON format, not XML, because Vera's CPU is not that powerful and so continuous requests of data in XML format will cause a lot of CPU time to be devoted to converting JSON into XML.<br />
<br />
== Finding Vera on the local network ==<br />
<br />
You can find Vera by using the traditional UPnP discovery process, or you can retrieve this URL:<br>'''https://sta1.mios.com/locator_json.php?username=xxx''' where the username=xxx is optional, but, if specified, it will report all systems that mios.com user xxx can report whether local or remote, and without the username=xxx it only shows the Vera's on the user's local home network.<br />
<br />
Each Vera, when it boots up, reports its internal IP address to the central mios.com server, which tracks this along with the external IP address. '''locator.php''' shows all serial numbers and internal network IP addresses on the same external IP. For example, if '''https://sta1.mios.com/locator_json.php?username=xxx'''.<br />
<br />
== The HTTP interface ==<br />
<br />
Vera listens on port 3480. Vera responds to UPnP actions the normal way, or by making simple HTTP requests. For example, to turn on a light you can either send the UPnP action "SetTarget" to the device using the normal UPnP mechanism, or you can simply put this URL in your web browser, or with wget, or similar: <br />
<br />
http://[ipadress]:3480/data_request?id=lu_action&amp;output_format=xml&amp;DeviceNum=10&amp;serviceId=urn:upnp-org:serviceId:SwitchPower1&amp;action=SetTarget&amp;newTargetValue=1 <br />
<br />
That URL will return the same results of the action as using the normal UPnP architecture. The '''output_format=xml''' on the URL means the data returned should be in XML format. You can instead use '''output_format=json'''<br />
<br />
The service ID's, actions, and arguments are all defined by the UPnP forum. A list of ratified UPnP devices and services is available on the [http://www.upnp.org UPnP Forum]. Mi Casa Verde added its own custom devices and services when there was no existing UPnP standard. A list of these can be found in the [[Luup_UPNP_Files]] header files.<br />
<br />
== Getting the system configuration ==<br />
<br />
Either use the UPnP service/action:<br> '''urn:micasaverde-com:serviceId:HomeAutomationGateway1/GetUserData''' <br />
<br />
or use the built-in request: <br />
<br />
'''http://ipaddress:3480/data_request?id=user_data2&amp;output_format=json''' (or xml) <br />
<br />
This returns the system configuration file for Vera. It's assumed you understand the way Vera categorizes devices with Rooms, Devices, Scenes, etc. When creating a user interface for controlling Vera only, like on a mobile phone, most of the tags can be ignored, since usually you just need the list of rooms and devices.<br />
<br />
== Accessing Vera remotely through the mios server ==<br />
<br />
Native UPnP only works on a local area home network, and cannot be used over the Internet. The mios server provides a secure way to remotely access and control your Vera system using the HTTP interface without having to make any substantial changes to the UI. Everything you can do locally with Vera on port 3480, you can do remotely with mios using the exact same syntax. You only need to ask the user for his username and password and pass them on the URL to the remote access server, along with the serial number of the unit (ie like 12345). For example, the above user_data is the syntax for local access on a home network. To retrieve the same URL over the internet with mios use:<br />
<br />
https://fwd2.mios.com/demovera/myvera123/12345/data_request?id=lu_status&output_format=json (or use fwd1.mios.com)<br />
<br />
assuming demovera is the username and myvera123 is the password that the user chose setting up his mios.com account. Note that since the request is https, the username and password are encrypted because https encrypts the URL's as well as the contents of the page.<br />
<br />
== Building a control-only UI for Vera ==<br />
<br />
If you just want to control Vera, and not modify the configuration, such as with a cell phone interface or web pad, the flow might possibly work like this: <br />
<br />
'''1)''' For the initial setup, you need to ask whether the user wants to (a)&nbsp;access Vera remotely with the mios service, and if so, get the user's username/password; or (b) access Vera directly on the home network. You can use locator.php to show the Vera on the home network. You might want to do an auto-detect. For example, you could use locator.php to see if Vera exists locally, and if not, prompt the user for a mios username and password. You can use locator.php and pass the username to get the serial number and internal IP, and then automatically switch to direct access if locator.php (without the username) indicates that serial number is found on the local network. This would allow the user to automatically switch between local access with Wi-Fi (which is much faster of course) and remote access with mios and the mobile phone network. Or just ask for his mios username and show him all the Vera's he can control, either local or remote.<br />
<br />
'''2)''' Once the connection is established, retrieve the list of rooms, scenes, and devices from Vera (see '''user_data''' below). You can cache this data locally so you don't need to retrieve it and parse it over and over.<br />
<br />
'''3)''' Present the user with the rooms, scenes, devices. In Vera's UI's we show first the rooms and then let the user pick a device or scene in the room. However this data could be presented graphically, such as on a floorplan. Your UI can have Vera store extra tags and data in the configuration database (ie user_data) to store things like coordinates for icons, outlines or rooms and so on.<br />
<br />
'''4)''' If the user picks a scene you can run the scene with the following URL, passing the scene number as '''x''', and it will return an OK if it went okay: <br />
<br />
http://127.0.0.1:3480/data_request?id=lu_action&amp;serviceId=urn:micasaverde-com:serviceId:HomeAutomationGateway1&amp;action=RunScene&amp;SceneNum=x <br />
<br />
'''5)''' If the user picks a device, you use the category which is contained in the user_data to determine what type of controls to present the user. (See [[Luup UPNP Files]] for a list of the categories.) When the user chooses an action, you can send it like this: <br />
<br />
http://ipadress:3480/data_request?id=lu_action&amp;output_format=xml&amp;DeviceNum=10&amp;serviceId=urn:upnp-org:serviceId:SwitchPower1&amp;action=SetTarget&amp;newTargetValue=1 <br />
<br />
For a list of common actions and device types see: [[Luup CP Mandatory Types]] <br />
<br />
Some actions return immediately with an 'OK'. Other jobs may take time to complete and are processed asynchronously. For these asynchronous jobs you will get a job ID back. There are several ways to present this to the user. One possibility is to do what Vera does in the UI, namely to use '''lu_status '''(explained next) to find all active jobs and to put a 'job' icon next to each device to indicate the progress of the job. In this way the user isn't tracking a particular job ''per se'', but just has visual feedback that a device is busy, and if the job icon(s) turn green, that everything went through okay. You could instead track the action individually using the job number that is returned, or use some other method, like making the icon for the device appear animated while it's busy, and turn green or red if the last command succeeded or failed.<br />
<br />
'''6)''' Periodically poll the system with '''lu_status''' (explained below), like this: <br />
<br />
http://ipaddress:3480/data_request?id=lu_status&amp;output_format=json <br />
<br />
That returns the current values of the UPnP variables, which you can use to show the user current status. For example, if the variable Status is 1 for a switch, you can show the 'on' button in a selected state, while 0 shows it in an 'off' state. '''lu_status''' also shows any active jobs for a device.<br />
<br />
==user_data==<br />
<br />
The user_data is the main configuration file that Vera uses to store all the rooms, devices, scenes, timers, events, users, and any other data about the system. You should request the user_data to get whatever data you need to present to the user, at a minimum, for example, you'll need the list of devices, their descriptions, and the categories (light switch, thermostat, etc.). You'll also want the list of scenes to present the user. To fetch the current user_data from Vera use the user_data request, like this:<br />
<br />
Returns JSON (preferred native format):<br />
<br />
http://[ip address]:3480/data_request?id=user_data<br />
<br />
Returns XML:<br />
<br />
http://[ip address]:3480/data_request?id=user_data&output_format=xml<br />
<br />
You can also add a 'DataVersion=TimeStamp' parameter to the URL. It the data has changed since the TimeStamp, all the data is returned. If the data has not changed since the TimeStamp, Vera will return a page with the text 'NO_CHANGES':<br />
<br />
http://[ip address]:3480/data_request?id=user_data&DataVersion=315587159<br />
<br />
The user_data contains the state for all the devices. For example this indicates that the device id #17, called "Switch" is turned off (ie service SwitchPower1, variable Status is 0)<br />
<br />
{<br />
"devices": [<br />
{<br />
"id": 17,<br />
"category": 3,<br />
"room": 1,<br />
"name": "Switch",<br />
"ip": "",<br />
"mac": "",<br />
{<br />
"service": "urn:upnp-org:serviceId:SwitchPower1",<br />
"variable": "Status",<br />
"value": "0" <br />
}<br />
}<br />
]<br />
}<br />
<br />
{{Warning|On UI7 build lu_sdata and lu_status have been deprecated, and you should use "status" instead.}}<br />
<br />
==lu_status==<br />
The UPnP variables describe the state of the devices according to the UPnP specs. When the variables change that information needs to be shown to the user, eg change a Switch icon from off to on. If you are interfacing with Vera using the UPnP stack, you can subscribe to the device's events to receive notifications automatically when a device's state changes. However if you're using the web interface you will need to poll using lu_status request.<br />
<br />
Call lu_status request like so:<br />
<br />
:http://[ip address]:3480/data_request?id=lu_status<br />
<br />
:http://[ip address]:3480/data_request?id=lu_status&output_format=xml<br />
<br />
:http://[ip address]:3480/data_request?id=lu_status&DataVersion=315587159<br />
<br />
<br />
The returned document contains four sets of information, which constantly change to reflect the current status:<br />
* root attributes including DataVersion, which is the status timestamp, plus other attributes such as LoadTime <br />
*the state of the system initialization, such as initialization of the plugin modules.<br />
*a '''subset''' of the user_data that represents the current state of the device's UPnP variables<br />
*the status of any active or recent '''jobs''', such as if a light was successfully turned off<br />
<br />
===Tracking status changes===<br />
If you call lu_status without passing a DataVersion on the URL, you will get the current value of all the UPnP variables for a device. Note that most of the UPnP variables do not ever change. For example, with a light switch, only the variable "SwitchPower:Status" changes, as the switch is turned off and on. There are many other variables, like "Capabilities" which are simply configuration data or settings the user modified. If you pass &DataVersion=1 on the URL, you will only see the UPnP variables which have changed since the Luup engine started. So, if you parse the initial UPnP variables when you first call user_data, you can call lu_status with DataVersion=1. Once you call lu_status the first time, store the DataVersion and on subsequent calls pass it on the URL and you will only get the UPnP variables which have changed since that last DataVersion. Regardless, you will also get the current state of jobs and system initialization.<br />
<br />
On subsequent calls to lu_status, you should also pass back in the LoadTime which you received on the prior call.<br />
<br />
===Controlling the poll timing===<br />
You can also pass in a Timeout value, which means the call will block for up to that many seconds if nothing has changed, and will return immediately when something does. This way you can have infrequent polling, say every 60 seconds by putting a Timeout value of 60, but your UI will be immediately responsive since, when something changes, it returns immediately. You can also add a MinimumDelay, which means that the call will wait for at least that many milliseconds. This is advisable so that in the event there are lots of continuous changes, such as a scene turning off many lights, you won't have lu_status calls returning non-stop consuming all the resources on both the Vera and the UI.<br />
<br />
===Startup status===<br />
The section with the initialization tasks is shown in the startup tag as shown:<br />
<br />
"startup": {<br />
"tasks": [<br />
{<br />
"id": 0,<br />
"status": 2,<br />
"type": "ZWave",<br />
"comments": "No Z-Wave" <br />
},<br />
<br />
The startup tasks begin whenever the Luup engine is reset, such as after the user makes a configuration change. Ever plugin and module in the Luup engine does a startup sequence. The id is not really important. The status numbers are the same as for jobs, so 2 means the module failed to startup. The 'Type' is what you can use to key off of to know which module is being reported, such as "ZWave", and comments are just notes indicating the current state. For example, "No Z-Wave" means there's no Z-Wave dongle connected.<br />
<br />
Once all the plugins have been initialized successfully the startup section will disappear completely from lu_status.<br />
<br />
Note that lu_status also returns UserData_DataVersion, which is the dataversion from user_data. That way you don't need to poll user_data in parallel. Simply retrieve the user_data one time at startup, then poll lu_status, and, if UserData_DataVersion is different from the previous user_data you retrieved, then download user_data again.<br />
<br />
Some notes on building a full replacement, including configuration, are available here [[UI_Notes_Replacement]], however the syntax is not up to date with the Luup architecture.<br />
<br />
===Job status===<br />
The jobs for a device will look like this:<br />
<br />
"devices": [<br />
{<br />
"id": 1,<br />
"Jobs": [<br />
{<br />
"id": "1",<br />
"name": "job#1 :getnodes (0x00D068F0) P:10 S:4",<br />
"icon": "",<br />
"comments": "",<br />
"status": "4" <br />
} <br />
] <br />
},<br />
<br />
The id is the job id number. When you run an action, like turning on a light, if it happens asynchronously, you'll get a job id number. All pending jobs for a device are shown by their id number. The name is just an internal name for the job. Icon is an optional keyword to indicate what sort of icon should be shown to the user. For example, 'getnodes' has no icon, meaning this type of job is generally not of interest to a user. If the icon was 'ON' or 'OFF' that would mean this job is busy turning on or off a light. Comments is notes about the job, if any. This may be shown to a user in a tool tip or similar, but is generally more technical than users would care to know. The status indicates the current state of the job, as shown:<br />
<br />
*job_None=-1, // no icon<br />
*job_WaitingToStart=0, // gray icon<br />
*job_InProgress=1, // blue icon<br />
*job_Error=2, // red icon<br />
*job_Aborted=3, // red icon<br />
*job_Done=4, // green icon<br />
*job_WaitingForCallback=5 // blue icon - Special case used in certain derived classes<br />
<br />
If the status is 0, this means the job is queued but hasn't started. If it's 1 or 5 the job is being executed right now. Generally both 1 and 5 are presented to the user the same way as a 'busy', although technically 1 means Vera is actively talking to the device, and 5 means Vera is waiting for a reply from the device. Status codes 2, 3 and 4 mean the job has finished. 4 means the job went ok, and both 2 and 3 mean it failed. Technically 3 means the job was aborted by another job or an external process, like a user cancelling it, while 2 means it failed due to a problem talking to the device. In both cases this is usually presented the user the same way, as a failure.<br />
<br />
== Categories and device types ==<br />
<br />
The values used in user_data to determine the types of devices are in [[Luup_UPNP_Files]]. In general you can use the category instead of the devicetype since it's an integer and is thus faster to compare:<br />
<br />
== pseudo-code for a UI ==<br />
<br />
Here is some pseudo code to show how the polling mechanism should be properly implemented. The parsing code is, of course, unique to your UI, so placeholder function names are shown here, like FetchAndParse. This shows the flow for handling the polling so you know you get the changes reported correctly.<br />
<br />
variable int DataVersion_lustatus=0<br />
variable int LoadTime=0<br />
variable int DataVersion_userdata=0<br />
<br />
:START<br />
variable boolean FetchUserData=false;<br />
if( DataVersion_userdata==0 ) // If we're on the first loop and haven't retrieved user_data, do it and don't do an lu_status<br />
FetchUserData=true;<br />
else<br />
{<br />
while(true)<br />
{<br />
newdata = FetchAndParse("lu_status&DataVersion="+DataVersion_lustatus+"&LoadTime="+LoadTime);<br />
if( newdata.IsEmpty()==false && newdata.isError()==false )<br />
break; // If we got data, continue on and process it<br />
else<br />
Sleep 1; // If we didn't get anything, or if lu_status failed, just sleep 1 second and stay in the loop to try again<br />
} // End of while loop<br />
<br />
if( newdata.UserData_DataVersion!=DataVersion_userdata )<br />
{<br />
FetchUserData=true;<br />
}<br />
else // Only Parse if userdata is the same, otherwise we're going to reload user_data<br />
{<br />
ParseLuStatus(); // This won't run if user_data has changed<br />
DataVersion_lustatus=newdata.DataVersion<br />
}<br />
} // end of else loop<br />
<br />
if( FetchUserData==true )<br />
{<br />
UI.HourglassAndSuspend(true); // Put a 'busy' hourglass in the UI, display a message in the info panel "Updating data" and suspend all UI stuff since this may take a moment<br />
newdata = FetchAndParse("user_data2");<br />
if( newdata.IsEmpty()==false && newdata.isError()==false )<br />
{<br />
ParseUserData();<br />
DataVersion_lustatus=newdata.DataVersion<br />
LoadTime=newdata.LoadTime<br />
DataVersion_userdata=newdata.DataVersion<br />
}<br />
else<br />
UI.DisplayError("Failed to update data"); // Display in the info panel an error message that the user will see for 10 seconds or so<br />
<br />
UI.HourglassAndSuspend(false); // Put a 'busy' hourglass in the UI, display a message in the info panel "Updating data" and suspend all UI stuff since this may take a moment<br />
}<br />
<br />
Sleep 1; // We know we just parsed user_data or lu_status, so sleep before looping<br />
goto START; // Loop again and start over</div>Andreimioshttp://wiki.mios.com/index.php/UI_NotesUI Notes2015-06-04T12:07:37Z<p>Andreimios: </p>
<hr />
<div>[[Category:Development]]<br />
Here is some general information about getting information to display in a user interface:<br />
<br />
== UPnP messaging system ==<br />
<br />
Vera uses UPnP for all the messaging, such as turning lights on and off. So Vera translates Z-Wave, Insteon, infrared codes, etc., into UPnP actions. If you have already implemented a UPnP stack and can send properly formated UPnP SOAP/XML requests, you can control everything using standard UPnP action invocation. If you did not, Vera provides a simple HTTP GET interface as well, which is discussed below.<br />
<br />
In a nutshell UPnP works like this: You have UPnP devices, which are things that can be controlled and can report their state, like a light switch. And you have UPnP Control Points, which are the things that let a user control UPnP devices, like a touch-screen web pad. The Control Point does this by a) reading the device and descriptions for the UPnP device to see what it can do, and b) invoking actions on the UPnP device (ie telling it to do something), and c) reading and setting variables for the device which describe the current state and/or configuration settings for the device.<br />
<br />
A UPnP device is defined in an XML document called a device description document. To see one, in Vera's setup UI, go to Devices, Luup plugins, Luup Files, and click 'view' file next to D_BinaryLight1.xml. Use Firefox since it has a built-in XML viewer. Notice the tag: <deviceType>urn:schemas-upnp-org:device:BinaryLight:1</deviceType>. This defines the type of device, namely an on/off light switch, which is what you use to know how to represent this device to a user. A device optionally implements one or more services. In this case the services: urn:upnp-org:serviceId:SwitchPower1, urn:micasaverde-com:serviceId:EnergyMetering1 and urn:micasaverde-com:serviceId:HaDevice1.<br />
<br />
A service is a collection of actions which a device implement and which you can invoke from a UPnP Control Point, as well as a collection of variables which always have a current value. The variables describe the current state of the device and/or configuration settings. View the file S_SwitchPower1.xml to see a service. For example, the device urn:schemas-upnp-org:device:BinaryLight:1 implements the service urn:upnp-org:serviceId:SwitchPower1, which has the action SetTarget, which is how you turn the light on and off. The action takes a single argument newTargetValue which can be 0 to turn the light off and 1 to turn it on. The service also has the variable Status which is 0 or 1 depending on whether the light is currently on or off.<br />
<br />
If you open the device description for a dimmable light D_DimmableLight1.xml you'll see that it implements the same service S_SwitchPower1.xml, since you can still turn it on and off, and it also implements the service urn:upnp-org:serviceId:Dimming1, which has an action to set the dim level (SetLoadLevelTarget).<br />
<br />
To test UPnP calls you can use the Intel Device Spy utility available [http://www.intel.com/cd/ids/developer/asmo-na/eng/downloads/upnp/tools/218896.htm?desturl=http://softwarecommunity.intel.com/isn/downloads/zips/IntelToolsForUPnPTechnology_v2.zip here]. It should pick up Vera, show you all the devices, like light switches, thermostats, etc., let you expand the services and see the actions and variables. Click an action, like SetTarget, to specify the arguments and click 'Invoke' to run the action, such as turning on and off the light.<br />
<br />
== JSON vs. XML ==<br />
<br />
The native UPnP protocol uses XML/SOAP. But there are also several times you will request data from Vera that has nothing to do with the UPnP spec. These will be done with data_request's as explained below, such as user_data, lu_status, etc. Internally Vera uses JSON as the native format, but Vera can convert to XML (details follow). In general when you want to view data in a human readable format, such as the device list, it's easiest to use the Firefox browser, and request Vera convert the data to XML. Firefox has a nice browser to display XML in human readable format. If you want to make the JSON data nicely formatted, you can use the web site jsonlint.com. In a UI application which will request data regularly from Vera we recommend retrieving everything in JSON format, not XML, because Vera's CPU is not that powerful and so continuous requests of data in XML format will cause a lot of CPU time to be devoted to converting JSON into XML.<br />
<br />
== Finding Vera on the local network ==<br />
<br />
You can find Vera by using the traditional UPnP discovery process, or you can retrieve this URL:<br>'''https://sta1.mios.com/locator_json.php?username=xxx''' where the username=xxx is optional, but, if specified, it will report all systems that mios.com user xxx can report whether local or remote, and without the username=xxx it only shows the Vera's on the user's local home network.<br />
<br />
Each Vera, when it boots up, reports its internal IP address to the central mios.com server, which tracks this along with the external IP address. '''locator.php''' shows all serial numbers and internal network IP addresses on the same external IP. For example, if '''https://sta1.mios.com/locator_json.php?username=xxx'''.<br />
<br />
== The HTTP interface ==<br />
<br />
Vera listens on port 3480. Vera responds to UPnP actions the normal way, or by making simple HTTP requests. For example, to turn on a light you can either send the UPnP action "SetTarget" to the device using the normal UPnP mechanism, or you can simply put this URL in your web browser, or with wget, or similar: <br />
<br />
http://[ipadress]:3480/data_request?id=lu_action&amp;output_format=xml&amp;DeviceNum=10&amp;serviceId=urn:upnp-org:serviceId:SwitchPower1&amp;action=SetTarget&amp;newTargetValue=1 <br />
<br />
That URL will return the same results of the action as using the normal UPnP architecture. The '''output_format=xml''' on the URL means the data returned should be in XML format. You can instead use '''output_format=json'''<br />
<br />
The service ID's, actions, and arguments are all defined by the UPnP forum. A list of ratified UPnP devices and services is available on the [http://www.upnp.org UPnP Forum]. Mi Casa Verde added its own custom devices and services when there was no existing UPnP standard. A list of these can be found in the [[Luup_UPNP_Files]] header files.<br />
<br />
== Getting the system configuration ==<br />
<br />
Either use the UPnP service/action:<br> '''urn:micasaverde-com:serviceId:HomeAutomationGateway1/GetUserData''' <br />
<br />
or use the built-in request: <br />
<br />
'''http://ipaddress:3480/data_request?id=user_data2&amp;output_format=json''' (or xml) <br />
<br />
This returns the system configuration file for Vera. It's assumed you understand the way Vera categorizes devices with Rooms, Devices, Scenes, etc. When creating a user interface for controlling Vera only, like on a mobile phone, most of the tags can be ignored, since usually you just need the list of rooms and devices.<br />
<br />
== Accessing Vera remotely through the mios server ==<br />
<br />
Native UPnP only works on a local area home network, and cannot be used over the Internet. The mios server provides a secure way to remotely access and control your Vera system using the HTTP interface without having to make any substantial changes to the UI. Everything you can do locally with Vera on port 3480, you can do remotely with mios using the exact same syntax. You only need to ask the user for his username and password and pass them on the URL to the remote access server, along with the serial number of the unit (ie like 12345). For example, the above user_data is the syntax for local access on a home network. To retrieve the same URL over the internet with mios use:<br />
<br />
https://fwd2.mios.com/demovera/myvera123/12345/data_request?id=lu_status&output_format=json (or use fwd1.mios.com)<br />
<br />
assuming demovera is the username and myvera123 is the password that the user chose setting up his mios.com account. Note that since the request is https, the username and password are encrypted because https encrypts the URL's as well as the contents of the page.<br />
<br />
== Building a control-only UI for Vera ==<br />
<br />
If you just want to control Vera, and not modify the configuration, such as with a cell phone interface or web pad, the flow might possibly work like this: <br />
<br />
'''1)''' For the initial setup, you need to ask whether the user wants to (a)&nbsp;access Vera remotely with the mios service, and if so, get the user's username/password; or (b) access Vera directly on the home network. You can use locator.php to show the Vera on the home network. You might want to do an auto-detect. For example, you could use locator.php to see if Vera exists locally, and if not, prompt the user for a mios username and password. You can use locator.php and pass the username to get the serial number and internal IP, and then automatically switch to direct access if locator.php (without the username) indicates that serial number is found on the local network. This would allow the user to automatically switch between local access with Wi-Fi (which is much faster of course) and remote access with mios and the mobile phone network. Or just ask for his mios username and show him all the Vera's he can control, either local or remote.<br />
<br />
'''2)''' Once the connection is established, retrieve the list of rooms, scenes, and devices from Vera (see '''user_data''' below). You can cache this data locally so you don't need to retrieve it and parse it over and over.<br />
<br />
'''3)''' Present the user with the rooms, scenes, devices. In Vera's UI's we show first the rooms and then let the user pick a device or scene in the room. However this data could be presented graphically, such as on a floorplan. Your UI can have Vera store extra tags and data in the configuration database (ie user_data) to store things like coordinates for icons, outlines or rooms and so on.<br />
<br />
'''4)''' If the user picks a scene you can run the scene with the following URL, passing the scene number as '''x''', and it will return an OK if it went okay: <br />
<br />
http://127.0.0.1:3480/data_request?id=lu_action&amp;serviceId=urn:micasaverde-com:serviceId:HomeAutomationGateway1&amp;action=RunScene&amp;SceneNum=x <br />
<br />
'''5)''' If the user picks a device, you use the category which is contained in the user_data to determine what type of controls to present the user. (See [[Luup UPNP Files]] for a list of the categories.) When the user chooses an action, you can send it like this: <br />
<br />
http://ipadress:3480/data_request?id=lu_action&amp;output_format=xml&amp;DeviceNum=10&amp;serviceId=urn:upnp-org:serviceId:SwitchPower1&amp;action=SetTarget&amp;newTargetValue=1 <br />
<br />
For a list of common actions and device types see: [[Luup CP Mandatory Types]] <br />
<br />
Some actions return immediately with an 'OK'. Other jobs may take time to complete and are processed asynchronously. For these asynchronous jobs you will get a job ID back. There are several ways to present this to the user. One possibility is to do what Vera does in the UI, namely to use '''lu_status '''(explained next) to find all active jobs and to put a 'job' icon next to each device to indicate the progress of the job. In this way the user isn't tracking a particular job ''per se'', but just has visual feedback that a device is busy, and if the job icon(s) turn green, that everything went through okay. You could instead track the action individually using the job number that is returned, or use some other method, like making the icon for the device appear animated while it's busy, and turn green or red if the last command succeeded or failed.<br />
<br />
'''6)''' Periodically poll the system with '''lu_status''' (explained below), like this: <br />
<br />
http://ipaddress:3480/data_request?id=lu_status&amp;output_format=json <br />
<br />
That returns the current values of the UPnP variables, which you can use to show the user current status. For example, if the variable Status is 1 for a switch, you can show the 'on' button in a selected state, while 0 shows it in an 'off' state. '''lu_status''' also shows any active jobs for a device.<br />
<br />
==user_data==<br />
NOTE: On UI3 builds, user_data2 and user_data are the same, and so is lu_status and lu_status. However, on UI2 builds, user_data and lu_status have been deprecated, and you should user_data2 and lu_status. Therefore, it's best to simply always use user_data2 instead of user_data, and lu_status instead of lu_status.<br />
<br />
The user_data is the main configuration file that Vera uses to store all the rooms, devices, scenes, timers, events, users, and any other data about the system. You should request the user_data to get whatever data you need to present to the user, at a minimum, for example, you'll need the list of devices, their descriptions, and the categories (light switch, thermostat, etc.). You'll also want the list of scenes to present the user. To fetch the current user_data from Vera use the user_data2 request, like this:<br />
<br />
Returns JSON (preferred native format):<br />
<br />
http://[ip address]:3480/data_request?id=user_data2<br />
<br />
Returns XML:<br />
<br />
http://[ip address]:3480/data_request?id=user_data2&output_format=xml<br />
<br />
You can also add a 'DataVersion=TimeStamp' parameter to the URL. It the data has changed since the TimeStamp, all the data is returned. If the data has not changed since the TimeStamp, Vera will return a page with the text 'NO_CHANGES':<br />
<br />
http://[ip address]:3480/data_request?id=user_data2&DataVersion=315587159<br />
<br />
The user_data contains the state for all the devices. For example this indicates that the device id #17, called "Switch" is turned off (ie service SwitchPower1, variable Status is 0)<br />
<br />
{<br />
"devices": [<br />
{<br />
"id": 17,<br />
"category": 3,<br />
"room": 1,<br />
"name": "Switch",<br />
"ip": "",<br />
"mac": "",<br />
{<br />
"service": "urn:upnp-org:serviceId:SwitchPower1",<br />
"variable": "Status",<br />
"value": "0" <br />
}<br />
}<br />
]<br />
}<br />
<br />
==lu_status==<br />
The UPnP variables describe the state of the devices according to the UPnP specs. When the variables change that information needs to be shown to the user, eg change a Switch icon from off to on. If you are interfacing with Vera using the UPnP stack, you can subscribe to the device's events to receive notifications automatically when a device's state changes. However if you're using the web interface you will need to poll using lu_status request.<br />
<br />
Call lu_status request like so:<br />
<br />
:http://[ip address]:3480/data_request?id=lu_status<br />
<br />
:http://[ip address]:3480/data_request?id=lu_status&output_format=xml<br />
<br />
:http://[ip address]:3480/data_request?id=lu_status&DataVersion=315587159<br />
<br />
<br />
The returned document contains four sets of information, which constantly change to reflect the current status:<br />
* root attributes including DataVersion, which is the status timestamp, plus other attributes such as LoadTime <br />
*the state of the system initialization, such as initialization of the plugin modules.<br />
*a '''subset''' of the user_data that represents the current state of the device's UPnP variables<br />
*the status of any active or recent '''jobs''', such as if a light was successfully turned off<br />
<br />
===Tracking status changes===<br />
If you call lu_status without passing a DataVersion on the URL, you will get the current value of all the UPnP variables for a device. Note that most of the UPnP variables do not ever change. For example, with a light switch, only the variable "SwitchPower:Status" changes, as the switch is turned off and on. There are many other variables, like "Capabilities" which are simply configuration data or settings the user modified. If you pass &DataVersion=1 on the URL, you will only see the UPnP variables which have changed since the Luup engine started. So, if you parse the initial UPnP variables when you first call user_data, you can call lu_status with DataVersion=1. Once you call lu_status the first time, store the DataVersion and on subsequent calls pass it on the URL and you will only get the UPnP variables which have changed since that last DataVersion. Regardless, you will also get the current state of jobs and system initialization.<br />
<br />
On subsequent calls to lu_status, you should also pass back in the LoadTime which you received on the prior call.<br />
<br />
===Controlling the poll timing===<br />
You can also pass in a Timeout value, which means the call will block for up to that many seconds if nothing has changed, and will return immediately when something does. This way you can have infrequent polling, say every 60 seconds by putting a Timeout value of 60, but your UI will be immediately responsive since, when something changes, it returns immediately. You can also add a MinimumDelay, which means that the call will wait for at least that many milliseconds. This is advisable so that in the event there are lots of continuous changes, such as a scene turning off many lights, you won't have lu_status calls returning non-stop consuming all the resources on both the Vera and the UI.<br />
<br />
===Startup status===<br />
The section with the initialization tasks is shown in the startup tag as shown:<br />
<br />
"startup": {<br />
"tasks": [<br />
{<br />
"id": 0,<br />
"status": 2,<br />
"type": "ZWave",<br />
"comments": "No Z-Wave" <br />
},<br />
<br />
The startup tasks begin whenever the Luup engine is reset, such as after the user makes a configuration change. Ever plugin and module in the Luup engine does a startup sequence. The id is not really important. The status numbers are the same as for jobs, so 2 means the module failed to startup. The 'Type' is what you can use to key off of to know which module is being reported, such as "ZWave", and comments are just notes indicating the current state. For example, "No Z-Wave" means there's no Z-Wave dongle connected.<br />
<br />
Once all the plugins have been initialized successfully the startup section will disappear completely from lu_status.<br />
<br />
Note that lu_status also returns UserData_DataVersion, which is the dataversion from user_data. That way you don't need to poll user_data in parallel. Simply retrieve the user_data one time at startup, then poll lu_status, and, if UserData_DataVersion is different from the previous user_data you retrieved, then download user_data again.<br />
<br />
Some notes on building a full replacement, including configuration, are available here [[UI_Notes_Replacement]], however the syntax is not up to date with the Luup architecture.<br />
<br />
===Job status===<br />
The jobs for a device will look like this:<br />
<br />
"devices": [<br />
{<br />
"id": 1,<br />
"Jobs": [<br />
{<br />
"id": "1",<br />
"name": "job#1 :getnodes (0x00D068F0) P:10 S:4",<br />
"icon": "",<br />
"comments": "",<br />
"status": "4" <br />
} <br />
] <br />
},<br />
<br />
The id is the job id number. When you run an action, like turning on a light, if it happens asynchronously, you'll get a job id number. All pending jobs for a device are shown by their id number. The name is just an internal name for the job. Icon is an optional keyword to indicate what sort of icon should be shown to the user. For example, 'getnodes' has no icon, meaning this type of job is generally not of interest to a user. If the icon was 'ON' or 'OFF' that would mean this job is busy turning on or off a light. Comments is notes about the job, if any. This may be shown to a user in a tool tip or similar, but is generally more technical than users would care to know. The status indicates the current state of the job, as shown:<br />
<br />
*job_None=-1, // no icon<br />
*job_WaitingToStart=0, // gray icon<br />
*job_InProgress=1, // blue icon<br />
*job_Error=2, // red icon<br />
*job_Aborted=3, // red icon<br />
*job_Done=4, // green icon<br />
*job_WaitingForCallback=5 // blue icon - Special case used in certain derived classes<br />
<br />
If the status is 0, this means the job is queued but hasn't started. If it's 1 or 5 the job is being executed right now. Generally both 1 and 5 are presented to the user the same way as a 'busy', although technically 1 means Vera is actively talking to the device, and 5 means Vera is waiting for a reply from the device. Status codes 2, 3 and 4 mean the job has finished. 4 means the job went ok, and both 2 and 3 mean it failed. Technically 3 means the job was aborted by another job or an external process, like a user cancelling it, while 2 means it failed due to a problem talking to the device. In both cases this is usually presented the user the same way, as a failure.<br />
<br />
== Categories and device types ==<br />
<br />
The values used in user_data to determine the types of devices are in [[Luup_UPNP_Files]]. In general you can use the category instead of the devicetype since it's an integer and is thus faster to compare:<br />
<br />
== pseudo-code for a UI ==<br />
<br />
Here is some pseudo code to show how the polling mechanism should be properly implemented. The parsing code is, of course, unique to your UI, so placeholder function names are shown here, like FetchAndParse. This shows the flow for handling the polling so you know you get the changes reported correctly.<br />
<br />
variable int DataVersion_lustatus=0<br />
variable int LoadTime=0<br />
variable int DataVersion_userdata=0<br />
<br />
:START<br />
variable boolean FetchUserData=false;<br />
if( DataVersion_userdata==0 ) // If we're on the first loop and haven't retrieved user_data, do it and don't do an lu_status<br />
FetchUserData=true;<br />
else<br />
{<br />
while(true)<br />
{<br />
newdata = FetchAndParse("lu_status&DataVersion="+DataVersion_lustatus+"&LoadTime="+LoadTime);<br />
if( newdata.IsEmpty()==false && newdata.isError()==false )<br />
break; // If we got data, continue on and process it<br />
else<br />
Sleep 1; // If we didn't get anything, or if lu_status failed, just sleep 1 second and stay in the loop to try again<br />
} // End of while loop<br />
<br />
if( newdata.UserData_DataVersion!=DataVersion_userdata )<br />
{<br />
FetchUserData=true;<br />
}<br />
else // Only Parse if userdata is the same, otherwise we're going to reload user_data<br />
{<br />
ParseLuStatus(); // This won't run if user_data has changed<br />
DataVersion_lustatus=newdata.DataVersion<br />
}<br />
} // end of else loop<br />
<br />
if( FetchUserData==true )<br />
{<br />
UI.HourglassAndSuspend(true); // Put a 'busy' hourglass in the UI, display a message in the info panel "Updating data" and suspend all UI stuff since this may take a moment<br />
newdata = FetchAndParse("user_data2");<br />
if( newdata.IsEmpty()==false && newdata.isError()==false )<br />
{<br />
ParseUserData();<br />
DataVersion_lustatus=newdata.DataVersion<br />
LoadTime=newdata.LoadTime<br />
DataVersion_userdata=newdata.DataVersion<br />
}<br />
else<br />
UI.DisplayError("Failed to update data"); // Display in the info panel an error message that the user will see for 10 seconds or so<br />
<br />
UI.HourglassAndSuspend(false); // Put a 'busy' hourglass in the UI, display a message in the info panel "Updating data" and suspend all UI stuff since this may take a moment<br />
}<br />
<br />
Sleep 1; // We know we just parsed user_data or lu_status, so sleep before looping<br />
goto START; // Loop again and start over</div>Andreimioshttp://wiki.mios.com/index.php/UI_NotesUI Notes2015-06-04T12:06:17Z<p>Andreimios: /* lu_status */</p>
<hr />
<div>[[Category:Development]]<br />
Here is some general information about getting information to display in a user interface:<br />
<br />
== UPnP messaging system ==<br />
<br />
Vera uses UPnP for all the messaging, such as turning lights on and off. So Vera translates Z-Wave, Insteon, infrared codes, etc., into UPnP actions. If you have already implemented a UPnP stack and can send properly formated UPnP SOAP/XML requests, you can control everything using standard UPnP action invocation. If you did not, Vera provides a simple HTTP GET interface as well, which is discussed below.<br />
<br />
In a nutshell UPnP works like this: You have UPnP devices, which are things that can be controlled and can report their state, like a light switch. And you have UPnP Control Points, which are the things that let a user control UPnP devices, like a touch-screen web pad. The Control Point does this by a) reading the device and descriptions for the UPnP device to see what it can do, and b) invoking actions on the UPnP device (ie telling it to do something), and c) reading and setting variables for the device which describe the current state and/or configuration settings for the device.<br />
<br />
A UPnP device is defined in an XML document called a device description document. To see one, in Vera's setup UI, go to Devices, Luup plugins, Luup Files, and click 'view' file next to D_BinaryLight1.xml. Use Firefox since it has a built-in XML viewer. Notice the tag: <deviceType>urn:schemas-upnp-org:device:BinaryLight:1</deviceType>. This defines the type of device, namely an on/off light switch, which is what you use to know how to represent this device to a user. A device optionally implements one or more services. In this case the services: urn:upnp-org:serviceId:SwitchPower1, urn:micasaverde-com:serviceId:EnergyMetering1 and urn:micasaverde-com:serviceId:HaDevice1.<br />
<br />
A service is a collection of actions which a device implement and which you can invoke from a UPnP Control Point, as well as a collection of variables which always have a current value. The variables describe the current state of the device and/or configuration settings. View the file S_SwitchPower1.xml to see a service. For example, the device urn:schemas-upnp-org:device:BinaryLight:1 implements the service urn:upnp-org:serviceId:SwitchPower1, which has the action SetTarget, which is how you turn the light on and off. The action takes a single argument newTargetValue which can be 0 to turn the light off and 1 to turn it on. The service also has the variable Status which is 0 or 1 depending on whether the light is currently on or off.<br />
<br />
If you open the device description for a dimmable light D_DimmableLight1.xml you'll see that it implements the same service S_SwitchPower1.xml, since you can still turn it on and off, and it also implements the service urn:upnp-org:serviceId:Dimming1, which has an action to set the dim level (SetLoadLevelTarget).<br />
<br />
To test UPnP calls you can use the Intel Device Spy utility available [http://www.intel.com/cd/ids/developer/asmo-na/eng/downloads/upnp/tools/218896.htm?desturl=http://softwarecommunity.intel.com/isn/downloads/zips/IntelToolsForUPnPTechnology_v2.zip here]. It should pick up Vera, show you all the devices, like light switches, thermostats, etc., let you expand the services and see the actions and variables. Click an action, like SetTarget, to specify the arguments and click 'Invoke' to run the action, such as turning on and off the light.<br />
<br />
== JSON vs. XML ==<br />
<br />
The native UPnP protocol uses XML/SOAP. But there are also several times you will request data from Vera that has nothing to do with the UPnP spec. These will be done with data_request's as explained below, such as user_data, lu_status, etc. Internally Vera uses JSON as the native format, but Vera can convert to XML (details follow). In general when you want to view data in a human readable format, such as the device list, it's easiest to use the Firefox browser, and request Vera convert the data to XML. Firefox has a nice browser to display XML in human readable format. If you want to make the JSON data nicely formatted, you can use the web site jsonlint.com. In a UI application which will request data regularly from Vera we recommend retrieving everything in JSON format, not XML, because Vera's CPU is not that powerful and so continuous requests of data in XML format will cause a lot of CPU time to be devoted to converting JSON into XML.<br />
<br />
== Finding Vera on the local network ==<br />
<br />
You can find Vera by using the traditional UPnP discovery process, or you can retrieve this URL:<br>'''https://sta1.mios.com/locator_json.php?username=xxx''' where the username=xxx is optional, but, if specified, it will report all systems that mios.com user xxx can report whether local or remote, and without the username=xxx it only shows the Vera's on the user's local home network.<br />
<br />
Each Vera, when it boots up, reports its internal IP address to the central mios.com server, which tracks this along with the external IP address. '''locator.php''' shows all serial numbers and internal network IP addresses on the same external IP. For example, if '''https://sta1.mios.com/locator_json.php?username=xxx'''.<br />
<br />
== The HTTP interface ==<br />
<br />
Vera listens on port 3480. Vera responds to UPnP actions the normal way, or by making simple HTTP requests. For example, to turn on a light you can either send the UPnP action "SetTarget" to the device using the normal UPnP mechanism, or you can simply put this URL in your web browser, or with wget, or similar: <br />
<br />
http://[ipadress]:3480/data_request?id=lu_action&amp;output_format=xml&amp;DeviceNum=10&amp;serviceId=urn:upnp-org:serviceId:SwitchPower1&amp;action=SetTarget&amp;newTargetValue=1 <br />
<br />
That URL will return the same results of the action as using the normal UPnP architecture. The '''output_format=xml''' on the URL means the data returned should be in XML format. You can instead use '''output_format=json'''<br />
<br />
The service ID's, actions, and arguments are all defined by the UPnP forum. A list of ratified UPnP devices and services is available on the [http://www.upnp.org UPnP Forum]. Mi Casa Verde added its own custom devices and services when there was no existing UPnP standard. A list of these can be found in the [[Luup_UPNP_Files]] header files.<br />
<br />
== Getting the system configuration ==<br />
<br />
Either use the UPnP service/action:<br> '''urn:micasaverde-com:serviceId:HomeAutomationGateway1/GetUserData''' <br />
<br />
or use the built-in request: <br />
<br />
'''http://ipaddress:3480/data_request?id=user_data2&amp;output_format=json''' (or xml) <br />
<br />
This returns the system configuration file for Vera. It's assumed you understand the way Vera categorizes devices with Rooms, Devices, Scenes, etc. When creating a user interface for controlling Vera only, like on a mobile phone, most of the tags can be ignored, since usually you just need the list of rooms and devices.<br />
<br />
== Accessing Vera remotely through the mios server ==<br />
<br />
Native UPnP only works on a local area home network, and cannot be used over the Internet. The mios server provides a secure way to remotely access and control your Vera system using the HTTP interface without having to make any substantial changes to the UI. Everything you can do locally with Vera on port 3480, you can do remotely with mios using the exact same syntax. You only need to ask the user for his username and password and pass them on the URL to the remote access server, along with the serial number of the unit (ie like 12345). For example, the above user_data is the syntax for local access on a home network. To retrieve the same URL over the internet with mios use:<br />
<br />
https://fwd2.mios.com/demovera/myvera123/12345/data_request?id=lu_status&output_format=json (or use fwd1.mios.com)<br />
<br />
assuming demovera is the username and myvera123 is the password that the user chose setting up his mios.com account. Note that since the request is https, the username and password are encrypted because https encrypts the URL's as well as the contents of the page.<br />
<br />
== Building a control-only UI for Vera ==<br />
<br />
If you just want to control Vera, and not modify the configuration, such as with a cell phone interface or web pad, the flow might possibly work like this: <br />
<br />
'''1)''' For the initial setup, you need to ask whether the user wants to (a)&nbsp;access Vera remotely with the mios service, and if so, get the user's username/password; or (b) access Vera directly on the home network. You can use locator.php to show the Vera on the home network. You might want to do an auto-detect. For example, you could use locator.php to see if Vera exists locally, and if not, prompt the user for a mios username and password. You can use locator.php and pass the username to get the serial number and internal IP, and then automatically switch to direct access if locator.php (without the username) indicates that serial number is found on the local network. This would allow the user to automatically switch between local access with Wi-Fi (which is much faster of course) and remote access with mios and the mobile phone network. Or just ask for his mios username and show him all the Vera's he can control, either local or remote.<br />
<br />
'''2)''' Once the connection is established, retrieve the list of rooms, scenes, and devices from Vera (see '''user_data''' below). You can cache this data locally so you don't need to retrieve it and parse it over and over.<br />
<br />
'''3)''' Present the user with the rooms, scenes, devices. In Vera's UI's we show first the rooms and then let the user pick a device or scene in the room. However this data could be presented graphically, such as on a floorplan. Your UI can have Vera store extra tags and data in the configuration database (ie user_data) to store things like coordinates for icons, outlines or rooms and so on.<br />
<br />
'''4)''' If the user picks a scene you can run the scene with the following URL, passing the scene number as '''x''', and it will return an OK if it went okay: <br />
<br />
http://127.0.0.1:3480/data_request?id=lu_action&amp;serviceId=urn:micasaverde-com:serviceId:HomeAutomationGateway1&amp;action=RunScene&amp;SceneNum=x <br />
<br />
'''5)''' If the user picks a device, you use the category which is contained in the user_data to determine what type of controls to present the user. (See [[Luup UPNP Files]] for a list of the categories.) When the user chooses an action, you can send it like this: <br />
<br />
http://ipadress:3480/data_request?id=lu_action&amp;output_format=xml&amp;DeviceNum=10&amp;serviceId=urn:upnp-org:serviceId:SwitchPower1&amp;action=SetTarget&amp;newTargetValue=1 <br />
<br />
For a list of common actions and device types see: [[Luup CP Mandatory Types]] <br />
<br />
Some actions return immediately with an 'OK'. Other jobs may take time to complete and are processed asynchronously. For these asynchronous jobs you will get a job ID back. There are several ways to present this to the user. One possibility is to do what Vera does in the UI, namely to use '''lu_status '''(explained next) to find all active jobs and to put a 'job' icon next to each device to indicate the progress of the job. In this way the user isn't tracking a particular job ''per se'', but just has visual feedback that a device is busy, and if the job icon(s) turn green, that everything went through okay. You could instead track the action individually using the job number that is returned, or use some other method, like making the icon for the device appear animated while it's busy, and turn green or red if the last command succeeded or failed.<br />
<br />
'''6)''' Periodically poll the system with '''lu_status''' (explained below), like this: <br />
<br />
http://ipaddress:3480/data_request?id=lu_status2&amp;output_format=json <br />
<br />
That returns the current values of the UPnP variables, which you can use to show the user current status. For example, if the variable Status is 1 for a switch, you can show the 'on' button in a selected state, while 0 shows it in an 'off' state. '''lu_status''' also shows any active jobs for a device.<br />
<br />
==user_data==<br />
NOTE: On UI3 builds, user_data2 and user_data are the same, and so is lu_status2 and lu_status. However, on UI2 builds, user_data and lu_status have been deprecated, and you should user_data2 and lu_status2. Therefore, it's best to simply always use user_data2 instead of user_data, and lu_status2 instead of lu_status.<br />
<br />
The user_data is the main configuration file that Vera uses to store all the rooms, devices, scenes, timers, events, users, and any other data about the system. You should request the user_data to get whatever data you need to present to the user, at a minimum, for example, you'll need the list of devices, their descriptions, and the categories (light switch, thermostat, etc.). You'll also want the list of scenes to present the user. To fetch the current user_data from Vera use the user_data2 request, like this:<br />
<br />
Returns JSON (preferred native format):<br />
<br />
http://[ip address]:3480/data_request?id=user_data2<br />
<br />
Returns XML:<br />
<br />
http://[ip address]:3480/data_request?id=user_data2&output_format=xml<br />
<br />
You can also add a 'DataVersion=TimeStamp' parameter to the URL. It the data has changed since the TimeStamp, all the data is returned. If the data has not changed since the TimeStamp, Vera will return a page with the text 'NO_CHANGES':<br />
<br />
http://[ip address]:3480/data_request?id=user_data2&DataVersion=315587159<br />
<br />
The user_data contains the state for all the devices. For example this indicates that the device id #17, called "Switch" is turned off (ie service SwitchPower1, variable Status is 0)<br />
<br />
{<br />
"devices": [<br />
{<br />
"id": 17,<br />
"category": 3,<br />
"room": 1,<br />
"name": "Switch",<br />
"ip": "",<br />
"mac": "",<br />
{<br />
"service": "urn:upnp-org:serviceId:SwitchPower1",<br />
"variable": "Status",<br />
"value": "0" <br />
}<br />
}<br />
]<br />
}<br />
<br />
==lu_status==<br />
The UPnP variables describe the state of the devices according to the UPnP specs. When the variables change that information needs to be shown to the user, eg change a Switch icon from off to on. If you are interfacing with Vera using the UPnP stack, you can subscribe to the device's events to receive notifications automatically when a device's state changes. However if you're using the web interface you will need to poll using lu_status request.<br />
<br />
Call lu_status request like so:<br />
<br />
:http://[ip address]:3480/data_request?id=lu_status<br />
<br />
:http://[ip address]:3480/data_request?id=lu_status&output_format=xml<br />
<br />
:http://[ip address]:3480/data_request?id=lu_status&DataVersion=315587159<br />
<br />
<br />
The returned document contains four sets of information, which constantly change to reflect the current status:<br />
* root attributes including DataVersion, which is the status timestamp, plus other attributes such as LoadTime <br />
*the state of the system initialization, such as initialization of the plugin modules.<br />
*a '''subset''' of the user_data that represents the current state of the device's UPnP variables<br />
*the status of any active or recent '''jobs''', such as if a light was successfully turned off<br />
<br />
===Tracking status changes===<br />
If you call lu_status without passing a DataVersion on the URL, you will get the current value of all the UPnP variables for a device. Note that most of the UPnP variables do not ever change. For example, with a light switch, only the variable "SwitchPower:Status" changes, as the switch is turned off and on. There are many other variables, like "Capabilities" which are simply configuration data or settings the user modified. If you pass &DataVersion=1 on the URL, you will only see the UPnP variables which have changed since the Luup engine started. So, if you parse the initial UPnP variables when you first call user_data, you can call lu_status with DataVersion=1. Once you call lu_status the first time, store the DataVersion and on subsequent calls pass it on the URL and you will only get the UPnP variables which have changed since that last DataVersion. Regardless, you will also get the current state of jobs and system initialization.<br />
<br />
On subsequent calls to lu_status, you should also pass back in the LoadTime which you received on the prior call.<br />
<br />
===Controlling the poll timing===<br />
You can also pass in a Timeout value, which means the call will block for up to that many seconds if nothing has changed, and will return immediately when something does. This way you can have infrequent polling, say every 60 seconds by putting a Timeout value of 60, but your UI will be immediately responsive since, when something changes, it returns immediately. You can also add a MinimumDelay, which means that the call will wait for at least that many milliseconds. This is advisable so that in the event there are lots of continuous changes, such as a scene turning off many lights, you won't have lu_status calls returning non-stop consuming all the resources on both the Vera and the UI.<br />
<br />
===Startup status===<br />
The section with the initialization tasks is shown in the startup tag as shown:<br />
<br />
"startup": {<br />
"tasks": [<br />
{<br />
"id": 0,<br />
"status": 2,<br />
"type": "ZWave",<br />
"comments": "No Z-Wave" <br />
},<br />
<br />
The startup tasks begin whenever the Luup engine is reset, such as after the user makes a configuration change. Ever plugin and module in the Luup engine does a startup sequence. The id is not really important. The status numbers are the same as for jobs, so 2 means the module failed to startup. The 'Type' is what you can use to key off of to know which module is being reported, such as "ZWave", and comments are just notes indicating the current state. For example, "No Z-Wave" means there's no Z-Wave dongle connected.<br />
<br />
Once all the plugins have been initialized successfully the startup section will disappear completely from lu_status.<br />
<br />
Note that lu_status also returns UserData_DataVersion, which is the dataversion from user_data. That way you don't need to poll user_data in parallel. Simply retrieve the user_data one time at startup, then poll lu_status, and, if UserData_DataVersion is different from the previous user_data you retrieved, then download user_data again.<br />
<br />
Some notes on building a full replacement, including configuration, are available here [[UI_Notes_Replacement]], however the syntax is not up to date with the Luup architecture.<br />
<br />
===Job status===<br />
The jobs for a device will look like this:<br />
<br />
"devices": [<br />
{<br />
"id": 1,<br />
"Jobs": [<br />
{<br />
"id": "1",<br />
"name": "job#1 :getnodes (0x00D068F0) P:10 S:4",<br />
"icon": "",<br />
"comments": "",<br />
"status": "4" <br />
} <br />
] <br />
},<br />
<br />
The id is the job id number. When you run an action, like turning on a light, if it happens asynchronously, you'll get a job id number. All pending jobs for a device are shown by their id number. The name is just an internal name for the job. Icon is an optional keyword to indicate what sort of icon should be shown to the user. For example, 'getnodes' has no icon, meaning this type of job is generally not of interest to a user. If the icon was 'ON' or 'OFF' that would mean this job is busy turning on or off a light. Comments is notes about the job, if any. This may be shown to a user in a tool tip or similar, but is generally more technical than users would care to know. The status indicates the current state of the job, as shown:<br />
<br />
*job_None=-1, // no icon<br />
*job_WaitingToStart=0, // gray icon<br />
*job_InProgress=1, // blue icon<br />
*job_Error=2, // red icon<br />
*job_Aborted=3, // red icon<br />
*job_Done=4, // green icon<br />
*job_WaitingForCallback=5 // blue icon - Special case used in certain derived classes<br />
<br />
If the status is 0, this means the job is queued but hasn't started. If it's 1 or 5 the job is being executed right now. Generally both 1 and 5 are presented to the user the same way as a 'busy', although technically 1 means Vera is actively talking to the device, and 5 means Vera is waiting for a reply from the device. Status codes 2, 3 and 4 mean the job has finished. 4 means the job went ok, and both 2 and 3 mean it failed. Technically 3 means the job was aborted by another job or an external process, like a user cancelling it, while 2 means it failed due to a problem talking to the device. In both cases this is usually presented the user the same way, as a failure.<br />
<br />
== Categories and device types ==<br />
<br />
The values used in user_data to determine the types of devices are in [[Luup_UPNP_Files]]. In general you can use the category instead of the devicetype since it's an integer and is thus faster to compare:<br />
<br />
== pseudo-code for a UI ==<br />
<br />
Here is some pseudo code to show how the polling mechanism should be properly implemented. The parsing code is, of course, unique to your UI, so placeholder function names are shown here, like FetchAndParse. This shows the flow for handling the polling so you know you get the changes reported correctly.<br />
<br />
variable int DataVersion_lustatus=0<br />
variable int LoadTime=0<br />
variable int DataVersion_userdata=0<br />
<br />
:START<br />
variable boolean FetchUserData=false;<br />
if( DataVersion_userdata==0 ) // If we're on the first loop and haven't retrieved user_data, do it and don't do an lu_status<br />
FetchUserData=true;<br />
else<br />
{<br />
while(true)<br />
{<br />
newdata = FetchAndParse("lu_status2&DataVersion="+DataVersion_lustatus+"&LoadTime="+LoadTime);<br />
if( newdata.IsEmpty()==false && newdata.isError()==false )<br />
break; // If we got data, continue on and process it<br />
else<br />
Sleep 1; // If we didn't get anything, or if lu_status failed, just sleep 1 second and stay in the loop to try again<br />
} // End of while loop<br />
<br />
if( newdata.UserData_DataVersion!=DataVersion_userdata )<br />
{<br />
FetchUserData=true;<br />
}<br />
else // Only Parse if userdata is the same, otherwise we're going to reload user_data<br />
{<br />
ParseLuStatus(); // This won't run if user_data has changed<br />
DataVersion_lustatus=newdata.DataVersion<br />
}<br />
} // end of else loop<br />
<br />
if( FetchUserData==true )<br />
{<br />
UI.HourglassAndSuspend(true); // Put a 'busy' hourglass in the UI, display a message in the info panel "Updating data" and suspend all UI stuff since this may take a moment<br />
newdata = FetchAndParse("user_data2");<br />
if( newdata.IsEmpty()==false && newdata.isError()==false )<br />
{<br />
ParseUserData();<br />
DataVersion_lustatus=newdata.DataVersion<br />
LoadTime=newdata.LoadTime<br />
DataVersion_userdata=newdata.DataVersion<br />
}<br />
else<br />
UI.DisplayError("Failed to update data"); // Display in the info panel an error message that the user will see for 10 seconds or so<br />
<br />
UI.HourglassAndSuspend(false); // Put a 'busy' hourglass in the UI, display a message in the info panel "Updating data" and suspend all UI stuff since this may take a moment<br />
}<br />
<br />
Sleep 1; // We know we just parsed user_data or lu_status, so sleep before looping<br />
goto START; // Loop again and start over</div>Andreimioshttp://wiki.mios.com/index.php/UI_NotesUI Notes2015-06-04T12:04:24Z<p>Andreimios: /* Tracking status changes */</p>
<hr />
<div>[[Category:Development]]<br />
Here is some general information about getting information to display in a user interface:<br />
<br />
== UPnP messaging system ==<br />
<br />
Vera uses UPnP for all the messaging, such as turning lights on and off. So Vera translates Z-Wave, Insteon, infrared codes, etc., into UPnP actions. If you have already implemented a UPnP stack and can send properly formated UPnP SOAP/XML requests, you can control everything using standard UPnP action invocation. If you did not, Vera provides a simple HTTP GET interface as well, which is discussed below.<br />
<br />
In a nutshell UPnP works like this: You have UPnP devices, which are things that can be controlled and can report their state, like a light switch. And you have UPnP Control Points, which are the things that let a user control UPnP devices, like a touch-screen web pad. The Control Point does this by a) reading the device and descriptions for the UPnP device to see what it can do, and b) invoking actions on the UPnP device (ie telling it to do something), and c) reading and setting variables for the device which describe the current state and/or configuration settings for the device.<br />
<br />
A UPnP device is defined in an XML document called a device description document. To see one, in Vera's setup UI, go to Devices, Luup plugins, Luup Files, and click 'view' file next to D_BinaryLight1.xml. Use Firefox since it has a built-in XML viewer. Notice the tag: <deviceType>urn:schemas-upnp-org:device:BinaryLight:1</deviceType>. This defines the type of device, namely an on/off light switch, which is what you use to know how to represent this device to a user. A device optionally implements one or more services. In this case the services: urn:upnp-org:serviceId:SwitchPower1, urn:micasaverde-com:serviceId:EnergyMetering1 and urn:micasaverde-com:serviceId:HaDevice1.<br />
<br />
A service is a collection of actions which a device implement and which you can invoke from a UPnP Control Point, as well as a collection of variables which always have a current value. The variables describe the current state of the device and/or configuration settings. View the file S_SwitchPower1.xml to see a service. For example, the device urn:schemas-upnp-org:device:BinaryLight:1 implements the service urn:upnp-org:serviceId:SwitchPower1, which has the action SetTarget, which is how you turn the light on and off. The action takes a single argument newTargetValue which can be 0 to turn the light off and 1 to turn it on. The service also has the variable Status which is 0 or 1 depending on whether the light is currently on or off.<br />
<br />
If you open the device description for a dimmable light D_DimmableLight1.xml you'll see that it implements the same service S_SwitchPower1.xml, since you can still turn it on and off, and it also implements the service urn:upnp-org:serviceId:Dimming1, which has an action to set the dim level (SetLoadLevelTarget).<br />
<br />
To test UPnP calls you can use the Intel Device Spy utility available [http://www.intel.com/cd/ids/developer/asmo-na/eng/downloads/upnp/tools/218896.htm?desturl=http://softwarecommunity.intel.com/isn/downloads/zips/IntelToolsForUPnPTechnology_v2.zip here]. It should pick up Vera, show you all the devices, like light switches, thermostats, etc., let you expand the services and see the actions and variables. Click an action, like SetTarget, to specify the arguments and click 'Invoke' to run the action, such as turning on and off the light.<br />
<br />
== JSON vs. XML ==<br />
<br />
The native UPnP protocol uses XML/SOAP. But there are also several times you will request data from Vera that has nothing to do with the UPnP spec. These will be done with data_request's as explained below, such as user_data, lu_status, etc. Internally Vera uses JSON as the native format, but Vera can convert to XML (details follow). In general when you want to view data in a human readable format, such as the device list, it's easiest to use the Firefox browser, and request Vera convert the data to XML. Firefox has a nice browser to display XML in human readable format. If you want to make the JSON data nicely formatted, you can use the web site jsonlint.com. In a UI application which will request data regularly from Vera we recommend retrieving everything in JSON format, not XML, because Vera's CPU is not that powerful and so continuous requests of data in XML format will cause a lot of CPU time to be devoted to converting JSON into XML.<br />
<br />
== Finding Vera on the local network ==<br />
<br />
You can find Vera by using the traditional UPnP discovery process, or you can retrieve this URL:<br>'''https://sta1.mios.com/locator_json.php?username=xxx''' where the username=xxx is optional, but, if specified, it will report all systems that mios.com user xxx can report whether local or remote, and without the username=xxx it only shows the Vera's on the user's local home network.<br />
<br />
Each Vera, when it boots up, reports its internal IP address to the central mios.com server, which tracks this along with the external IP address. '''locator.php''' shows all serial numbers and internal network IP addresses on the same external IP. For example, if '''https://sta1.mios.com/locator_json.php?username=xxx'''.<br />
<br />
== The HTTP interface ==<br />
<br />
Vera listens on port 3480. Vera responds to UPnP actions the normal way, or by making simple HTTP requests. For example, to turn on a light you can either send the UPnP action "SetTarget" to the device using the normal UPnP mechanism, or you can simply put this URL in your web browser, or with wget, or similar: <br />
<br />
http://[ipadress]:3480/data_request?id=lu_action&amp;output_format=xml&amp;DeviceNum=10&amp;serviceId=urn:upnp-org:serviceId:SwitchPower1&amp;action=SetTarget&amp;newTargetValue=1 <br />
<br />
That URL will return the same results of the action as using the normal UPnP architecture. The '''output_format=xml''' on the URL means the data returned should be in XML format. You can instead use '''output_format=json'''<br />
<br />
The service ID's, actions, and arguments are all defined by the UPnP forum. A list of ratified UPnP devices and services is available on the [http://www.upnp.org UPnP Forum]. Mi Casa Verde added its own custom devices and services when there was no existing UPnP standard. A list of these can be found in the [[Luup_UPNP_Files]] header files.<br />
<br />
== Getting the system configuration ==<br />
<br />
Either use the UPnP service/action:<br> '''urn:micasaverde-com:serviceId:HomeAutomationGateway1/GetUserData''' <br />
<br />
or use the built-in request: <br />
<br />
'''http://ipaddress:3480/data_request?id=user_data2&amp;output_format=json''' (or xml) <br />
<br />
This returns the system configuration file for Vera. It's assumed you understand the way Vera categorizes devices with Rooms, Devices, Scenes, etc. When creating a user interface for controlling Vera only, like on a mobile phone, most of the tags can be ignored, since usually you just need the list of rooms and devices.<br />
<br />
== Accessing Vera remotely through the mios server ==<br />
<br />
Native UPnP only works on a local area home network, and cannot be used over the Internet. The mios server provides a secure way to remotely access and control your Vera system using the HTTP interface without having to make any substantial changes to the UI. Everything you can do locally with Vera on port 3480, you can do remotely with mios using the exact same syntax. You only need to ask the user for his username and password and pass them on the URL to the remote access server, along with the serial number of the unit (ie like 12345). For example, the above user_data is the syntax for local access on a home network. To retrieve the same URL over the internet with mios use:<br />
<br />
https://fwd2.mios.com/demovera/myvera123/12345/data_request?id=lu_status&output_format=json (or use fwd1.mios.com)<br />
<br />
assuming demovera is the username and myvera123 is the password that the user chose setting up his mios.com account. Note that since the request is https, the username and password are encrypted because https encrypts the URL's as well as the contents of the page.<br />
<br />
== Building a control-only UI for Vera ==<br />
<br />
If you just want to control Vera, and not modify the configuration, such as with a cell phone interface or web pad, the flow might possibly work like this: <br />
<br />
'''1)''' For the initial setup, you need to ask whether the user wants to (a)&nbsp;access Vera remotely with the mios service, and if so, get the user's username/password; or (b) access Vera directly on the home network. You can use locator.php to show the Vera on the home network. You might want to do an auto-detect. For example, you could use locator.php to see if Vera exists locally, and if not, prompt the user for a mios username and password. You can use locator.php and pass the username to get the serial number and internal IP, and then automatically switch to direct access if locator.php (without the username) indicates that serial number is found on the local network. This would allow the user to automatically switch between local access with Wi-Fi (which is much faster of course) and remote access with mios and the mobile phone network. Or just ask for his mios username and show him all the Vera's he can control, either local or remote.<br />
<br />
'''2)''' Once the connection is established, retrieve the list of rooms, scenes, and devices from Vera (see '''user_data''' below). You can cache this data locally so you don't need to retrieve it and parse it over and over.<br />
<br />
'''3)''' Present the user with the rooms, scenes, devices. In Vera's UI's we show first the rooms and then let the user pick a device or scene in the room. However this data could be presented graphically, such as on a floorplan. Your UI can have Vera store extra tags and data in the configuration database (ie user_data) to store things like coordinates for icons, outlines or rooms and so on.<br />
<br />
'''4)''' If the user picks a scene you can run the scene with the following URL, passing the scene number as '''x''', and it will return an OK if it went okay: <br />
<br />
http://127.0.0.1:3480/data_request?id=lu_action&amp;serviceId=urn:micasaverde-com:serviceId:HomeAutomationGateway1&amp;action=RunScene&amp;SceneNum=x <br />
<br />
'''5)''' If the user picks a device, you use the category which is contained in the user_data to determine what type of controls to present the user. (See [[Luup UPNP Files]] for a list of the categories.) When the user chooses an action, you can send it like this: <br />
<br />
http://ipadress:3480/data_request?id=lu_action&amp;output_format=xml&amp;DeviceNum=10&amp;serviceId=urn:upnp-org:serviceId:SwitchPower1&amp;action=SetTarget&amp;newTargetValue=1 <br />
<br />
For a list of common actions and device types see: [[Luup CP Mandatory Types]] <br />
<br />
Some actions return immediately with an 'OK'. Other jobs may take time to complete and are processed asynchronously. For these asynchronous jobs you will get a job ID back. There are several ways to present this to the user. One possibility is to do what Vera does in the UI, namely to use '''lu_status '''(explained next) to find all active jobs and to put a 'job' icon next to each device to indicate the progress of the job. In this way the user isn't tracking a particular job ''per se'', but just has visual feedback that a device is busy, and if the job icon(s) turn green, that everything went through okay. You could instead track the action individually using the job number that is returned, or use some other method, like making the icon for the device appear animated while it's busy, and turn green or red if the last command succeeded or failed.<br />
<br />
'''6)''' Periodically poll the system with '''lu_status''' (explained below), like this: <br />
<br />
http://ipaddress:3480/data_request?id=lu_status2&amp;output_format=json <br />
<br />
That returns the current values of the UPnP variables, which you can use to show the user current status. For example, if the variable Status is 1 for a switch, you can show the 'on' button in a selected state, while 0 shows it in an 'off' state. '''lu_status''' also shows any active jobs for a device.<br />
<br />
==user_data==<br />
NOTE: On UI3 builds, user_data2 and user_data are the same, and so is lu_status2 and lu_status. However, on UI2 builds, user_data and lu_status have been deprecated, and you should user_data2 and lu_status2. Therefore, it's best to simply always use user_data2 instead of user_data, and lu_status2 instead of lu_status.<br />
<br />
The user_data is the main configuration file that Vera uses to store all the rooms, devices, scenes, timers, events, users, and any other data about the system. You should request the user_data to get whatever data you need to present to the user, at a minimum, for example, you'll need the list of devices, their descriptions, and the categories (light switch, thermostat, etc.). You'll also want the list of scenes to present the user. To fetch the current user_data from Vera use the user_data2 request, like this:<br />
<br />
Returns JSON (preferred native format):<br />
<br />
http://[ip address]:3480/data_request?id=user_data2<br />
<br />
Returns XML:<br />
<br />
http://[ip address]:3480/data_request?id=user_data2&output_format=xml<br />
<br />
You can also add a 'DataVersion=TimeStamp' parameter to the URL. It the data has changed since the TimeStamp, all the data is returned. If the data has not changed since the TimeStamp, Vera will return a page with the text 'NO_CHANGES':<br />
<br />
http://[ip address]:3480/data_request?id=user_data2&DataVersion=315587159<br />
<br />
The user_data contains the state for all the devices. For example this indicates that the device id #17, called "Switch" is turned off (ie service SwitchPower1, variable Status is 0)<br />
<br />
{<br />
"devices": [<br />
{<br />
"id": 17,<br />
"category": 3,<br />
"room": 1,<br />
"name": "Switch",<br />
"ip": "",<br />
"mac": "",<br />
{<br />
"service": "urn:upnp-org:serviceId:SwitchPower1",<br />
"variable": "Status",<br />
"value": "0" <br />
}<br />
}<br />
]<br />
}<br />
<br />
==lu_status==<br />
The UPnP variables describe the state of the devices according to the UPnP specs. When the variables change that information needs to be shown to the user, eg change a Switch icon from off to on. If you are interfacing with Vera using the UPnP stack, you can subscribe to the device's events to receive notifications automatically when a device's state changes. However if you're using the web interface you will need to poll using lu_status request.<br />
<br />
Call lu_status request like so:<br />
<br />
:http://[ip address]:3480/data_request?id=lu_status2<br />
<br />
:http://[ip address]:3480/data_request?id=lu_status2&output_format=xml<br />
<br />
:http://[ip address]:3480/data_request?id=lu_status2&DataVersion=315587159<br />
<br />
<br />
The returned document contains four sets of information, which constantly change to reflect the current status:<br />
* root attributes including DataVersion, which is the status timestamp, plus other attributes such as LoadTime <br />
*the state of the system initialization, such as initialization of the plugin modules.<br />
*a '''subset''' of the user_data that represents the current state of the device's UPnP variables<br />
*the status of any active or recent '''jobs''', such as if a light was successfully turned off<br />
<br />
===Tracking status changes===<br />
If you call lu_status without passing a DataVersion on the URL, you will get the current value of all the UPnP variables for a device. Note that most of the UPnP variables do not ever change. For example, with a light switch, only the variable "SwitchPower:Status" changes, as the switch is turned off and on. There are many other variables, like "Capabilities" which are simply configuration data or settings the user modified. If you pass &DataVersion=1 on the URL, you will only see the UPnP variables which have changed since the Luup engine started. So, if you parse the initial UPnP variables when you first call user_data, you can call lu_status with DataVersion=1. Once you call lu_status the first time, store the DataVersion and on subsequent calls pass it on the URL and you will only get the UPnP variables which have changed since that last DataVersion. Regardless, you will also get the current state of jobs and system initialization.<br />
<br />
On subsequent calls to lu_status, you should also pass back in the LoadTime which you received on the prior call.<br />
<br />
===Controlling the poll timing===<br />
You can also pass in a Timeout value, which means the call will block for up to that many seconds if nothing has changed, and will return immediately when something does. This way you can have infrequent polling, say every 60 seconds by putting a Timeout value of 60, but your UI will be immediately responsive since, when something changes, it returns immediately. You can also add a MinimumDelay, which means that the call will wait for at least that many milliseconds. This is advisable so that in the event there are lots of continuous changes, such as a scene turning off many lights, you won't have lu_status2 calls returning non-stop consuming all the resources on both the Vera and the UI.<br />
<br />
===Startup status===<br />
The section with the initialization tasks is shown in the startup tag as shown:<br />
<br />
"startup": {<br />
"tasks": [<br />
{<br />
"id": 0,<br />
"status": 2,<br />
"type": "ZWave",<br />
"comments": "No Z-Wave" <br />
},<br />
<br />
The startup tasks begin whenever the Luup engine is reset, such as after the user makes a configuration change. Ever plugin and module in the Luup engine does a startup sequence. The id is not really important. The status numbers are the same as for jobs, so 2 means the module failed to startup. The 'Type' is what you can use to key off of to know which module is being reported, such as "ZWave", and comments are just notes indicating the current state. For example, "No Z-Wave" means there's no Z-Wave dongle connected.<br />
<br />
Once all the plugins have been initialized successfully the startup section will disappear completely from lu_status.<br />
<br />
Note that lu_status2 also returns UserData_DataVersion, which is the dataversion from user_data. That way you don't need to poll user_data in parallel. Simply retrieve the user_data one time at startup, then poll lu_status, and, if UserData_DataVersion is different from the previous user_data you retrieved, then download user_data again.<br />
<br />
Some notes on building a full replacement, including configuration, are available here [[UI_Notes_Replacement]], however the syntax is not up to date with the Luup architecture.<br />
<br />
===Job status===<br />
The jobs for a device will look like this:<br />
<br />
"devices": [<br />
{<br />
"id": 1,<br />
"Jobs": [<br />
{<br />
"id": "1",<br />
"name": "job#1 :getnodes (0x00D068F0) P:10 S:4",<br />
"icon": "",<br />
"comments": "",<br />
"status": "4" <br />
} <br />
] <br />
},<br />
<br />
The id is the job id number. When you run an action, like turning on a light, if it happens asynchronously, you'll get a job id number. All pending jobs for a device are shown by their id number. The name is just an internal name for the job. Icon is an optional keyword to indicate what sort of icon should be shown to the user. For example, 'getnodes' has no icon, meaning this type of job is generally not of interest to a user. If the icon was 'ON' or 'OFF' that would mean this job is busy turning on or off a light. Comments is notes about the job, if any. This may be shown to a user in a tool tip or similar, but is generally more technical than users would care to know. The status indicates the current state of the job, as shown:<br />
<br />
*job_None=-1, // no icon<br />
*job_WaitingToStart=0, // gray icon<br />
*job_InProgress=1, // blue icon<br />
*job_Error=2, // red icon<br />
*job_Aborted=3, // red icon<br />
*job_Done=4, // green icon<br />
*job_WaitingForCallback=5 // blue icon - Special case used in certain derived classes<br />
<br />
If the status is 0, this means the job is queued but hasn't started. If it's 1 or 5 the job is being executed right now. Generally both 1 and 5 are presented to the user the same way as a 'busy', although technically 1 means Vera is actively talking to the device, and 5 means Vera is waiting for a reply from the device. Status codes 2, 3 and 4 mean the job has finished. 4 means the job went ok, and both 2 and 3 mean it failed. Technically 3 means the job was aborted by another job or an external process, like a user cancelling it, while 2 means it failed due to a problem talking to the device. In both cases this is usually presented the user the same way, as a failure.<br />
<br />
== Categories and device types ==<br />
<br />
The values used in user_data to determine the types of devices are in [[Luup_UPNP_Files]]. In general you can use the category instead of the devicetype since it's an integer and is thus faster to compare:<br />
<br />
== pseudo-code for a UI ==<br />
<br />
Here is some pseudo code to show how the polling mechanism should be properly implemented. The parsing code is, of course, unique to your UI, so placeholder function names are shown here, like FetchAndParse. This shows the flow for handling the polling so you know you get the changes reported correctly.<br />
<br />
variable int DataVersion_lustatus=0<br />
variable int LoadTime=0<br />
variable int DataVersion_userdata=0<br />
<br />
:START<br />
variable boolean FetchUserData=false;<br />
if( DataVersion_userdata==0 ) // If we're on the first loop and haven't retrieved user_data, do it and don't do an lu_status<br />
FetchUserData=true;<br />
else<br />
{<br />
while(true)<br />
{<br />
newdata = FetchAndParse("lu_status2&DataVersion="+DataVersion_lustatus+"&LoadTime="+LoadTime);<br />
if( newdata.IsEmpty()==false && newdata.isError()==false )<br />
break; // If we got data, continue on and process it<br />
else<br />
Sleep 1; // If we didn't get anything, or if lu_status failed, just sleep 1 second and stay in the loop to try again<br />
} // End of while loop<br />
<br />
if( newdata.UserData_DataVersion!=DataVersion_userdata )<br />
{<br />
FetchUserData=true;<br />
}<br />
else // Only Parse if userdata is the same, otherwise we're going to reload user_data<br />
{<br />
ParseLuStatus(); // This won't run if user_data has changed<br />
DataVersion_lustatus=newdata.DataVersion<br />
}<br />
} // end of else loop<br />
<br />
if( FetchUserData==true )<br />
{<br />
UI.HourglassAndSuspend(true); // Put a 'busy' hourglass in the UI, display a message in the info panel "Updating data" and suspend all UI stuff since this may take a moment<br />
newdata = FetchAndParse("user_data2");<br />
if( newdata.IsEmpty()==false && newdata.isError()==false )<br />
{<br />
ParseUserData();<br />
DataVersion_lustatus=newdata.DataVersion<br />
LoadTime=newdata.LoadTime<br />
DataVersion_userdata=newdata.DataVersion<br />
}<br />
else<br />
UI.DisplayError("Failed to update data"); // Display in the info panel an error message that the user will see for 10 seconds or so<br />
<br />
UI.HourglassAndSuspend(false); // Put a 'busy' hourglass in the UI, display a message in the info panel "Updating data" and suspend all UI stuff since this may take a moment<br />
}<br />
<br />
Sleep 1; // We know we just parsed user_data or lu_status, so sleep before looping<br />
goto START; // Loop again and start over</div>Andreimioshttp://wiki.mios.com/index.php/File:MyDevice5.jpgFile:MyDevice5.jpg2015-03-10T10:33:56Z<p>Andreimios: </p>
<hr />
<div></div>Andreimioshttp://wiki.mios.com/index.php/File:MyDevice4.jpgFile:MyDevice4.jpg2015-03-10T10:33:43Z<p>Andreimios: </p>
<hr />
<div></div>Andreimioshttp://wiki.mios.com/index.php/File:MyDevice3.jpgFile:MyDevice3.jpg2015-03-10T10:33:25Z<p>Andreimios: </p>
<hr />
<div></div>Andreimioshttp://wiki.mios.com/index.php/File:MyDevice2.jpgFile:MyDevice2.jpg2015-03-10T10:31:00Z<p>Andreimios: </p>
<hr />
<div></div>Andreimioshttp://wiki.mios.com/index.php/Luup_plugins:_Static_JSON_fileLuup plugins: Static JSON file2015-03-10T10:30:20Z<p>Andreimios: </p>
<hr />
<div>[[Category:Development]]<br />
<br />
Starting in UI4, Luup plugins can specify a ''static JSON'' file. This file describes how the plugin appears in the web interface.<br />
<br />
=What the static JSON file controls=<br />
<br />
* The icon used by the plugin in the dashboard.<br />
* The text that displays in the one-to-two-row status message in the dashboard.<br />
* Whether the icon changes depending on the value of a variable in the device (for example, a binary light's icon changes from lit to unlit).<br />
* The tabs that appear in the device's detail dialog (when you click the wrench/spanner).<br />
* The content of these tabs.<br />
* The triggers or events that are available for the device in the "Triggers" or "Events" tag of a scene.<br />
<br />
=Referencing the static JSON file from the Device XML file=<br />
<br />
The device XML file (customarly '''D_PluginName.xml''') contains a reference to the static JSON file, in the '''staticJson''' element. Place the element as a child of the '''device''' element:<br />
<br />
<pre><nowiki><br />
<?xml version="1.0"?><br />
<root xmlns="urn:schemas-upnp-org:device-1-0"><br />
<specVersion><!-- ... --></specVersion><br />
<device><br />
<deviceType>urn:schemas-futzle-com:device:holidayvirtualswitch:1</deviceType><br />
<staticJson>D_HolidayVirtualSwitch1.json</staticJson><br />
<!-- ... --><br />
</nowiki></pre><br />
<br />
Capitalization is important, as with all XML.<br />
<br />
The static JSON file is customarily called '''D_PluginName.json'''.<br />
<br />
=The static JSON file=<br />
<br />
The static JSON file is a single JSON object (associative array).<br />
<br />
==Root keys==<br />
<br />
These keys have been seen at the top level in static JSON files in the wild:<br />
<br />
; flashicon<br />
: The device's icon, as a string. Despite the name, the icon is no longer related to Adobe Flash in UI4 or UI5. See [[Luup plugin icons]].<br />
; imgIconBody<br />
: Ignored in UI5.<br />
; imgIconDimmable<br />
: Ignored in UI5.<br />
; imgIconTurnable<br />
: Ignored in UI5.<br />
; imgIconMin<br />
: Ignored in UI5.<br />
; imgIconMax<br />
: Ignored in UI5.<br />
; halloIconsDir<br />
: Ignored in UI5.<br />
; inScene<br />
: When included and set equal to one, it enables any buttons, etc located on the "dashboard box", so they can be selected in the scene editor for use in scenes, rather than being grayed out.<br />
; DisplayStatus<br />
: A JSON object (associative array). For devices where the icon changes based on a variable's value, describes which variable, and the range of values that produce different icon images. See [[Luup plugin icons]].<br />
; state_icons<br />
: A JSON array. For devices where the icon changes based on a variable's value, describes which icon files exist. See [[Luup plugin icons]]. Used only in firmware 1.5.401 or later.<br />
; doc_url<br />
: A JSON object (associative array). In UI5, the only item in this object which is used is doc_page. It controls which page in docs5.mios.com is brought up when you click on the help ('''?''') icon in the device control panel.<br />
; Tabs<br />
: A JSON array. Describes the tabs in the detail dialog, and what subset of the first tab appears in the dashboard. See [[Luup plugin tabs]].<br />
; ToggleButton<br />
: ?????<br />
; DeviceType<br />
: A JSON string. Must match the '''deviceType''' element in the corresponding device XML ('''D_PluginName.xml''') file.<br />
; eventList<br />
: A JSON object (associative array). Describes the events that this plugin can produce. Events are triggers that can fire off actions in scenes. This key is required for UI4, and obsoleted in UI5. For UI5, use the eventList2 tag, which has a different format. For compatibility with both UI4 and UI5 you need the same information in both keys. See [[UI4 UI5 Migration]] for more information.<br />
; eventList2<br />
: see eventList, above.<br />
; sceneList<br />
: A JSON object (associative array). Describes the actions that this plugin can perform (for instance, as the action in a scene). This key is not required and is ignored in UI5, however it is needed for UI4 compatibility. See [[UI4 UI5 Migration]] for more information about its format.<br />
<br />
= UI7 Updates =<br />
<br />
* '''default_icon'''<br />
: replace the old "flashicon" from UI5. See [[Luup plugin icons]]<br />
* '''state_icons'''<br />
: state_icons mechanism has changed in UI7. Please see [[Luup plugin icons]]<br />
* '''TopNavigationTab''' = '''top_navigation_tab'''<br />
<br />
In device cpanel, tabs can be placed either in the top part or in the bottom. By default they are put in the bottom part. You can mark your tabs with a special flag so that they can be placed in top navigation bar of the cpanel.<br />
If two or more tabs are marked with ‘'''TabType=”flash”'''’, only the first one found will be placed in top navigation bar. If you want all of them to be placed there, you have to add ‘'''top_navigation_tab'''’ to each one.<br />
Let’s assume you have a plugin named ‘MyPlugin’ and you want to put a button in the top navigation bar, which, when clicked, will display a message in the cpanel.<br />
<br />
* Add the following lines to the .json device file (D_MyPlugin.json), in the Tabs section:<br />
<source lang="javascript"><br />
{<br />
"Label": {<br />
"lang_tag": "About",<br />
"text": "About"<br />
},<br />
"TopNavigationTab": "1",<br />
"Position": "4",<br />
"TabType": "javascript",<br />
"ScriptName": "J_MyPlugin.js",<br />
"Function": "MyPlugin.about"<br />
}<br />
</source><br />
<br />
Notice the property ‘'''TopNavigationTab'''’ set to the value of ‘1’. This is the line that specifies where to place the tab in cpanel. If you set a value different than 1, the tab will be placed in the bottom part of the cpanel, so always use ‘1’ if you want the tab in the top bar. You can also use ‘'''top_navigation_tab'''’.<br />
<br />
* Add the following lines of code to your .js file (J_MyPlugin.js):<br />
<br />
<source lang="javascript"><br />
var MyPlugin = (function(api){<br />
return {<br />
about: function() {<br />
try { <br />
var html = '<div>This is all about me !</div>';<br />
api.setCpanelContent(html);<br />
} catch (e) {<br />
Utils.logError('Error in MyPlugin.about(): ' + e);<br />
}<br />
}<br />
};<br />
})(api);<br />
</source><br />
<br />
* Perform a lu reload, enter device cpanel and click on ‘About’ button (which is in the top navigation bar of the cpanel) and the result will be something like this:<br />
<br />
[[File:TopNavigationTab.jpg|image|center|caption]]<br />
<br />
<br />
== Position device controls for generic devices ==<br />
<br />
In UI7, devices are split into two categories: specific and generic. Specific devices are those which have a predefined design (like binary light, thermostat, dimmable etc.). Generic devices are those created by plugin developers.<br />
<br />
=== Positioning controls in ‘device view’ ===<br />
<br />
The controls for generic devices are placed inside the device container based on the order in which are found in device .json file and so, each control is drawn to the right of the previous one. If a control doesn’t fit in the remaining space it will be drawn on the following line. This rule will guarantee that the look of a device will be the same on the Web, but also on the mobile apps.<br />
<br />
In order to achieve this, but also to maintain backward compatibility with UI5, the developer can add new properties to the device .json, but doesn’t have to change the existing ones.<br />
<br />
In the WEB UI, each control is contained in a div element which is positioned using float: left CSS property.<br />
<br />
The size of the controls can be altered using properties like ‘HorizontalMultiplier’ which multiplies the default width of a control with a given float number.<br />
<br />
To force a control to be positioned on the next line, a special device control was created: ‘line_break’.<br />
<br />
To insert a space between two controls, the developer can use the newly created device control: ‘spacer’, which also accepts ‘HorizontalMultiplier’ property.<br />
<br />
=== Tutorial ===<br />
<br />
We will start with a device that contains no controls.<br />
<br />
* First, we need a SceneGroup with id 1 and a ControlGroup with id 1 which belongs to the previous added scene group (this is the same as in UI5)<br />
<br />
<source lang="javascript"><br />
"SceneGroup": [<br />
{<br />
"id": "1",<br />
"top": "1",<br />
"left": "0",<br />
"x": "2",<br />
"y": "3"<br />
}<br />
],<br />
"ControlGroup": [<br />
{<br />
"id": "1",<br />
"isSingle": "1",<br />
"scenegroup": "1"<br />
}<br />
]<br />
</source><br />
<br />
* Then, add a control of type ‘button’ with a label: ‘My First Button’. Create it using the same definition as in UI5. Be sure to set the ControlGroup of the button to be equal to 1:<br />
<br />
<source lang="javascript"><br />
{<br />
"ControlGroup": 1,<br />
"ControlType": "button",<br />
"ControlCode": "my_button",<br />
"top": 0,<br />
"left": 0,<br />
"Label": {<br />
"lang_tag": "my_first_button",<br />
"text": "My First Button"<br />
},<br />
"Display": {<br />
"Service": "urn:micasaverde-com:serviceId:MyPlugin1",<br />
"Variable": "Status",<br />
"Value": "1",<br />
"Top": 200,<br />
"Left": 50,<br />
"Width": 100,<br />
"Height": 20<br />
},<br />
"Command": {<br />
"Service": "urn:micasaverde-com:serviceId:MyPlugin1",<br />
"Action": "SetStatus",<br />
"Parameters": [<br />
{<br />
"Name": "Status",<br />
"Value": "1"<br />
}<br />
]<br />
}<br />
},<br />
</source><br />
<br />
* By now, your device will look something like this:<br />
<br />
[[File:MyDevice1.jpg|image|center|caption]]<br />
<br />
* Notice that the text doesn’t fit properly inside the button. Add "HorizontalMultiplier": "2" property to your control definition. This will set the width of the button to double the default size. By now, your device will look like this:<br />
<br />
[[File:MyDevice2.jpg|image|center|caption]]<br />
<br />
* Add 6 more buttons using the same template as above, but don’t set the “HorizontalMultiplier” property. Use labels: ‘Button 1’, ‘Button 2’, … ‘Button 6’. It will look like this:<br />
<br />
[[File:MyDevice3.jpg|image|center|caption]]<br />
<br />
* Notice that the latest 6 buttons will be added to the right of the previously added ones; if the button doesn’t fit in the remaining space it will be placed on the next line<br />
<br />
* We decide to move buttons 1-3 on a separate line and buttons 4-6 on another line; to do so, add a control of type ‘line_break’ at the end of ‘My First Button’ and at the end of ‘Button 3’. The syntax is the following:<br />
<br />
<source lang="javascript"><br />
{<br />
"ControlGroup": 1,<br />
"ControlType": "line_break"<br />
}<br />
</source><br />
<br />
* And the result is like this:<br />
<br />
[[File:MyDevice4.jpg|image|center|caption]]<br />
<br />
* If you want some space between the buttons you can use ‘spacer’, like this:<br />
<br />
<source lang="javascript"><br />
{<br />
"ControlGroup": 1,<br />
"ControlType": "spacer",<br />
"HorizontalMultiplier": "0.7"<br />
}<br />
</source><br />
<br />
* The result:<br />
<br />
[[File:MyDevice5.jpg|image|center|caption]]<br />
<br />
* Here is the full definition of the Control array (highlighted with blue you can see UI7 specific properties):<br />
<br />
<source lang="javascript"><br />
{<br />
"HorizontalMultiplier": "2",<br />
"ControlGroup": 1,<br />
"ControlType": "button",<br />
"ControlCode": "my_button",<br />
"top": 0,<br />
"left": 0,<br />
"Label": {<br />
"lang_tag": "my_first_button",<br />
"text": "My First Button"<br />
},<br />
"Display": {<br />
"Service": "urn:micasaverde-com:serviceId:MyPlugin1",<br />
"Variable": "Status",<br />
"Value": "1",<br />
"Top": 200,<br />
"Left": 50,<br />
"Width": 100,<br />
"Height": 20<br />
},<br />
"Command": {<br />
"Service": "urn:micasaverde-com:serviceId:MyPlugin1",<br />
"Action": "SetStatus",<br />
"Parameters": [<br />
{<br />
"Name": "Status",<br />
"Value": "1"<br />
}<br />
]<br />
}<br />
},<br />
{<br />
"ControlGroup": 1,<br />
"ControlType": "line_break"<br />
},<br />
{<br />
"ControlGroup": 1,<br />
"ControlType": "button",<br />
"ControlCode": "button_1",<br />
"top": 0,<br />
"left": 0,<br />
"Label": {<br />
"lang_tag": "button1",<br />
"text": "Button1"<br />
},<br />
"Display": {<br />
"Service": "urn:micasaverde-com:serviceId:MyPlugin1",<br />
"Variable": "Status",<br />
"Value": "21",<br />
"Top": 200,<br />
"Left": 50,<br />
"Width": 100,<br />
"Height": 20<br />
},<br />
"Command": {<br />
"Service": "urn:micasaverde-com:serviceId:MyPlugin1",<br />
"Action": "SetStatus",<br />
"Parameters": [<br />
{<br />
"Name": "Status",<br />
"Value": "21"<br />
}<br />
]<br />
}<br />
},<br />
{<br />
"ControlGroup": 1,<br />
"ControlType": "spacer",<br />
"HorizontalMultiplier": "0.7"<br />
},<br />
{<br />
"ControlGroup": 1,<br />
"ControlType": "button",<br />
"ControlCode": "button_2",<br />
"top": 0,<br />
"left": 0,<br />
"Label": {<br />
"lang_tag": "button2",<br />
"text": "Button2"<br />
},<br />
"Display": {<br />
"Service": "urn:micasaverde-com:serviceId:MyPlugin1",<br />
"Variable": "Status",<br />
"Value": "22",<br />
"Top": 200,<br />
"Left": 50,<br />
"Width": 100,<br />
"Height": 20<br />
},<br />
"Command": {<br />
"Service": "urn:micasaverde-com:serviceId:MyPlugin1",<br />
"Action": "SetStatus",<br />
"Parameters": [<br />
{<br />
"Name": "Status",<br />
"Value": "22"<br />
}<br />
]<br />
}<br />
},<br />
{<br />
"ControlGroup": 1,<br />
"ControlType": "spacer",<br />
"HorizontalMultiplier": "0.7"<br />
},<br />
{<br />
"ControlGroup": 1,<br />
"ControlType": "button",<br />
"ControlCode": "button_3",<br />
"top": 0,<br />
"left": 0,<br />
"Label": {<br />
"lang_tag": "button3",<br />
"text": "Button3"<br />
},<br />
"Display": {<br />
"Service": "urn:micasaverde-com:serviceId:MyPlugin1",<br />
"Variable": "Status",<br />
"Value": "23",<br />
"Top": 200,<br />
"Left": 50,<br />
"Width": 100,<br />
"Height": 20<br />
},<br />
"Command": {<br />
"Service": "urn:micasaverde-com:serviceId:MyPlugin1",<br />
"Action": "SetStatus",<br />
"Parameters": [<br />
{<br />
"Name": "Status",<br />
"Value": "23"<br />
}<br />
]<br />
}<br />
},<br />
{<br />
"ControlGroup": 1,<br />
"ControlType": "line_break"<br />
},<br />
{<br />
"ControlGroup": 1,<br />
"ControlType": "button",<br />
"ControlCode": "button_4",<br />
"top": 0,<br />
"left": 0,<br />
"Label": {<br />
"lang_tag": "button4",<br />
"text": "Button4"<br />
},<br />
"Display": {<br />
"Service": "urn:micasaverde-com:serviceId:MyPlugin1",<br />
"Variable": "Status",<br />
"Value": "24",<br />
"Top": 200,<br />
"Left": 50,<br />
"Width": 100,<br />
"Height": 20<br />
},<br />
"Command": {<br />
"Service": "urn:micasaverde-com:serviceId:MyPlugin1",<br />
"Action": "SetStatus",<br />
"Parameters": [<br />
{<br />
"Name": "Status",<br />
"Value": "24"<br />
}<br />
]<br />
}<br />
},<br />
{<br />
"ControlGroup": 1,<br />
"ControlType": "spacer",<br />
"HorizontalMultiplier": "0.7"<br />
},<br />
{<br />
"ControlGroup": 1,<br />
"ControlType": "button",<br />
"ControlCode": "button_5",<br />
"top": 0,<br />
"left": 0,<br />
"Label": {<br />
"lang_tag": "button5",<br />
"text": "Button5"<br />
},<br />
"Display": {<br />
"Service": "urn:micasaverde-com:serviceId:MyPlugin1",<br />
"Variable": "Status",<br />
"Value": "25",<br />
"Top": 200,<br />
"Left": 50,<br />
"Width": 100,<br />
"Height": 20<br />
},<br />
"Command": {<br />
"Service": "urn:micasaverde-com:serviceId:MyPlugin1",<br />
"Action": "SetStatus",<br />
"Parameters": [<br />
{<br />
"Name": "Status",<br />
"Value": "25"<br />
}<br />
]<br />
}<br />
},<br />
{<br />
"ControlGroup": 1,<br />
"ControlType": "spacer",<br />
"HorizontalMultiplier": "0.7"<br />
},<br />
{<br />
"ControlGroup": 1,<br />
"ControlType": "button",<br />
"ControlCode": "button_6",<br />
"top": 0,<br />
"left": 0,<br />
"Label": {<br />
"lang_tag": "button6",<br />
"text": "Button6"<br />
},<br />
"Display": {<br />
"Service": "urn:micasaverde-com:serviceId:MyPlugin1",<br />
"Variable": "Status",<br />
"Value": "26",<br />
"Top": 200,<br />
"Left": 50,<br />
"Width": 100,<br />
"Height": 20<br />
},<br />
"Command": {<br />
"Service": "urn:micasaverde-com:serviceId:MyPlugin1",<br />
"Action": "SetStatus",<br />
"Parameters": [<br />
{<br />
"Name": "Status",<br />
"Value": "26"<br />
}<br />
]<br />
}<br />
}<br />
</source></div>Andreimioshttp://wiki.mios.com/index.php/File:MyDevice1.jpgFile:MyDevice1.jpg2015-03-10T10:29:45Z<p>Andreimios: </p>
<hr />
<div></div>Andreimioshttp://wiki.mios.com/index.php/JavaScript_APIJavaScript API2015-02-03T15:54:12Z<p>Andreimios: </p>
<hr />
<div>== Usage ==<br />
<pre>"Tabs": [<br />
{<br />
"Label": {<br />
"lang_tag": "users",<br />
"text": "Users" <br />
},<br />
"Position": "0",<br />
"TabType": "javascript",<br />
"ScriptName": "I_HomeCare.js",<br />
"Function": "showUsers"<br />
}, </pre> <br />
To generate a tab using your JavaScript functions you need to specify this by setting ''TabType'' to '''''javascript'''''. Then, you need to specify the script file's name and which function in this file will be used to draw the tab's content. That function will have one argument, which is the device number.<br> <br />
<br />
==== &lt;functionName&gt; (deviceNumber) ====<br />
<br />
This is the tab rendering function. The [[#set_panel_html_.28html.29 | set_panel_html]] function must be called at the end.<br> <br />
<br />
'''Input:''' <br />
<br />
*deviceNumber (number)<br><br />
<br />
'''Output:''' <br />
<br />
*nothing<br />
<br />
<br><br />
<br />
== Variables ==<br />
<br />
==== jsonp.ud ====<br />
<br />
This is the user data. <br />
<br />
*'''Type''': object <br />
*'''Members''': <br />
**devices (array) <br />
**scenes (array) <br />
**users (array) <br />
**rooms (array) <br />
**eventList (array) <br />
**etc.<br />
<br />
<br> <br />
<br />
==== jsonp.ud.devices ====<br />
<br />
*'''Type''': array <br />
*'''Members''': <br />
**id (number) <br />
**device_type (string) <br />
**room (number) <br />
**name (string) <br />
**category_num (number) <br />
**etc.<br />
<br />
<br> <br />
<br />
==== jsonp.ud.scenes ====<br />
<br />
*'''Type''': array <br />
*'''Members''': <br />
**id (number) <br />
**name (string) <br />
**room (number) <br />
**Timer_ids (array) <br />
**Timer (object) <br />
**etc.<br />
<br />
<br> <br />
<br />
== Functions ==<br />
<br />
==== get_device_state (deviceId, serviceId, variable, dynamic) ====<br />
<br />
'''Input:''' <br />
<br />
*deviceId (number)<br />
*serviceId (string)<br />
*variable (string)<br />
*dynamic (number): if '''1''', the variable's value is taken from ''lu_status'', else, the variable's value is taken from ''user_data''. ''user_data'' is read at Luup startup, so for variables that change their value frequently (like Watts, Temperature, etc.) ''dynamic'' should be '''1'''.<br />
<br />
'''Output:''' <br />
<br />
*variable value (string or ''undefined'')<br />
<br />
<br><br />
<br />
==== set_device_state (deviceId, serviceId, variable, value, dynamic) ====<br />
<br />
'''Input:''' <br />
<br />
*deviceId (number)<br />
*serviceId (string)<br />
*variable (string)<br />
*value (string)<br />
*dynamic (number): if '''1''', the variable's value is saved to ''lu_status'' (the value is lost after Luup is restarted), else, the variable's value is saved to a copy of ''user_data''; the real user_data is updated when LuaUPnP is restarted.<br />
<br />
'''Output:''' <br />
<br />
*''true'' if the operation succeeded, ''false'' otherwise<br />
<br />
<br><br />
<br />
==== _console (str) ====<br />
<br />
'''Input:''' <br />
<br />
*str (string): text to be written in the console. You need to have FireBug installed in order to have a console.<br />
<br />
'''Output:''' <br />
<br />
*nothing<br />
<br />
<br><br />
<br />
==== set_panel_html (html) ====<br />
<br />
Used in the tab rendering functions. <br />
<br />
'''Input:''' <br />
<br />
*html (string): The html to be used for generating the tab content.<br />
<br />
'''Output:''' <br />
<br />
*nothing<br />
<br />
[[Category:Development]]<br />
<br />
= JavaScript API for UI7 =<br />
<br />
== Introduction ==<br />
<br />
One of the new features of UI7 is the Javascript API for writing plugins. This is a free programming interface which is robust, well documented and comes with a guarantee that it will be compatible with the following UI releases.<br />
<br />
'''''What is this “API” ?'''''<br />
<br />
Simply said: it is a layer between the UI and the plugin developer. This way, the developer can use the features available in the UI by interacting only with the API. By using the new features available in the API, the overall user experience can be visibly improved.<br />
<br />
'''''How does it work ?'''''<br />
<br />
The API comes in the form of a library which exposes to the developer the objects and methods/functions needed to implement functionality in their plugins.<br />
<br />
'''''How is this different from the previous way of writing plugins ?'''''<br />
<br />
The developers were writing Javascript code and they had full access to the core of the application. There were a couple of objects and functions written by the UI team which were easing the work for the developer.<br />
By using the new API, the developer can write code without interfering with the core of the application.<br />
<br />
'''''What is new ?'''''<br />
<br />
* The developer can write the plugin without interfering with any other code except the API. This means there are a great bundle of methods like setters and getters which help writing good code.<br />
* UI team can make any changes to the core of the application, but as long as the API stays the same, the plugins will work. This way, the application can be improved and the developer won’t have to fix the code in order for it to work. New versions of the UI can be launched and the plugins will be compatible.<br />
* Event handling - the application will notify the plugin (via the API) about the events that happen inside. Consider, for example, the addition of a new device to the unit. The developer will know, by simply listening to an event, that a device was added and so, (s)he will write the code in such a way that it will take into account the event. The user experience will be greatly improved.<br />
* Asynchronous getters and setters - because most of the actions that happen inside the UI is asynchronous, so are the API’s method written. Most of them have a signature like this: function getXXX(obj, onSuccess, onFailure), where ‘onSuccess’ and ‘onFailure’ are callback functions which are called based on the result of the call.<br />
* No more global variables to manipulate. Everything is handled through getters/setters via API.<br />
* An API reference documentation: every method and its parameters is carefully documented so that the developer would know what the function does, how to call it and what it will return.<br />
* A couple of guidelines will be given to help developers write better code in such a way that two different plugins won’t “harm” each other. The module pattern will be used as a design pattern in order to put a plugin code inside a namespace. Also, this module helps in writing code which is easier to read and use.<br />
* It will be easier for the developers to write the code by using a new feature in the UI which generates the skeleton for the plugin.<br />
<br />
'''''What is the API reference documentation ?'''''<br />
<br />
This is the part which makes the API usable. Every aspect of the API, no matter how trivial, will be stated explicitly. It contains:<br />
<br />
* a description of all the data structures it depends upon<br />
* a description of all the function signatures:<br />
** function names<br />
** function parameters (names and types)<br />
** return type of the function<br />
** if it throws any exceptions or not<br />
<br />
'''''Where is the list of functions which were replaced ?'''''<br />
<br />
In the API reference documentation the developer can find out if a function replaces an old one.<br />
<br />
'''''Why should a developer write plugins using the API when it can do some “reverse engineering” and directly access any object/functionality of the application ?'''''<br />
<br />
It is not mandatory to write the code for the plugin this way. Probably the plugin will work as long as changes are not made in the core of the application, but the API comes also with a guarantee that after application changes, the plugins will continue to work. The UI team and plugin developers have the same goal: to deliver the best experience to the user. This is where the API comes into place - an interface between the two.<br />
<br />
'''''Will the API be rewritten with each new UI release ?'''''<br />
<br />
No. It will be improved. The goal of the API is to provide a stable interface to the developer so that when changing the core of the application it won’t be necessary to rewrite the plugins.<br />
<br />
'''''Is this API going to change in the near future ?'''''<br />
<br />
It can be changed. There will be parts of it which are going to be marked as ‘deprecated’. This means that the parts will be candidates for being removed, or modified in a backward incompatible way. The developers will be advised on how are they to change their code in order to use the features which replace the deprecated parts.<br />
<br />
'''''Is the API complete ?'''''<br />
<br />
Almost. Most of the functionality is there, but developers are encouraged to request new features from the API which will be added in future releases.<br />
<br />
== Guidelines on writing Javascript code for plugins in UI7 ==<br />
<br />
* Use the module pattern to organize your code inside a namespace. Choose a well defined name for your namespace.<br />
* Generate an UUID for your plugin. This way you can use the events engine.<br />
* Use the provided API plugins to perform most of your stuff. If you can’t find an implemented method inside the API you can ASK for an implementation to it.<br />
* '''NEVER USE''' variables/functions which are not accessible through API ! They can be changed or removed at any time.<br />
* If you need to do a background job (ex: start a timer), use the events engine and register a ‘cleanup’ function in which you finish the job (clear the timer).<br />
* We encourage the use of try { … } catch { … } blocks everywhere in your functions so that errors don’t get propagated to the top of the application.<br />
* Start from the skeleton provided and expand it:<br />
<br />
<source lang="javascript"><br />
var MyPlugin = (function (api) {<br />
// example of unique identifier for this plugin...<br />
var uuid = 'B971F6C4-F315-4E2E-AD08-F029A9777517';<br />
<br />
var myModule = {};<br />
<br />
function doSomething() {<br />
// register to event ‘on_ui_cpanel_before_close’...<br />
api.registerEventHandler('on_ui_cpanel_before_close', myModule, ‘cleanUp’);<br />
// and do something... <br />
}<br />
<br />
function cleanUp() {<br />
// perform clean up...<br />
}<br />
<br />
myModule = {<br />
uuid: uuid,<br />
doSomething: doSomething,<br />
cleanUp: cleanUp<br />
};<br />
return myModule;<br />
})(api);<br />
</source><br />
<br />
Your plugin functions will be accessible via ''MyPlugin.doSomething()'' construction.<br />
When the user will leave the cpanel, your plugin will be noticed via event ''‘on_ui_cpanel_before_close’''; this way you can perform the necessary cleanup.<br />
<br />
== JavaScript API ==<br />
<br />
''Defined in'': api.js<br />
<br />
=== Class Summary ===<br />
<br />
----<br />
<br />
'''API(config, application, ui)''' <br />
<br />
- API class for plugins<br />
<br />
'''Parameters:'''<br />
<br />
* {object} config - holds configuration data<br />
* {object} application - application layer<br />
* {object} ui - interface<br />
<br />
=== Method Summary ===<br />
<br />
----<br />
<br />
==== {Object} cloneObject(obj) ====<br />
<br />
- Clones a given object<br />
<br />
- Replaces: cloneObject()<br />
<br />
'''Parameters:'''<br />
<br />
* {object} obj - object to be cloned<br />
<br />
'''Returns:'''<br />
<br />
* {Object}<br />
<br />
==== {*} getCommandURL() ==== <br />
<br />
- Retrieves command URL<br />
<br />
- Replaces: command_url<br />
<br />
'''Returns:'''<br />
<br />
* {*}<br />
<br />
==== {string} getCpanelContent() ====<br />
<br />
- Retrieves cpanel content<br />
<br />
- Replaces: get_panel_html()<br />
<br />
'''Returns:'''<br />
<br />
* {string} HTML code set in cpanel<br />
<br />
==== {number} getCpanelDeviceId() ====<br />
<br />
- Returns device id for current opened cpanel or 0 if not found<br />
<br />
'''Returns:'''<br />
<br />
* {number} - device ID<br />
<br />
==== getCurrentHouseMode(onSuccess, onFailure, context) ====<br />
<br />
- Performs a data request to retrieve the current house mode<br />
<br />
'''Parameters:'''<br />
<br />
* {*} onSuccess Optional - function to be called if the call is successfull<br />
* {*} onFailure Optional - function to be called if the call fails<br />
* {object} context Optional - context in which to execute the functions of success and/or failure<br />
<br />
==== {*} getDataRequestURL() ====<br />
<br />
- Retrieves data request URL<br />
<br />
- Replaces: data_request_url<br />
<br />
'''Returns:'''<br />
<br />
* {*}<br />
<br />
==== {number} getDeviceIndex(deviceId) ====<br />
<br />
- Retrieves device index for given device id<br />
<br />
- Replaces: get_device_index()<br />
<br />
'''Parameters:'''<br />
<br />
* {number} deviceId - id of the device<br />
<br />
'''Returns:'''<br />
<br />
* {number}<br />
<br />
==== {*} getDeviceObject(deviceId) ====<br />
<br />
- Retrieves device object given its id<br />
<br />
- Replaces: get_device_obj()<br />
<br />
'''Parameters:'''<br />
<br />
* {number} deviceId - id of the device<br />
<br />
'''Returns:'''<br />
<br />
* {number}<br />
<br />
===={object} getDeviceState(deviceId, service, variable, options)====<br />
<br />
- Retrieves device state for a device (it can be either read from user data or lu status, depending on the options set)<br />
<br />
'''Parameters:'''<br />
<br />
* {number} deviceId - id of the device<br />
* {string} service - name of the service<br />
* {string} variable - name of the variable<br />
* {object} options Optional - list of options like: 'dynamic': (true - lu_status will be used [default], false - user_data will be used)<br />
<br />
'''Returns:'''<br />
<br />
* {object} value for a given variable<br />
<br />
===={object} getDeviceStateVariable(deviceId, service, variable, options)====<br />
<br />
- Retrieves device state for a device (it can be either read from user data or lu status, depending on the options set)(same as api.getDeviceState())<br />
<br />
'''Parameters:'''<br />
<br />
* {number} deviceId - id of the device<br />
* {string} service - name of the service<br />
* {string} variable - name of the variable<br />
* {object} options Optional - list of options like: 'dynamic': (true - lu_status will be used [default], false - user_data will be used)<br />
<br />
'''Returns:'''<br />
<br />
* {object} value for a given variable<br />
<br />
<br />
==== {Object|Boolean} getDeviceTemplate(deviceId) ====<br />
<br />
- Returns device template for a given device id<br />
<br />
'''Parameters:'''<br />
<br />
* {number} deviceId - id of the device<br />
<br />
'''Returns:'''<br />
<br />
* {Object|Boolean}<br />
<br />
==== {*} getDisplayedDeviceName(deviceId) ====<br />
<br />
- Retrieves displayed device name or 'unnamed device' if device doesn't have a name or undefined if device not found<br />
<br />
'''Parameters:'''<br />
<br />
* {number} deviceId - id of the device<br />
<br />
'''Returns:'''<br />
<br />
* {*} if device is found a string which contains the device name or 'Unnamed device' if device name is not set, or undefined if device wasn't found<br />
<br />
==== {*} getEventDefinition(deviceType) ====<br />
<br />
- Retrieves event list for a given device type<br />
<br />
- Replaces: get_event_definition() <br />
<br />
'''Parameters:'''<br />
<br />
* {string} deviceType - type of device<br />
<br />
'''Returns:'''<br />
<br />
* {*}<br />
<br />
==== {Array} getListOfDevices() ====<br />
<br />
- Returns the list of devices from userdata<br />
<br />
'''Returns:'''<br />
<br />
* {*}<br />
<br />
==== {Array} getListOfSupportedEvents() ====<br />
<br />
- Returns the list of supported events<br />
<br />
'''Returns:'''<br />
<br />
* {Array} - list containing each event a plugin can subscribe to<br />
<br />
==== getLuSdata(onSuccess, onFailure, context) ====<br />
<br />
- Performs a data request to retrieve lu_sdata<br />
<br />
'''Parameters:'''<br />
<br />
* {*} onSuccess Optional - function to be called if the call is successfull<br />
* {*} onFailure Optional - function to be called if the call fails<br />
* {object} context Optional - context in which to execute the functions of success and/or failure<br />
<br />
==== {*|Object} getRoomObject(roomId) ====<br />
<br />
- Returns room object given a room id<br />
<br />
- Replaces: get_room_by_id()<br />
<br />
'''Parameters:'''<br />
<br />
* {number} roomId - id of the room<br />
<br />
'''Returns:'''<br />
<br />
* {*|Object}<br />
<br />
==== {string} getSceneDescription(sceneId, options) ====<br />
<br />
- Retrieves scene description<br />
<br />
'''Parameters:'''<br />
<br />
* {number} sceneId - id of the scene<br />
<br />
* {object} options Optional<br />
<br />
- Options can be :<br />
<br />
{Boolean} hideTriggers: hides triggers description (default: false)<br />
<br />
{Boolean} hideSchedules: hides schedules description (default: false)<br />
<br />
{Boolean} hideActions: hides actions description (default: false)<br />
<br />
{Boolean} hideNotifications: hides notifications description (default: false)<br />
<br />
'''Returns:'''<br />
<br />
* {string}<br />
<br />
==== {*} getSendCommandURL() ====<br />
<br />
- Retrieves send command URL<br />
<br />
'''Returns:'''<br />
<br />
* {*}<br />
<br />
==== {*} getSysinfo() ====<br />
<br />
- Retrieves sysinfo JSON<br />
<br />
- Replaces: sysinfoJson<br />
<br />
'''Returns:'''<br />
<br />
* {*}<br />
<br />
==== {*} getUserData() ====<br />
<br />
- Retrieves userData or null if error<br />
<br />
- Replaces: jsonp.ud<br />
<br />
'''Returns:'''<br />
<br />
* {*} object containing userdata<br />
<br />
==== performActionOnDevice(deviceId, service, action, options) ====<br />
<br />
- Same as 'performLuActionOnDevice' Performs an action on a device<br />
<br />
'''Parameters:'''<br />
<br />
* {number} deviceId<br />
* {string} service<br />
* {string} action<br />
* {object} options Optional<br />
<br />
- Ex: options can be: { actionArguments: {arg1: 'val1', arg2: 'val2'}, onSuccess: function() {}, onFailure: function() {}, context: that }<br />
<br />
==== performLuActionOnDevice(deviceId, service, action, options) ====<br />
<br />
- Same as 'performActionOnDevice' Performs a lu_action on a device<br />
<br />
'''Parameters:'''<br />
<br />
* {number} deviceId<br />
* {string} service<br />
* {string} action<br />
* {object} options Optional<br />
<br />
- Ex: options can be: { actionArguments: {arg1: 'val1', arg2: 'val2'}, onSuccess: function() {}, onFailure: function() {}, context: that }<br />
<br />
==== registerEventHandler(eventName, object, functionName) ====<br />
<br />
- Register an event handler.<br />
<br />
'''Parameters:'''<br />
<br />
* {string} eventName - name of the event to register to<br />
* {object} object - the object which registers to the event<br />
* {string} functionName - the name of the function to be executed if event triggers<br />
<br />
==== runUpnpCode(code, options, onSuccess, onFailure, context) ====<br />
<br />
- Runs given Upnp code<br />
<br />
'''Parameters:'''<br />
<br />
* {string} code - code to execute<br />
* {object} options Optional - optionally options to be supplied (will be documented later)<br />
* {*} onSuccess Optional - function to be called if the call is successfull<br />
* {*} onFailure Optional - function to be called if the call fails<br />
* {object} context Optional - context in which to execute the functions of success and/or failure<br />
<br />
==== setCpanelContent(html) ====<br />
<br />
- Sets content for the cpanel<br />
<br />
- Replaces: set_panel_html()<br />
<br />
'''Parameters:'''<br />
<br />
* {string} html - the new content of the cpanel<br />
<br />
==== setCurrentHouseMode(modeValue, onSuccess, onFailure, context) ====<br />
<br />
- Sets current house mode<br />
<br />
'''Parameters:'''<br />
<br />
* {number} modeValue - new value for the house mode<br />
* {*} onSuccess Optional - function to be called if the call is successfull<br />
* {*} onFailure Optional - function to be called if the call fails<br />
* {object} context Optional - context in which to execute the functions of success and/or failure<br />
<br />
==== setDeviceState(deviceId, service, variable, value, options) ====<br />
<br />
- Sets state for a device variable (same as API.setDeviceStateVariable())<br />
<br />
- Replaces: set_device_state()<br />
<br />
'''Parameters:'''<br />
<br />
* {number} deviceId - id of the device<br />
* {string} service - name of the service<br />
* {string} variable - name of the variable<br />
* {*} value - new value for the variable<br />
* {object} options Optional - a set of options which can be:<br />
<br />
- onSuccess: {function} to be called if the call succedes<br />
<br />
- onFailure: {function} to be called if the call fails<br />
<br />
- context: {object} represents context of execution for onSuccess and onFailure functions<br />
<br />
- dynamic: {Boolean} true - state variable will be set in lu_status (default); false - state variable will be set in user_data<br />
<br />
==== setDeviceStatePersistent(deviceId, service, variable, value, options) ====<br />
<br />
- Sets a persistent state for a device variable using a variableset request (same as API.setDeviceStateVariablePersistent())<br />
<br />
'''Parameters:'''<br />
<br />
* {number} deviceId - id of the device<br />
* {string} service - name of the service<br />
* {string} variable - name of the variable<br />
* {*} value - new value for the variable<br />
* {object} options Optional - a set of options which can be:<br />
<br />
- onSuccess: {function} to be called if the call succedes<br />
<br />
- onFailure: {function} to be called if the call fails<br />
<br />
- context: {object} represents context of execution for onSuccess and onFailure functions<br />
<br />
==== setDeviceStateVariable(deviceId, service, variable, value, onSuccess, onFailure, context) ====<br />
<br />
- Sets state for a device variable using variableset request.<br />
<br />
- Replaces: set_device_state()<br />
<br />
'''Parameters:'''<br />
<br />
* {number} deviceId - id of the device<br />
* {string} service - name of the service<br />
* {string} variable - name of the variable<br />
* {*} value - new value for the variable<br />
* {*} onSuccess Optional - function to be called if the call is successfull<br />
* {*} onFailure Optional - function to be called if the call fails<br />
* {object} options Optional - a set of options which can be:<br />
<br />
- onSuccess: {function} to be called if the call succedes<br />
<br />
- onFailure: {function} to be called if the call fails<br />
<br />
- context: {object} represents context of execution for onSuccess and onFailure functions<br />
<br />
- dynamic: {Boolean} true - state variable will be set in lu_status (default); false - state variable will be set in user_data<br />
<br />
==== setDeviceStateVariablePersistent(deviceId, service, variable, value, onSuccess, onFailure, context) ====<br />
<br />
- Sets a persistent state for a device variable using a variableset request<br />
<br />
'''Parameters:'''<br />
<br />
* {number} deviceId - id of the device<br />
* {string} service - name of the service<br />
* {string} variable - name of the variable<br />
* {*} value - new value for the variable<br />
* {*} onSuccess Optional - function to be called if the call is successfull<br />
* {*} onFailure Optional - function to be called if the call fails<br />
* {object} options Optional - a set of options which can be:<br />
<br />
- onSuccess: {function} to be called if the call succedes<br />
<br />
- onFailure: {function} to be called if the call fails<br />
<br />
- context: {object} represents context of execution for onSuccess and onFailure functions<br />
<br />
=== Events ===<br />
<br />
----<br />
<br />
The list of available events can be obtained with the following command:<br />
<br />
'''api.getListOfSupportedEvents()'''<br />
<br />
* on_startup_showModalLoading<br />
** triggered before loading resources in the browser<br />
*on_startup_luStatusLoaded<br />
** triggered after luStatus was successfully parsed<br />
** parameter: luStatusObject<br />
* on_startup_show2gInterface<br />
** triggered after requesting account devices only if UI is not in ‘local mode’ and ‘slowConnection’ flag is set<br />
* on_ui_requireSave<br />
** triggered if user data was changed and save wasn’t issued<br />
* on_ui_userDataFirstLoaded<br />
** fired if user data was loaded for the first time<br />
* on_ui_staticDataAdded<br />
** fired if static_data was added to user data<br />
** parameter: staticDataObject<br />
* on_ui_staticDataChanged<br />
** fired if static_data was changed after parsing user data<br />
** parameter: changedStaticDataObject<br />
* on_ui_staticDataRemoved<br />
** fired if static_data was removed after parsing user data<br />
** parameter: idForRemovedStaticDataObject<br />
* on_ui_setupDeviceAdded<br />
** fired if new setup device (menu item) is added<br />
** parameter: setupDeviceObject<br />
* on_ui_setupDeviceChanged<br />
** fired if setup device (menu item) is changed<br />
** parameter: changedSetupDeviceObject<br />
* on_ui_setupDeviceRemoved<br />
** fired if setup device (menu item) is removed<br />
** parameter: idForRemovedSetupDeviceObject<br />
* on_ui_sectionAdded<br />
** triggered when new section is added<br />
** parameter: sectionObject<br />
* on_ui_sectionChanged<br />
** fired after section was changed<br />
** parameter: changedSectionObject<br />
* on_ui_sectionRemoved<br />
** fired after section was removed<br />
** parameter: idForRemovedSectionObject<br />
* on_ui_roomAdded<br />
** fired when new room was added to user data<br />
** parameter: roomObject<br />
* on_ui_roomChanged<br />
** fired after room was changed<br />
** parameter: changedRoomObject<br />
* on_ui_roomRemoved<br />
** fired after room was removed from user data<br />
** parameter: idForRemovedRoomObject<br />
* on_ui_deviceAdded<br />
** fired after device was added to user data<br />
** parameter: deviceObject<br />
*** wrapper object for<br />
**** device: this is the actual object representing the device<br />
**** deviceTemplate: object with the static data associated to this device type<br />
* on_ui_deviceChanged<br />
** fired after device was found changed in user data<br />
** parameter: changedDeviceObject<br />
*** wrapper object for<br />
**** device: this is the actual object representing the device<br />
**** deviceTemplate: object with the static data associated to this device type<br />
* on_ui_deviceRemoved<br />
** fired after device was found removed from user data<br />
** parameter: idForRemovedDeviceObject<br />
* on_ui_deviceJobsReceived<br />
** fired when jobs are found for a device in lu_status<br />
** parameter: deviceObjectFromLuStatus<br />
* on_ui_sceneAdded<br />
** fired after scene was added<br />
** parameter: sceneObject<br />
* on_ui_sceneChanged<br />
** fired after scene was changed<br />
** parameter: changedSceneObject<br />
* on_ui_sceneChanged<br />
** fired when scene is removed<br />
** parameter: idForRemovedSceneObject<br />
* on_ui_pluginAdded<br />
** triggered when plugin is added to user data<br />
** parameter: pluginObject<br />
* on_ui_pluginChanged<br />
** triggered when plugin is changed<br />
** parameter: changedPluginObject<br />
* on_ui_pluginRemoved<br />
** triggered when plugin is removed<br />
** parameter: idForRemovedPluginObject<br />
* on_ui_extraSubmenuItemAdded<br />
** triggered when extra submenu item is added<br />
** parameter: extraSubmenuItemObject<br />
*** wrapper for:<br />
**** submenuItem: object containing submenu item<br />
**** deviceType: string which contains the type of device for which the submenu item is added<br />
* on_ui_extraSubmenuItemChanged<br />
** triggered when extra submenu item is changed<br />
** parameter: changedExtraSubmenuItemObject<br />
*** wrapper for:<br />
**** oldObj: contains previous submenu item<br />
**** newObj: wrapper for:<br />
***** submenuItem: object containing submenu item<br />
***** deviceType: string which contains the type of device for which the submenu item is added<br />
* on_ui_extraSubmenuItemRemoved:<br />
** triggered when an extra submenu item is removed<br />
** parameter: idForRemovedExtraSubmenuItemObject<br />
* on_ui_cardAdded<br />
** triggered when card is added to user data<br />
** parameter: cardObject<br />
* on_ui_cardChanged<br />
** triggered when card is found changed in user data<br />
** parameter: changedCardObject<br />
* on_ui_cardRemoved<br />
** triggered when card is removed from user data<br />
** parameter: idForRemovedCardObject<br />
* on_ui_jobsUpdated<br />
** triggered when job is updated in lu_status<br />
** parameter: luStatusJobsObject<br />
* on_ui_deviceStatusChanged<br />
** triggered when device status is changed<br />
** parameter: deviceObjectFromLuStatus<br />
* on_ui_syncClock<br />
** triggered after lu_status is parsed<br />
** parameter: luStatusLocalTime<br />
* on_ui_initFinished<br />
** fired when init has finished (UI should be ready now)<br />
* on_ui_setUserAuthenticated<br />
** fired after login is successful<br />
* on_ui_saveFinished<br />
** fired after save is finished<br />
* on_ui_initNotLogged<br />
** triggered if user is not logged in<br />
* on_ui_alertsUpdated<br />
** fired after alert list was updated<br />
* on_ui_refreshDashboardCards<br />
** triggered when dashboard cards are refreshed<br />
* on_ui_engineAvailable<br />
** triggered if engine is not busy<br />
* on_ui_2GEnabled<br />
** triggered when parsing lu_status if 2G is enabled<br />
* on_ui_userDataSetTemperatureFormat<br />
** triggered after temperature format is set in user data<br />
** parameter: userDataObject<br />
* on_ui_userDataLoaded<br />
** triggered after user data parsing is completed<br />
* on_parseUserData<br />
** triggered when user data parsing is started<br />
* on_ui_accountUnitsLoaded<br />
** fired after account lis from MMS was successfully loaded<br />
* accountInformationLoaded<br />
** triggered after account information is loaded<br />
** parameter: accountInfoObject<br />
* on_ui_finishDrawingMenu<br />
** triggered after parsing of user data setup devices has finished<br />
* on_ui_deviceTypeChanged<br />
** triggered if device type for a device has changed<br />
** parameter: deviceObject<br />
*** wrapper object for<br />
**** device: this is the actual object representing the device<br />
**** deviceTemplate: object with the static data associated to this device type<br />
* on_ui_hideModalLoading<br />
** triggered each time a time consuming job finishes (so that UI can hide modal loading)<br />
* on_ui_showUserDataSaveFailure<br />
** triggered if user data save has failed<br />
* on_ui_showErrorMessage<br />
** fired if application has error message to send to the UI<br />
* on_ui_cpanel_before_close<br />
** fired before closing the cpanel to allow plugins to cleanup their data<br />
** parameters: idForDeviceWhichOpenedTheCpanel<br />
<br />
=== Migration Walkthrough for plugins with JS ===<br />
<br />
With the introduction of our new JavaScript API, plugin mechanism slightly changed. In order to keep a backward compatibility with the UI5 version, there are a couple of thing a developer should do :<br />
<br />
* '''Update the JS file using the JavaScript API'''<br />
<br />
* '''Update the JSON file with proper calls for JavaScript functions'''<br />
<br />
For UI5 version, the JavaScript functions were called in JSON file like this :<br />
<br />
'''"ScriptName": "Your_JS_File.js",'''<br />
<br />
'''"Function": "Your_Function_Name"'''<br />
<br />
Example: Home Care Plugin - JSON file:<br />
<br />
<source lang="javascript"><br />
{<br />
"Label": {<br />
"lang_tag": "users",<br />
"text": "Users"<br />
},<br />
"TopNavigationTab": "1",<br />
"Position": "0",<br />
"TabType": "javascript",<br />
"ScriptName": "J_HomeCare.js",<br />
"Function": "ShowUsers"<br />
},<br />
</source><br />
<br />
For UI7, the JavaScript functions are called like this : <br />
<br />
'''"ScriptName": "Your_JS_File_for_UI7.js",'''<br />
<br />
'''"Function": "Your_Class_Name.Your_Function_Name"'''<br />
<br />
Example:<br />
<br />
<source lang="javascript"><br />
{<br />
"Label": {<br />
"lang_tag": "users",<br />
"text": "Users"<br />
},<br />
"TopNavigationTab": "1",<br />
"Position": "0",<br />
"TabType": "javascript",<br />
"ScriptName": "J_HomeCare_UI7.js",<br />
"Function": "HomeCare.ShowUsers"<br />
},<br />
</source><br />
<br />
By now, you should be asking yourself: "How plugin will work on UI5 if I update these files?". If you answer by yourself and the answer is : "It won't work", you are right. For this you will need to do an additional step:<br />
<br />
*'''Create different JSON and JS files and perform a check in your Luup code'''<br />
**As you can see in the above example for JSON file, our choice was to add "''_UI7''" for our JS file : "''J_HomeCare_UI7.js''". We suggest you to do the same, but this is not a requirement. We did the same with JSON file : "''D_HomeCare_UI7.json''"<br />
**In order to use the new JSON and JS files in UI7 instead of UI5 versions, "device_json" attribute of your device must set with the JSON file for UI7. For this, you can use the following function:<br />
<source lang="lua"> <br />
local function checkVersion()<br />
local ui7Check = luup.variable_get(SID, "UI7Check", lug_device) or ""<br />
if ui7Check == "" then<br />
luup.variable_set(SID, "UI7Check", "false", lug_device)<br />
ui7Check = "false"<br />
end<br />
if( luup.version_branch == 1 and luup.version_major == 7 and ui7Check == "false") then<br />
luup.variable_set(SID, "UI7Check", "true", lug_device)<br />
luup.attr_set("device_json", "Your_UI7_JSON_File", lug_device)<br />
luup.reload()<br />
end<br />
end<br />
</source><br />
''SID'' - your Service ID; ''lug_device'' - your device ID; <br />
**Call ''checkVersion()'' in your initialization function, before doing something else.<br />
<br />
=== HomeCare Plugin - updated for UI7 ===<br />
<br />
We use the HomeCare plugin as example for what need to be added/updated for UI7. Below you can download plugin files:<br />
<br />
[[File:HomeCare.zip]]<br />
<br />
This is the published version of HomeCare plugin that can be downloaded from our appstore. This version is compatible with both UI5 and UI7.</div>Andreimioshttp://wiki.mios.com/index.php/JavaScript_APIJavaScript API2015-02-03T15:21:50Z<p>Andreimios: </p>
<hr />
<div>== Usage ==<br />
<pre>"Tabs": [<br />
{<br />
"Label": {<br />
"lang_tag": "users",<br />
"text": "Users" <br />
},<br />
"Position": "0",<br />
"TabType": "javascript",<br />
"ScriptName": "I_HomeCare.js",<br />
"Function": "showUsers"<br />
}, </pre> <br />
To generate a tab using your JavaScript functions you need to specify this by setting ''TabType'' to '''''javascript'''''. Then, you need to specify the script file's name and which function in this file will be used to draw the tab's content. That function will have one argument, which is the device number.<br> <br />
<br />
==== &lt;functionName&gt; (deviceNumber) ====<br />
<br />
This is the tab rendering function. The [[#set_panel_html_.28html.29 | set_panel_html]] function must be called at the end.<br> <br />
<br />
'''Input:''' <br />
<br />
*deviceNumber (number)<br><br />
<br />
'''Output:''' <br />
<br />
*nothing<br />
<br />
<br><br />
<br />
== Variables ==<br />
<br />
==== jsonp.ud ====<br />
<br />
This is the user data. <br />
<br />
*'''Type''': object <br />
*'''Members''': <br />
**devices (array) <br />
**scenes (array) <br />
**users (array) <br />
**rooms (array) <br />
**eventList (array) <br />
**etc.<br />
<br />
<br> <br />
<br />
==== jsonp.ud.devices ====<br />
<br />
*'''Type''': array <br />
*'''Members''': <br />
**id (number) <br />
**device_type (string) <br />
**room (number) <br />
**name (string) <br />
**category_num (number) <br />
**etc.<br />
<br />
<br> <br />
<br />
==== jsonp.ud.scenes ====<br />
<br />
*'''Type''': array <br />
*'''Members''': <br />
**id (number) <br />
**name (string) <br />
**room (number) <br />
**Timer_ids (array) <br />
**Timer (object) <br />
**etc.<br />
<br />
<br> <br />
<br />
== Functions ==<br />
<br />
==== get_device_state (deviceId, serviceId, variable, dynamic) ====<br />
<br />
'''Input:''' <br />
<br />
*deviceId (number)<br />
*serviceId (string)<br />
*variable (string)<br />
*dynamic (number): if '''1''', the variable's value is taken from ''lu_status'', else, the variable's value is taken from ''user_data''. ''user_data'' is read at Luup startup, so for variables that change their value frequently (like Watts, Temperature, etc.) ''dynamic'' should be '''1'''.<br />
<br />
'''Output:''' <br />
<br />
*variable value (string or ''undefined'')<br />
<br />
<br><br />
<br />
==== set_device_state (deviceId, serviceId, variable, value, dynamic) ====<br />
<br />
'''Input:''' <br />
<br />
*deviceId (number)<br />
*serviceId (string)<br />
*variable (string)<br />
*value (string)<br />
*dynamic (number): if '''1''', the variable's value is saved to ''lu_status'' (the value is lost after Luup is restarted), else, the variable's value is saved to a copy of ''user_data''; the real user_data is updated when LuaUPnP is restarted.<br />
<br />
'''Output:''' <br />
<br />
*''true'' if the operation succeeded, ''false'' otherwise<br />
<br />
<br><br />
<br />
==== _console (str) ====<br />
<br />
'''Input:''' <br />
<br />
*str (string): text to be written in the console. You need to have FireBug installed in order to have a console.<br />
<br />
'''Output:''' <br />
<br />
*nothing<br />
<br />
<br><br />
<br />
==== set_panel_html (html) ====<br />
<br />
Used in the tab rendering functions. <br />
<br />
'''Input:''' <br />
<br />
*html (string): The html to be used for generating the tab content.<br />
<br />
'''Output:''' <br />
<br />
*nothing<br />
<br />
[[Category:Development]]<br />
<br />
= JavaScript API for UI7 =<br />
<br />
== Introduction ==<br />
<br />
One of the new features of UI7 is the Javascript API for writing plugins. This is a free programming interface which is robust, well documented and comes with a guarantee that it will be compatible with the following UI releases.<br />
<br />
'''''What is this “API” ?'''''<br />
<br />
Simply said: it is a layer between the UI and the plugin developer. This way, the developer can use the features available in the UI by interacting only with the API. By using the new features available in the API, the overall user experience can be visibly improved.<br />
<br />
'''''How does it work ?'''''<br />
<br />
The API comes in the form of a library which exposes to the developer the objects and methods/functions needed to implement functionality in their plugins.<br />
<br />
'''''How is this different from the previous way of writing plugins ?'''''<br />
<br />
The developers were writing Javascript code and they had full access to the core of the application. There were a couple of objects and functions written by the UI team which were easing the work for the developer.<br />
By using the new API, the developer can write code without interfering with the core of the application.<br />
<br />
'''''What is new ?'''''<br />
<br />
* The developer can write the plugin without interfering with any other code except the API. This means there are a great bundle of methods like setters and getters which help writing good code.<br />
* UI team can make any changes to the core of the application, but as long as the API stays the same, the plugins will work. This way, the application can be improved and the developer won’t have to fix the code in order for it to work. New versions of the UI can be launched and the plugins will be compatible.<br />
* Event handling - the application will notify the plugin (via the API) about the events that happen inside. Consider, for example, the addition of a new device to the unit. The developer will know, by simply listening to an event, that a device was added and so, (s)he will write the code in such a way that it will take into account the event. The user experience will be greatly improved.<br />
* Asynchronous getters and setters - because most of the actions that happen inside the UI is asynchronous, so are the API’s method written. Most of them have a signature like this: function getXXX(obj, onSuccess, onFailure), where ‘onSuccess’ and ‘onFailure’ are callback functions which are called based on the result of the call.<br />
* No more global variables to manipulate. Everything is handled through getters/setters via API.<br />
* An API reference documentation: every method and its parameters is carefully documented so that the developer would know what the function does, how to call it and what it will return.<br />
* A couple of guidelines will be given to help developers write better code in such a way that two different plugins won’t “harm” each other. The module pattern will be used as a design pattern in order to put a plugin code inside a namespace. Also, this module helps in writing code which is easier to read and use.<br />
* It will be easier for the developers to write the code by using a new feature in the UI which generates the skeleton for the plugin.<br />
<br />
'''''What is the API reference documentation ?'''''<br />
<br />
This is the part which makes the API usable. Every aspect of the API, no matter how trivial, will be stated explicitly. It contains:<br />
<br />
* a description of all the data structures it depends upon<br />
* a description of all the function signatures:<br />
** function names<br />
** function parameters (names and types)<br />
** return type of the function<br />
** if it throws any exceptions or not<br />
<br />
'''''Where is the list of functions which were replaced ?'''''<br />
<br />
In the API reference documentation the developer can find out if a function replaces an old one.<br />
<br />
'''''Why should a developer write plugins using the API when it can do some “reverse engineering” and directly access any object/functionality of the application ?'''''<br />
<br />
It is not mandatory to write the code for the plugin this way. Probably the plugin will work as long as changes are not made in the core of the application, but the API comes also with a guarantee that after application changes, the plugins will continue to work. The UI team and plugin developers have the same goal: to deliver the best experience to the user. This is where the API comes into place - an interface between the two.<br />
<br />
'''''Will the API be rewritten with each new UI release ?'''''<br />
<br />
No. It will be improved. The goal of the API is to provide a stable interface to the developer so that when changing the core of the application it won’t be necessary to rewrite the plugins.<br />
<br />
'''''Is this API going to change in the near future ?'''''<br />
<br />
It can be changed. There will be parts of it which are going to be marked as ‘deprecated’. This means that the parts will be candidates for being removed, or modified in a backward incompatible way. The developers will be advised on how are they to change their code in order to use the features which replace the deprecated parts.<br />
<br />
'''''Is the API complete ?'''''<br />
<br />
Almost. Most of the functionality is there, but developers are encouraged to request new features from the API which will be added in future releases.<br />
<br />
== Guidelines on writing Javascript code for plugins in UI7 ==<br />
<br />
* Use the module pattern to organize your code inside a namespace. Choose a well defined name for your namespace.<br />
* Generate an UUID for your plugin. This way you can use the events engine.<br />
* Use the provided API plugins to perform most of your stuff. If you can’t find an implemented method inside the API you can ASK for an implementation to it.<br />
* '''NEVER USE''' variables/functions which are not accessible through API ! They can be changed or removed at any time.<br />
* If you need to do a background job (ex: start a timer), use the events engine and register a ‘cleanup’ function in which you finish the job (clear the timer).<br />
* We encourage the use of try { … } catch { … } blocks everywhere in your functions so that errors don’t get propagated to the top of the application.<br />
* Start from the skeleton provided and expand it:<br />
<br />
<source lang="javascript"><br />
var MyPlugin = (function (api) {<br />
// example of unique identifier for this plugin...<br />
var uuid = 'B971F6C4-F315-4E2E-AD08-F029A9777517';<br />
<br />
var myModule = {};<br />
<br />
function doSomething() {<br />
// register to event ‘on_ui_cpanel_before_close’...<br />
api.registerEventHandler('on_ui_cpanel_before_close', myModule, ‘cleanUp’);<br />
// and do something... <br />
}<br />
<br />
function cleanUp() {<br />
// perform clean up...<br />
}<br />
<br />
myModule = {<br />
uuid: uuid,<br />
doSomething: doSomething,<br />
cleanUp: cleanUp<br />
};<br />
return myModule;<br />
})(api);<br />
</source><br />
<br />
Your plugin functions will be accessible via ''MyPlugin.doSomething()'' construction.<br />
When the user will leave the cpanel, your plugin will be noticed via event ''‘on_ui_cpanel_before_close’''; this way you can perform the necessary cleanup.<br />
<br />
== JavaScript API ==<br />
<br />
''Defined in'': api.js<br />
<br />
=== Class Summary ===<br />
<br />
----<br />
<br />
'''API(config, application, ui)''' <br />
<br />
- API class for plugins<br />
<br />
'''Parameters:'''<br />
<br />
* {object} config - holds configuration data<br />
* {object} application - application layer<br />
* {object} ui - interface<br />
<br />
=== Method Summary ===<br />
<br />
----<br />
<br />
==== {Object} cloneObject(obj) ====<br />
<br />
- Clones a given object<br />
<br />
- Replaces: cloneObject()<br />
<br />
'''Parameters:'''<br />
<br />
* {object} obj - object to be cloned<br />
<br />
'''Returns:'''<br />
<br />
* {Object}<br />
<br />
==== {*} getCommandURL() ==== <br />
<br />
- Retrieves command URL<br />
<br />
- Replaces: command_url<br />
<br />
'''Returns:'''<br />
<br />
* {*}<br />
<br />
==== {string} getCpanelContent() ====<br />
<br />
- Retrieves cpanel content<br />
<br />
- Replaces: get_panel_html()<br />
<br />
'''Returns:'''<br />
<br />
* {string} HTML code set in cpanel<br />
<br />
==== {number} getCpanelDeviceId() ====<br />
<br />
- Returns device id for current opened cpanel or 0 if not found<br />
<br />
'''Returns:'''<br />
<br />
* {number} - device ID<br />
<br />
==== getCurrentHouseMode(onSuccess, onFailure, context) ====<br />
<br />
- Performs a data request to retrieve the current house mode<br />
<br />
'''Parameters:'''<br />
<br />
* {*} onSuccess Optional - function to be called if the call is successfull<br />
* {*} onFailure Optional - function to be called if the call fails<br />
* {object} context Optional - context in which to execute the functions of success and/or failure<br />
<br />
==== {*} getDataRequestURL() ====<br />
<br />
- Retrieves data request URL<br />
<br />
- Replaces: data_request_url<br />
<br />
'''Returns:'''<br />
<br />
* {*}<br />
<br />
==== {number} getDeviceIndex(deviceId) ====<br />
<br />
- Retrieves device index for given device id<br />
<br />
- Replaces: get_device_index()<br />
<br />
'''Parameters:'''<br />
<br />
* {number} deviceId - id of the device<br />
<br />
'''Returns:'''<br />
<br />
* {number}<br />
<br />
==== {*} getDeviceObject(deviceId) ====<br />
<br />
- Retrieves device object given its id<br />
<br />
- Replaces: get_device_obj()<br />
<br />
'''Parameters:'''<br />
<br />
* {number} deviceId - id of the device<br />
<br />
'''Returns:'''<br />
<br />
* {number}<br />
<br />
===={object} getDeviceState(deviceId, service, variable, options)====<br />
<br />
- Retrieves device state for a device (it can be either read from user data or lu status, depending on the options set)<br />
<br />
'''Parameters:'''<br />
<br />
* {number} deviceId - id of the device<br />
* {string} service - name of the service<br />
* {string} variable - name of the variable<br />
* {object} options Optional - list of options like: 'dynamic': (true - lu_status will be used [default], false - user_data will be used)<br />
<br />
'''Returns:'''<br />
<br />
* {object} value for a given variable<br />
<br />
===={object} getDeviceStateVariable(deviceId, service, variable, options)====<br />
<br />
- Retrieves device state for a device (it can be either read from user data or lu status, depending on the options set)(same as api.getDeviceState())<br />
<br />
'''Parameters:'''<br />
<br />
* {number} deviceId - id of the device<br />
* {string} service - name of the service<br />
* {string} variable - name of the variable<br />
* {object} options Optional - list of options like: 'dynamic': (true - lu_status will be used [default], false - user_data will be used)<br />
<br />
'''Returns:'''<br />
<br />
* {object} value for a given variable<br />
<br />
<br />
==== {Object|Boolean} getDeviceTemplate(deviceId) ====<br />
<br />
- Returns device template for a given device id<br />
<br />
'''Parameters:'''<br />
<br />
* {number} deviceId - id of the device<br />
<br />
'''Returns:'''<br />
<br />
* {Object|Boolean}<br />
<br />
==== {*} getDisplayedDeviceName(deviceId) ====<br />
<br />
- Retrieves displayed device name or 'unnamed device' if device doesn't have a name or undefined if device not found<br />
<br />
'''Parameters:'''<br />
<br />
* {number} deviceId - id of the device<br />
<br />
'''Returns:'''<br />
<br />
* {*} if device is found a string which contains the device name or 'Unnamed device' if device name is not set, or undefined if device wasn't found<br />
<br />
==== {*} getEventDefinition(deviceType) ====<br />
<br />
- Retrieves event list for a given device type<br />
<br />
- Replaces: get_event_definition() <br />
<br />
'''Parameters:'''<br />
<br />
* {string} deviceType - type of device<br />
<br />
'''Returns:'''<br />
<br />
* {*}<br />
<br />
==== {Array} getListOfDevices() ====<br />
<br />
- Returns the list of devices from userdata<br />
<br />
'''Returns:'''<br />
<br />
* {*}<br />
<br />
==== {Array} getListOfSupportedEvents() ====<br />
<br />
- Returns the list of supported events<br />
<br />
'''Returns:'''<br />
<br />
* {Array} - list containing each event a plugin can subscribe to<br />
<br />
==== getLuSdata(onSuccess, onFailure, context) ====<br />
<br />
- Performs a data request to retrieve lu_sdata<br />
<br />
'''Parameters:'''<br />
<br />
* {*} onSuccess Optional - function to be called if the call is successfull<br />
* {*} onFailure Optional - function to be called if the call fails<br />
* {object} context Optional - context in which to execute the functions of success and/or failure<br />
<br />
==== {*|Object} getRoomObject(roomId) ====<br />
<br />
- Returns room object given a room id<br />
<br />
- Replaces: get_room_by_id()<br />
<br />
'''Parameters:'''<br />
<br />
* {number} roomId - id of the room<br />
<br />
'''Returns:'''<br />
<br />
* {*|Object}<br />
<br />
==== {string} getSceneDescription(sceneId, options) ====<br />
<br />
- Retrieves scene description<br />
<br />
'''Parameters:'''<br />
<br />
* {number} sceneId - id of the scene<br />
<br />
* {object} options Optional<br />
<br />
- Options can be :<br />
<br />
{Boolean} hideTriggers: hides triggers description (default: false)<br />
<br />
{Boolean} hideSchedules: hides schedules description (default: false)<br />
<br />
{Boolean} hideActions: hides actions description (default: false)<br />
<br />
{Boolean} hideNotifications: hides notifications description (default: false)<br />
<br />
'''Returns:'''<br />
<br />
* {string}<br />
<br />
==== {*} getSendCommandURL() ====<br />
<br />
- Retrieves send command URL<br />
<br />
'''Returns:'''<br />
<br />
* {*}<br />
<br />
==== {*} getSysinfo() ====<br />
<br />
- Retrieves sysinfo JSON<br />
<br />
- Replaces: sysinfoJson<br />
<br />
'''Returns:'''<br />
<br />
* {*}<br />
<br />
==== {*} getUserData() ====<br />
<br />
- Retrieves userData or null if error<br />
<br />
- Replaces: jsonp.ud<br />
<br />
'''Returns:'''<br />
<br />
* {*} object containing userdata<br />
<br />
==== performActionOnDevice(deviceId, service, action, options) ====<br />
<br />
- Same as 'performLuActionOnDevice' Performs an action on a device<br />
<br />
'''Parameters:'''<br />
<br />
* {number} deviceId<br />
* {string} service<br />
* {string} action<br />
* {object} options Optional<br />
<br />
- Ex: options can be: { actionArguments: {arg1: 'val1', arg2: 'val2'}, onSuccess: function() {}, onFailure: function() {}, context: that }<br />
<br />
==== performLuActionOnDevice(deviceId, service, action, options) ====<br />
<br />
- Same as 'performActionOnDevice' Performs a lu_action on a device<br />
<br />
'''Parameters:'''<br />
<br />
* {number} deviceId<br />
* {string} service<br />
* {string} action<br />
* {object} options Optional<br />
<br />
- Ex: options can be: { actionArguments: {arg1: 'val1', arg2: 'val2'}, onSuccess: function() {}, onFailure: function() {}, context: that }<br />
<br />
==== registerEventHandler(eventName, object, functionName) ====<br />
<br />
- Register an event handler.<br />
<br />
'''Parameters:'''<br />
<br />
* {string} eventName - name of the event to register to<br />
* {object} object - the object which registers to the event<br />
* {string} functionName - the name of the function to be executed if event triggers<br />
<br />
==== runUpnpCode(code, options, onSuccess, onFailure, context) ====<br />
<br />
- Runs given Upnp code<br />
<br />
'''Parameters:'''<br />
<br />
* {string} code - code to execute<br />
* {object} options Optional - optionally options to be supplied (will be documented later)<br />
* {*} onSuccess Optional - function to be called if the call is successfull<br />
* {*} onFailure Optional - function to be called if the call fails<br />
* {object} context Optional - context in which to execute the functions of success and/or failure<br />
<br />
==== setCpanelContent(html) ====<br />
<br />
- Sets content for the cpanel<br />
<br />
- Replaces: set_panel_html()<br />
<br />
'''Parameters:'''<br />
<br />
* {string} html - the new content of the cpanel<br />
<br />
==== setCurrentHouseMode(modeValue, onSuccess, onFailure, context) ====<br />
<br />
- Sets current house mode<br />
<br />
'''Parameters:'''<br />
<br />
* {number} modeValue - new value for the house mode<br />
* {*} onSuccess Optional - function to be called if the call is successfull<br />
* {*} onFailure Optional - function to be called if the call fails<br />
* {object} context Optional - context in which to execute the functions of success and/or failure<br />
<br />
==== setDeviceState(deviceId, service, variable, value, options) ====<br />
<br />
- Sets state for a device variable (same as API.setDeviceStateVariable())<br />
<br />
- Replaces: set_device_state()<br />
<br />
'''Parameters:'''<br />
<br />
* {number} deviceId - id of the device<br />
* {string} service - name of the service<br />
* {string} variable - name of the variable<br />
* {*} value - new value for the variable<br />
* {object} context Optional - a set of options which can be:<br />
<br />
- onSuccess: {function} to be called if the call succedes<br />
<br />
- onFailure: {function} to be called if the call fails<br />
<br />
- context: {object} represents context of execution for onSuccess and onFailure functions<br />
<br />
- dynamic: {Boolean} true - state variable will be set in lu_status (default); false - state variable will be set in user_data<br />
<br />
==== setDeviceStateVariable(deviceId, service, variable, value, onSuccess, onFailure, context) ====<br />
<br />
- Sets state for a device variable using variableset request.<br />
<br />
- Replaces: set_device_state()<br />
<br />
'''Parameters:'''<br />
<br />
* {number} deviceId - id of the device<br />
* {string} service - name of the service<br />
* {string} variable - name of the variable<br />
* {*} value - new value for the variable<br />
* {*} onSuccess Optional - function to be called if the call is successfull<br />
* {*} onFailure Optional - function to be called if the call fails<br />
* {object} context Optional - context in which to execute the functions of success and/or failure<br />
<br />
<br />
=== Events ===<br />
<br />
----<br />
<br />
The list of available events can be obtained with the following command:<br />
<br />
'''api.getListOfSupportedEvents()'''<br />
<br />
* on_startup_showModalLoading<br />
** triggered before loading resources in the browser<br />
*on_startup_luStatusLoaded<br />
** triggered after luStatus was successfully parsed<br />
** parameter: luStatusObject<br />
* on_startup_show2gInterface<br />
** triggered after requesting account devices only if UI is not in ‘local mode’ and ‘slowConnection’ flag is set<br />
* on_ui_requireSave<br />
** triggered if user data was changed and save wasn’t issued<br />
* on_ui_userDataFirstLoaded<br />
** fired if user data was loaded for the first time<br />
* on_ui_staticDataAdded<br />
** fired if static_data was added to user data<br />
** parameter: staticDataObject<br />
* on_ui_staticDataChanged<br />
** fired if static_data was changed after parsing user data<br />
** parameter: changedStaticDataObject<br />
* on_ui_staticDataRemoved<br />
** fired if static_data was removed after parsing user data<br />
** parameter: idForRemovedStaticDataObject<br />
* on_ui_setupDeviceAdded<br />
** fired if new setup device (menu item) is added<br />
** parameter: setupDeviceObject<br />
* on_ui_setupDeviceChanged<br />
** fired if setup device (menu item) is changed<br />
** parameter: changedSetupDeviceObject<br />
* on_ui_setupDeviceRemoved<br />
** fired if setup device (menu item) is removed<br />
** parameter: idForRemovedSetupDeviceObject<br />
* on_ui_sectionAdded<br />
** triggered when new section is added<br />
** parameter: sectionObject<br />
* on_ui_sectionChanged<br />
** fired after section was changed<br />
** parameter: changedSectionObject<br />
* on_ui_sectionRemoved<br />
** fired after section was removed<br />
** parameter: idForRemovedSectionObject<br />
* on_ui_roomAdded<br />
** fired when new room was added to user data<br />
** parameter: roomObject<br />
* on_ui_roomChanged<br />
** fired after room was changed<br />
** parameter: changedRoomObject<br />
* on_ui_roomRemoved<br />
** fired after room was removed from user data<br />
** parameter: idForRemovedRoomObject<br />
* on_ui_deviceAdded<br />
** fired after device was added to user data<br />
** parameter: deviceObject<br />
*** wrapper object for<br />
**** device: this is the actual object representing the device<br />
**** deviceTemplate: object with the static data associated to this device type<br />
* on_ui_deviceChanged<br />
** fired after device was found changed in user data<br />
** parameter: changedDeviceObject<br />
*** wrapper object for<br />
**** device: this is the actual object representing the device<br />
**** deviceTemplate: object with the static data associated to this device type<br />
* on_ui_deviceRemoved<br />
** fired after device was found removed from user data<br />
** parameter: idForRemovedDeviceObject<br />
* on_ui_deviceJobsReceived<br />
** fired when jobs are found for a device in lu_status<br />
** parameter: deviceObjectFromLuStatus<br />
* on_ui_sceneAdded<br />
** fired after scene was added<br />
** parameter: sceneObject<br />
* on_ui_sceneChanged<br />
** fired after scene was changed<br />
** parameter: changedSceneObject<br />
* on_ui_sceneChanged<br />
** fired when scene is removed<br />
** parameter: idForRemovedSceneObject<br />
* on_ui_pluginAdded<br />
** triggered when plugin is added to user data<br />
** parameter: pluginObject<br />
* on_ui_pluginChanged<br />
** triggered when plugin is changed<br />
** parameter: changedPluginObject<br />
* on_ui_pluginRemoved<br />
** triggered when plugin is removed<br />
** parameter: idForRemovedPluginObject<br />
* on_ui_extraSubmenuItemAdded<br />
** triggered when extra submenu item is added<br />
** parameter: extraSubmenuItemObject<br />
*** wrapper for:<br />
**** submenuItem: object containing submenu item<br />
**** deviceType: string which contains the type of device for which the submenu item is added<br />
* on_ui_extraSubmenuItemChanged<br />
** triggered when extra submenu item is changed<br />
** parameter: changedExtraSubmenuItemObject<br />
*** wrapper for:<br />
**** oldObj: contains previous submenu item<br />
**** newObj: wrapper for:<br />
***** submenuItem: object containing submenu item<br />
***** deviceType: string which contains the type of device for which the submenu item is added<br />
* on_ui_extraSubmenuItemRemoved:<br />
** triggered when an extra submenu item is removed<br />
** parameter: idForRemovedExtraSubmenuItemObject<br />
* on_ui_cardAdded<br />
** triggered when card is added to user data<br />
** parameter: cardObject<br />
* on_ui_cardChanged<br />
** triggered when card is found changed in user data<br />
** parameter: changedCardObject<br />
* on_ui_cardRemoved<br />
** triggered when card is removed from user data<br />
** parameter: idForRemovedCardObject<br />
* on_ui_jobsUpdated<br />
** triggered when job is updated in lu_status<br />
** parameter: luStatusJobsObject<br />
* on_ui_deviceStatusChanged<br />
** triggered when device status is changed<br />
** parameter: deviceObjectFromLuStatus<br />
* on_ui_syncClock<br />
** triggered after lu_status is parsed<br />
** parameter: luStatusLocalTime<br />
* on_ui_initFinished<br />
** fired when init has finished (UI should be ready now)<br />
* on_ui_setUserAuthenticated<br />
** fired after login is successful<br />
* on_ui_saveFinished<br />
** fired after save is finished<br />
* on_ui_initNotLogged<br />
** triggered if user is not logged in<br />
* on_ui_alertsUpdated<br />
** fired after alert list was updated<br />
* on_ui_refreshDashboardCards<br />
** triggered when dashboard cards are refreshed<br />
* on_ui_engineAvailable<br />
** triggered if engine is not busy<br />
* on_ui_2GEnabled<br />
** triggered when parsing lu_status if 2G is enabled<br />
* on_ui_userDataSetTemperatureFormat<br />
** triggered after temperature format is set in user data<br />
** parameter: userDataObject<br />
* on_ui_userDataLoaded<br />
** triggered after user data parsing is completed<br />
* on_parseUserData<br />
** triggered when user data parsing is started<br />
* on_ui_accountUnitsLoaded<br />
** fired after account lis from MMS was successfully loaded<br />
* accountInformationLoaded<br />
** triggered after account information is loaded<br />
** parameter: accountInfoObject<br />
* on_ui_finishDrawingMenu<br />
** triggered after parsing of user data setup devices has finished<br />
* on_ui_deviceTypeChanged<br />
** triggered if device type for a device has changed<br />
** parameter: deviceObject<br />
*** wrapper object for<br />
**** device: this is the actual object representing the device<br />
**** deviceTemplate: object with the static data associated to this device type<br />
* on_ui_hideModalLoading<br />
** triggered each time a time consuming job finishes (so that UI can hide modal loading)<br />
* on_ui_showUserDataSaveFailure<br />
** triggered if user data save has failed<br />
* on_ui_showErrorMessage<br />
** fired if application has error message to send to the UI<br />
* on_ui_cpanel_before_close<br />
** fired before closing the cpanel to allow plugins to cleanup their data<br />
** parameters: idForDeviceWhichOpenedTheCpanel<br />
<br />
=== Migration Walkthrough for plugins with JS ===<br />
<br />
With the introduction of our new JavaScript API, plugin mechanism slightly changed. In order to keep a backward compatibility with the UI5 version, there are a couple of thing a developer should do :<br />
<br />
* '''Update the JS file using the JavaScript API'''<br />
<br />
* '''Update the JSON file with proper calls for JavaScript functions'''<br />
<br />
For UI5 version, the JavaScript functions were called in JSON file like this :<br />
<br />
'''"ScriptName": "Your_JS_File.js",'''<br />
<br />
'''"Function": "Your_Function_Name"'''<br />
<br />
Example: Home Care Plugin - JSON file:<br />
<br />
<source lang="javascript"><br />
{<br />
"Label": {<br />
"lang_tag": "users",<br />
"text": "Users"<br />
},<br />
"TopNavigationTab": "1",<br />
"Position": "0",<br />
"TabType": "javascript",<br />
"ScriptName": "J_HomeCare.js",<br />
"Function": "ShowUsers"<br />
},<br />
</source><br />
<br />
For UI7, the JavaScript functions are called like this : <br />
<br />
'''"ScriptName": "Your_JS_File_for_UI7.js",'''<br />
<br />
'''"Function": "Your_Class_Name.Your_Function_Name"'''<br />
<br />
Example:<br />
<br />
<source lang="javascript"><br />
{<br />
"Label": {<br />
"lang_tag": "users",<br />
"text": "Users"<br />
},<br />
"TopNavigationTab": "1",<br />
"Position": "0",<br />
"TabType": "javascript",<br />
"ScriptName": "J_HomeCare_UI7.js",<br />
"Function": "HomeCare.ShowUsers"<br />
},<br />
</source><br />
<br />
By now, you should be asking yourself: "How plugin will work on UI5 if I update these files?". If you answer by yourself and the answer is : "It won't work", you are right. For this you will need to do an additional step:<br />
<br />
*'''Create different JSON and JS files and perform a check in your Luup code'''<br />
**As you can see in the above example for JSON file, our choice was to add "''_UI7''" for our JS file : "''J_HomeCare_UI7.js''". We suggest you to do the same, but this is not a requirement. We did the same with JSON file : "''D_HomeCare_UI7.json''"<br />
**In order to use the new JSON and JS files in UI7 instead of UI5 versions, "device_json" attribute of your device must set with the JSON file for UI7. For this, you can use the following function:<br />
<source lang="lua"> <br />
local function checkVersion()<br />
local ui7Check = luup.variable_get(SID, "UI7Check", lug_device) or ""<br />
if ui7Check == "" then<br />
luup.variable_set(SID, "UI7Check", "false", lug_device)<br />
ui7Check = "false"<br />
end<br />
if( luup.version_branch == 1 and luup.version_major == 7 and ui7Check == "false") then<br />
luup.variable_set(SID, "UI7Check", "true", lug_device)<br />
luup.attr_set("device_json", "Your_UI7_JSON_File", lug_device)<br />
luup.reload()<br />
end<br />
end<br />
</source><br />
''SID'' - your Service ID; ''lug_device'' - your device ID; <br />
**Call ''checkVersion()'' in your initialization function, before doing something else.<br />
<br />
=== HomeCare Plugin - updated for UI7 ===<br />
<br />
We use the HomeCare plugin as example for what need to be added/updated for UI7. Below you can download plugin files:<br />
<br />
[[File:HomeCare.zip]]<br />
<br />
This is the published version of HomeCare plugin that can be downloaded from our appstore. This version is compatible with both UI5 and UI7.</div>Andreimioshttp://wiki.mios.com/index.php/Luup_DevicesLuup Devices2014-12-19T07:49:37Z<p>Andreimios: /* Sensor - Temperature */</p>
<hr />
<div>[[Category:Development]]<br />
== Home Automation Device ==<br />
The generic device type that all MiOS devices implement.<br />
===Service===<br />
*urn:micasaverde-com:serviceId:HaDevice1<br />
===Variables===<br />
===Actions===<br />
== Switch ==<br />
A binary switch, for an appliance, florescent light, or a relay.<br />
===Service===<br />
*urn:upnp-org:serviceId:SwitchPower1<br />
===Variables===<br />
====Status====<br />
The state of the device. 1 is on, 0 is off.<br />
===Actions===<br />
====SetTarget====<br />
Sets the target state of the switch<br />
<br />
'''Arguments:''' newTargetValue (Integer)<br />
<br />
newTargetValue: 1 for on, 0 for off.<br />
<br />
== Dimmer ==<br />
A dimmable light.<br />
===Service===<br />
*urn:upnp-org:serviceId:Dimming1<br />
===Variables===<br />
newTargetValue: an integer between 0 and 100 indicating the desired % of lighting.<br />
===Actions===<br />
====SetLoadLevelTarget====<br />
Sets the desired brightness or load level for the dimming device.<br />
<br />
<br />
'''Arguments:''' newLoadlevelTarget(Integer)<br />
<br />
newLoadlevelTarget: an integer between 0 and 100 indicating the desired % of lighting/load.<br />
<br />
== Sensor ==<br />
A security sensor, or any device that can be "tripped"<br />
===Service===<br />
*urn:micasaverde-com:serviceId:SecuritySensor<br />
===Variables===<br />
====Armed====<br />
An integer. 1 for armed, 0 for disarmed. This is an internal state variable of the MiOS engine and has nothing to do with the state of the sensor.<br />
====Tripped====<br />
An integer. 1 for tripped, 0 for not.<br />
====LastTrip====<br />
An integer with the UNIX timestamp of the last trip event that the MiOS engine recorded.<br />
===Actions===<br />
====SetArmed====<br />
Sets the armed state of the sensor.<br />
<br />
'''Arguments:''' newArmedValue(Integer)<br />
<br />
newArmedValue: 1 for armed, 0 for disarmed.<br />
== HVAC/Climate ==<br />
<br />
=== Service ===<br />
<br />
*urn:upnp-org:serviceId:HVAC_UserOperatingMode1 <br />
**For action SetModeTarget <br />
*urn:upnp-org:serviceId:TemperatureSetpoint1_Heat <br />
**For action NewCurrentSetpoint <br />
*urn:upnp-org:serviceId:TemperatureSetpoint1_Cool <br />
**For action NewCurrentSetpoint <br />
*urn:upnp-org:serviceId:HVAC_FanOperatingMode1 <br />
**For action SetMode<br />
<br />
=== Variables ===<br />
<br />
==== urn:upnp-org:serviceId:HVAC_UserOperatingMode1 -- ModeStatus ====<br />
<br />
One of Off, HeatOn, CoolOn, or AutoChangeOver depending on the User operation mode of the thermostat. <br />
<br />
==== urn:upnp-org:serviceId:HVAC_FanOperatingMode1 -- Mode ====<br />
<br />
One of Auto, ContinuousOn, or PeriodicOn depending on the fan mode of the thermostat.<br />
<br />
==== urn:upnp-org:serviceId:TemperatureSensor1 -- CurrentTemperature ====<br />
<br />
An integer value representing the temperature that the thermostat is reporting. <br />
<br />
==== urn:upnp-org:serviceId:TemperatureSetpoint1_Heat -- CurrentSetpoint ====<br />
<br />
An integer value representing the heat setpoint for the thermostat <br />
<br />
==== urn:upnp-org:serviceId:TemperatureSetpoint1_Cool -- CurrentSetpoint ====<br />
<br />
An integer value representing the cool setpoint for the thermostat <br />
<br />
=== Actions ===<br />
<br />
==== SetModeTarget ====<br />
<br />
Sets the desired operation mode for the thermostat. <br />
<br />
'''Arguments:''' NewModeTarget(String) <br />
<br />
NewModeTarget: One of Off, CoolOn, HeatOn, or AutoChangeOver. <br />
<br />
==== SetCurrentSetpoint ====<br />
<br />
Sets the desired setpoint. User serviceId urn:upnp-org:serviceId:TemperatureSetpoint1_Heat for heat and urn:upnp-org:serviceId:TemperatureSetpoint1_Cool for cooling <br />
<br />
'''Arguments:''' NewCurrentSetpoint(Integer) <br />
<br />
NewCurrentSetpoint: An integer value between 0 and 100 specifying the desired heat or cooling setpoint. <br />
<br />
==== SetMode ====<br />
<br />
Sets the fan operation mode for the thermostat <br />
<br />
'''Arguments:''' NewMode(String) <br />
<br />
NewMode: One of ContinuousOn or Auto, depending on the desired mode of operation for the HVAC system's fan. <br />
<br />
=== Examples ===<br />
<br />
Set Thermostat #4 to Cool: veraIP:3480/data_request?id=lu_action&amp;DeviceNum=4&amp;serviceId=urn:upnp-org:serviceId:HVAC_UserOperatingMode1&amp;action=SetModeTarget&amp;NewModeTarget=CoolOn <br />
<br />
Set Thermostat #98 cool setpoint to 70: veraIP:3480/data_request?id=lu_action&amp;DeviceNum=98&amp;serviceId=urn:upnp-org:serviceId:TemperatureSetpoint1_Cool&amp;action=SetCurrentSetpoint&amp;NewCurrentSetpoint=70<br />
<br />
== Lock ==<br />
Lorem ipsum dolor sit amet, ultricies ligula ligula maecenas, sed laboriosam erat.<br />
===Service===<br />
urn:micasaverde-com:serviceId:DoorLock1<br />
===Variables===<br />
====Status====<br />
1 for locked, 0 for unlocked<br />
===Actions===<br />
====SetTarget====<br />
Sets the desired lock state of the door lock<br />
<br />
'''Arguments:''' newTargetValue(integer)<br />
<br />
newTargetValue: 1 for lock, 0 for unlock<br />
== Window Covering ==<br />
Blinds and shades.<br />
===Service===<br />
*urn:upnp-org:serviceId:WindowCovering1<br />
*urn:upnp-org:serviceId:SwitchPower1<br />
**Supports the same actions and variables as a switch. On is closed, Off is open.<br />
===Actions===<br />
====Up====<br />
Moves the covering up.<br />
====Down====<br />
Moves the covering down.<br />
====Stop====<br />
Stops the covering moving.<br />
== Sensor - Humidity ==<br />
A humidity sensor.<br />
===Service===<br />
urn:micasaverde-com:serviceId:HumiditySensor1<br />
===Variables===<br />
CurrentLevel(Integer): The current humidity level that the sensor is reporting.<br />
== Sensor - Temperature ==<br />
A temperature sensor.<br />
===Service===<br />
urn:upnp-org:serviceId:TemperatureSensor1<br />
===Variables===<br />
CurrentTemperature(Integer): The current temperature in degrees the sensor is reporting.<br />
<br />
== Sensor - Light ==<br />
A light sensor.<br />
===Service===<br />
urn:schemas-micasaverde-com:service:LightSensor:1<br />
===Variables===<br />
CurrentLevel(Integer): The current light level that the sensor is reporting.<br />
<br />
== Power Meter ==<br />
A power meter or a device that can display power usage.<br />
===Service===<br />
urn:micasaverde-com:serviceId:EnergyMetering1<br />
===Variables===<br />
Watts(Integer): The energy draw the meter is recording, in watts.</div>Andreimioshttp://wiki.mios.com/index.php/Luup_DevicesLuup Devices2014-12-19T07:49:20Z<p>Andreimios: /* Sensor - Light */</p>
<hr />
<div>[[Category:Development]]<br />
== Home Automation Device ==<br />
The generic device type that all MiOS devices implement.<br />
===Service===<br />
*urn:micasaverde-com:serviceId:HaDevice1<br />
===Variables===<br />
===Actions===<br />
== Switch ==<br />
A binary switch, for an appliance, florescent light, or a relay.<br />
===Service===<br />
*urn:upnp-org:serviceId:SwitchPower1<br />
===Variables===<br />
====Status====<br />
The state of the device. 1 is on, 0 is off.<br />
===Actions===<br />
====SetTarget====<br />
Sets the target state of the switch<br />
<br />
'''Arguments:''' newTargetValue (Integer)<br />
<br />
newTargetValue: 1 for on, 0 for off.<br />
<br />
== Dimmer ==<br />
A dimmable light.<br />
===Service===<br />
*urn:upnp-org:serviceId:Dimming1<br />
===Variables===<br />
newTargetValue: an integer between 0 and 100 indicating the desired % of lighting.<br />
===Actions===<br />
====SetLoadLevelTarget====<br />
Sets the desired brightness or load level for the dimming device.<br />
<br />
<br />
'''Arguments:''' newLoadlevelTarget(Integer)<br />
<br />
newLoadlevelTarget: an integer between 0 and 100 indicating the desired % of lighting/load.<br />
<br />
== Sensor ==<br />
A security sensor, or any device that can be "tripped"<br />
===Service===<br />
*urn:micasaverde-com:serviceId:SecuritySensor<br />
===Variables===<br />
====Armed====<br />
An integer. 1 for armed, 0 for disarmed. This is an internal state variable of the MiOS engine and has nothing to do with the state of the sensor.<br />
====Tripped====<br />
An integer. 1 for tripped, 0 for not.<br />
====LastTrip====<br />
An integer with the UNIX timestamp of the last trip event that the MiOS engine recorded.<br />
===Actions===<br />
====SetArmed====<br />
Sets the armed state of the sensor.<br />
<br />
'''Arguments:''' newArmedValue(Integer)<br />
<br />
newArmedValue: 1 for armed, 0 for disarmed.<br />
== HVAC/Climate ==<br />
<br />
=== Service ===<br />
<br />
*urn:upnp-org:serviceId:HVAC_UserOperatingMode1 <br />
**For action SetModeTarget <br />
*urn:upnp-org:serviceId:TemperatureSetpoint1_Heat <br />
**For action NewCurrentSetpoint <br />
*urn:upnp-org:serviceId:TemperatureSetpoint1_Cool <br />
**For action NewCurrentSetpoint <br />
*urn:upnp-org:serviceId:HVAC_FanOperatingMode1 <br />
**For action SetMode<br />
<br />
=== Variables ===<br />
<br />
==== urn:upnp-org:serviceId:HVAC_UserOperatingMode1 -- ModeStatus ====<br />
<br />
One of Off, HeatOn, CoolOn, or AutoChangeOver depending on the User operation mode of the thermostat. <br />
<br />
==== urn:upnp-org:serviceId:HVAC_FanOperatingMode1 -- Mode ====<br />
<br />
One of Auto, ContinuousOn, or PeriodicOn depending on the fan mode of the thermostat.<br />
<br />
==== urn:upnp-org:serviceId:TemperatureSensor1 -- CurrentTemperature ====<br />
<br />
An integer value representing the temperature that the thermostat is reporting. <br />
<br />
==== urn:upnp-org:serviceId:TemperatureSetpoint1_Heat -- CurrentSetpoint ====<br />
<br />
An integer value representing the heat setpoint for the thermostat <br />
<br />
==== urn:upnp-org:serviceId:TemperatureSetpoint1_Cool -- CurrentSetpoint ====<br />
<br />
An integer value representing the cool setpoint for the thermostat <br />
<br />
=== Actions ===<br />
<br />
==== SetModeTarget ====<br />
<br />
Sets the desired operation mode for the thermostat. <br />
<br />
'''Arguments:''' NewModeTarget(String) <br />
<br />
NewModeTarget: One of Off, CoolOn, HeatOn, or AutoChangeOver. <br />
<br />
==== SetCurrentSetpoint ====<br />
<br />
Sets the desired setpoint. User serviceId urn:upnp-org:serviceId:TemperatureSetpoint1_Heat for heat and urn:upnp-org:serviceId:TemperatureSetpoint1_Cool for cooling <br />
<br />
'''Arguments:''' NewCurrentSetpoint(Integer) <br />
<br />
NewCurrentSetpoint: An integer value between 0 and 100 specifying the desired heat or cooling setpoint. <br />
<br />
==== SetMode ====<br />
<br />
Sets the fan operation mode for the thermostat <br />
<br />
'''Arguments:''' NewMode(String) <br />
<br />
NewMode: One of ContinuousOn or Auto, depending on the desired mode of operation for the HVAC system's fan. <br />
<br />
=== Examples ===<br />
<br />
Set Thermostat #4 to Cool: veraIP:3480/data_request?id=lu_action&amp;DeviceNum=4&amp;serviceId=urn:upnp-org:serviceId:HVAC_UserOperatingMode1&amp;action=SetModeTarget&amp;NewModeTarget=CoolOn <br />
<br />
Set Thermostat #98 cool setpoint to 70: veraIP:3480/data_request?id=lu_action&amp;DeviceNum=98&amp;serviceId=urn:upnp-org:serviceId:TemperatureSetpoint1_Cool&amp;action=SetCurrentSetpoint&amp;NewCurrentSetpoint=70<br />
<br />
== Lock ==<br />
Lorem ipsum dolor sit amet, ultricies ligula ligula maecenas, sed laboriosam erat.<br />
===Service===<br />
urn:micasaverde-com:serviceId:DoorLock1<br />
===Variables===<br />
====Status====<br />
1 for locked, 0 for unlocked<br />
===Actions===<br />
====SetTarget====<br />
Sets the desired lock state of the door lock<br />
<br />
'''Arguments:''' newTargetValue(integer)<br />
<br />
newTargetValue: 1 for lock, 0 for unlock<br />
== Window Covering ==<br />
Blinds and shades.<br />
===Service===<br />
*urn:upnp-org:serviceId:WindowCovering1<br />
*urn:upnp-org:serviceId:SwitchPower1<br />
**Supports the same actions and variables as a switch. On is closed, Off is open.<br />
===Actions===<br />
====Up====<br />
Moves the covering up.<br />
====Down====<br />
Moves the covering down.<br />
====Stop====<br />
Stops the covering moving.<br />
== Sensor - Humidity ==<br />
A humidity sensor.<br />
===Service===<br />
urn:micasaverde-com:serviceId:HumiditySensor1<br />
===Variables===<br />
CurrentLevel(Integer): The current humidity level that the sensor is reporting.<br />
== Sensor - Temperature ==<br />
A temperature sensor.<br />
===Service===<br />
urn:upnp-org:serviceId:TemperatureSensor1<br />
===Variables===<br />
CurrentLevel(Integer): The current temperature in degrees the sensor is reporting.<br />
== Sensor - Light ==<br />
A light sensor.<br />
===Service===<br />
urn:schemas-micasaverde-com:service:LightSensor:1<br />
===Variables===<br />
CurrentLevel(Integer): The current light level that the sensor is reporting.<br />
<br />
== Power Meter ==<br />
A power meter or a device that can display power usage.<br />
===Service===<br />
urn:micasaverde-com:serviceId:EnergyMetering1<br />
===Variables===<br />
Watts(Integer): The energy draw the meter is recording, in watts.</div>Andreimioshttp://wiki.mios.com/index.php/Luup_DevicesLuup Devices2014-12-19T07:47:24Z<p>Andreimios: /* Sensor - Light */</p>
<hr />
<div>[[Category:Development]]<br />
== Home Automation Device ==<br />
The generic device type that all MiOS devices implement.<br />
===Service===<br />
*urn:micasaverde-com:serviceId:HaDevice1<br />
===Variables===<br />
===Actions===<br />
== Switch ==<br />
A binary switch, for an appliance, florescent light, or a relay.<br />
===Service===<br />
*urn:upnp-org:serviceId:SwitchPower1<br />
===Variables===<br />
====Status====<br />
The state of the device. 1 is on, 0 is off.<br />
===Actions===<br />
====SetTarget====<br />
Sets the target state of the switch<br />
<br />
'''Arguments:''' newTargetValue (Integer)<br />
<br />
newTargetValue: 1 for on, 0 for off.<br />
<br />
== Dimmer ==<br />
A dimmable light.<br />
===Service===<br />
*urn:upnp-org:serviceId:Dimming1<br />
===Variables===<br />
newTargetValue: an integer between 0 and 100 indicating the desired % of lighting.<br />
===Actions===<br />
====SetLoadLevelTarget====<br />
Sets the desired brightness or load level for the dimming device.<br />
<br />
<br />
'''Arguments:''' newLoadlevelTarget(Integer)<br />
<br />
newLoadlevelTarget: an integer between 0 and 100 indicating the desired % of lighting/load.<br />
<br />
== Sensor ==<br />
A security sensor, or any device that can be "tripped"<br />
===Service===<br />
*urn:micasaverde-com:serviceId:SecuritySensor<br />
===Variables===<br />
====Armed====<br />
An integer. 1 for armed, 0 for disarmed. This is an internal state variable of the MiOS engine and has nothing to do with the state of the sensor.<br />
====Tripped====<br />
An integer. 1 for tripped, 0 for not.<br />
====LastTrip====<br />
An integer with the UNIX timestamp of the last trip event that the MiOS engine recorded.<br />
===Actions===<br />
====SetArmed====<br />
Sets the armed state of the sensor.<br />
<br />
'''Arguments:''' newArmedValue(Integer)<br />
<br />
newArmedValue: 1 for armed, 0 for disarmed.<br />
== HVAC/Climate ==<br />
<br />
=== Service ===<br />
<br />
*urn:upnp-org:serviceId:HVAC_UserOperatingMode1 <br />
**For action SetModeTarget <br />
*urn:upnp-org:serviceId:TemperatureSetpoint1_Heat <br />
**For action NewCurrentSetpoint <br />
*urn:upnp-org:serviceId:TemperatureSetpoint1_Cool <br />
**For action NewCurrentSetpoint <br />
*urn:upnp-org:serviceId:HVAC_FanOperatingMode1 <br />
**For action SetMode<br />
<br />
=== Variables ===<br />
<br />
==== urn:upnp-org:serviceId:HVAC_UserOperatingMode1 -- ModeStatus ====<br />
<br />
One of Off, HeatOn, CoolOn, or AutoChangeOver depending on the User operation mode of the thermostat. <br />
<br />
==== urn:upnp-org:serviceId:HVAC_FanOperatingMode1 -- Mode ====<br />
<br />
One of Auto, ContinuousOn, or PeriodicOn depending on the fan mode of the thermostat.<br />
<br />
==== urn:upnp-org:serviceId:TemperatureSensor1 -- CurrentTemperature ====<br />
<br />
An integer value representing the temperature that the thermostat is reporting. <br />
<br />
==== urn:upnp-org:serviceId:TemperatureSetpoint1_Heat -- CurrentSetpoint ====<br />
<br />
An integer value representing the heat setpoint for the thermostat <br />
<br />
==== urn:upnp-org:serviceId:TemperatureSetpoint1_Cool -- CurrentSetpoint ====<br />
<br />
An integer value representing the cool setpoint for the thermostat <br />
<br />
=== Actions ===<br />
<br />
==== SetModeTarget ====<br />
<br />
Sets the desired operation mode for the thermostat. <br />
<br />
'''Arguments:''' NewModeTarget(String) <br />
<br />
NewModeTarget: One of Off, CoolOn, HeatOn, or AutoChangeOver. <br />
<br />
==== SetCurrentSetpoint ====<br />
<br />
Sets the desired setpoint. User serviceId urn:upnp-org:serviceId:TemperatureSetpoint1_Heat for heat and urn:upnp-org:serviceId:TemperatureSetpoint1_Cool for cooling <br />
<br />
'''Arguments:''' NewCurrentSetpoint(Integer) <br />
<br />
NewCurrentSetpoint: An integer value between 0 and 100 specifying the desired heat or cooling setpoint. <br />
<br />
==== SetMode ====<br />
<br />
Sets the fan operation mode for the thermostat <br />
<br />
'''Arguments:''' NewMode(String) <br />
<br />
NewMode: One of ContinuousOn or Auto, depending on the desired mode of operation for the HVAC system's fan. <br />
<br />
=== Examples ===<br />
<br />
Set Thermostat #4 to Cool: veraIP:3480/data_request?id=lu_action&amp;DeviceNum=4&amp;serviceId=urn:upnp-org:serviceId:HVAC_UserOperatingMode1&amp;action=SetModeTarget&amp;NewModeTarget=CoolOn <br />
<br />
Set Thermostat #98 cool setpoint to 70: veraIP:3480/data_request?id=lu_action&amp;DeviceNum=98&amp;serviceId=urn:upnp-org:serviceId:TemperatureSetpoint1_Cool&amp;action=SetCurrentSetpoint&amp;NewCurrentSetpoint=70<br />
<br />
== Lock ==<br />
Lorem ipsum dolor sit amet, ultricies ligula ligula maecenas, sed laboriosam erat.<br />
===Service===<br />
urn:micasaverde-com:serviceId:DoorLock1<br />
===Variables===<br />
====Status====<br />
1 for locked, 0 for unlocked<br />
===Actions===<br />
====SetTarget====<br />
Sets the desired lock state of the door lock<br />
<br />
'''Arguments:''' newTargetValue(integer)<br />
<br />
newTargetValue: 1 for lock, 0 for unlock<br />
== Window Covering ==<br />
Blinds and shades.<br />
===Service===<br />
*urn:upnp-org:serviceId:WindowCovering1<br />
*urn:upnp-org:serviceId:SwitchPower1<br />
**Supports the same actions and variables as a switch. On is closed, Off is open.<br />
===Actions===<br />
====Up====<br />
Moves the covering up.<br />
====Down====<br />
Moves the covering down.<br />
====Stop====<br />
Stops the covering moving.<br />
== Sensor - Humidity ==<br />
A humidity sensor.<br />
===Service===<br />
urn:micasaverde-com:serviceId:HumiditySensor1<br />
===Variables===<br />
CurrentLevel(Integer): The current humidity level that the sensor is reporting.<br />
== Sensor - Temperature ==<br />
A temperature sensor.<br />
===Service===<br />
urn:upnp-org:serviceId:TemperatureSensor1<br />
===Variables===<br />
CurrentLevel(Integer): The current temperature in degrees the sensor is reporting.<br />
== Sensor - Light ==<br />
A light sensor.<br />
===Service===<br />
urn:schemas-micasaverde-com:service:LightSensor:1<br />
===Variables===<br />
CurrentTemperature(Integer): The current light level that the sensor is reporting.<br />
<br />
== Power Meter ==<br />
A power meter or a device that can display power usage.<br />
===Service===<br />
urn:micasaverde-com:serviceId:EnergyMetering1<br />
===Variables===<br />
Watts(Integer): The energy draw the meter is recording, in watts.</div>Andreimioshttp://wiki.mios.com/index.php/JavaScript_APIJavaScript API2014-11-19T16:06:42Z<p>Andreimios: </p>
<hr />
<div>== Usage ==<br />
<pre>"Tabs": [<br />
{<br />
"Label": {<br />
"lang_tag": "users",<br />
"text": "Users" <br />
},<br />
"Position": "0",<br />
"TabType": "javascript",<br />
"ScriptName": "I_HomeCare.js",<br />
"Function": "showUsers"<br />
}, </pre> <br />
To generate a tab using your JavaScript functions you need to specify this by setting ''TabType'' to '''''javascript'''''. Then, you need to specify the script file's name and which function in this file will be used to draw the tab's content. That function will have one argument, which is the device number.<br> <br />
<br />
==== &lt;functionName&gt; (deviceNumber) ====<br />
<br />
This is the tab rendering function. The [[#set_panel_html_.28html.29 | set_panel_html]] function must be called at the end.<br> <br />
<br />
'''Input:''' <br />
<br />
*deviceNumber (number)<br><br />
<br />
'''Output:''' <br />
<br />
*nothing<br />
<br />
<br><br />
<br />
== Variables ==<br />
<br />
==== jsonp.ud ====<br />
<br />
This is the user data. <br />
<br />
*'''Type''': object <br />
*'''Members''': <br />
**devices (array) <br />
**scenes (array) <br />
**users (array) <br />
**rooms (array) <br />
**eventList (array) <br />
**etc.<br />
<br />
<br> <br />
<br />
==== jsonp.ud.devices ====<br />
<br />
*'''Type''': array <br />
*'''Members''': <br />
**id (number) <br />
**device_type (string) <br />
**room (number) <br />
**name (string) <br />
**category_num (number) <br />
**etc.<br />
<br />
<br> <br />
<br />
==== jsonp.ud.scenes ====<br />
<br />
*'''Type''': array <br />
*'''Members''': <br />
**id (number) <br />
**name (string) <br />
**room (number) <br />
**Timer_ids (array) <br />
**Timer (object) <br />
**etc.<br />
<br />
<br> <br />
<br />
== Functions ==<br />
<br />
==== get_device_state (deviceId, serviceId, variable, dynamic) ====<br />
<br />
'''Input:''' <br />
<br />
*deviceId (number)<br />
*serviceId (string)<br />
*variable (string)<br />
*dynamic (number): if '''1''', the variable's value is taken from ''lu_status'', else, the variable's value is taken from ''user_data''. ''user_data'' is read at Luup startup, so for variables that change their value frequently (like Watts, Temperature, etc.) ''dynamic'' should be '''1'''.<br />
<br />
'''Output:''' <br />
<br />
*variable value (string or ''undefined'')<br />
<br />
<br><br />
<br />
==== set_device_state (deviceId, serviceId, variable, value, dynamic) ====<br />
<br />
'''Input:''' <br />
<br />
*deviceId (number)<br />
*serviceId (string)<br />
*variable (string)<br />
*value (string)<br />
*dynamic (number): if '''1''', the variable's value is saved to ''lu_status'' (the value is lost after Luup is restarted), else, the variable's value is saved to a copy of ''user_data''; the real user_data is updated when LuaUPnP is restarted.<br />
<br />
'''Output:''' <br />
<br />
*''true'' if the operation succeeded, ''false'' otherwise<br />
<br />
<br><br />
<br />
==== _console (str) ====<br />
<br />
'''Input:''' <br />
<br />
*str (string): text to be written in the console. You need to have FireBug installed in order to have a console.<br />
<br />
'''Output:''' <br />
<br />
*nothing<br />
<br />
<br><br />
<br />
==== set_panel_html (html) ====<br />
<br />
Used in the tab rendering functions. <br />
<br />
'''Input:''' <br />
<br />
*html (string): The html to be used for generating the tab content.<br />
<br />
'''Output:''' <br />
<br />
*nothing<br />
<br />
[[Category:Development]]<br />
<br />
= JavaScript API for UI7 =<br />
<br />
== Introduction ==<br />
<br />
One of the new features of UI7 is the Javascript API for writing plugins. This is a free programming interface which is robust, well documented and comes with a guarantee that it will be compatible with the following UI releases.<br />
<br />
'''''What is this “API” ?'''''<br />
<br />
Simply said: it is a layer between the UI and the plugin developer. This way, the developer can use the features available in the UI by interacting only with the API. By using the new features available in the API, the overall user experience can be visibly improved.<br />
<br />
'''''How does it work ?'''''<br />
<br />
The API comes in the form of a library which exposes to the developer the objects and methods/functions needed to implement functionality in their plugins.<br />
<br />
'''''How is this different from the previous way of writing plugins ?'''''<br />
<br />
The developers were writing Javascript code and they had full access to the core of the application. There were a couple of objects and functions written by the UI team which were easing the work for the developer.<br />
By using the new API, the developer can write code without interfering with the core of the application.<br />
<br />
'''''What is new ?'''''<br />
<br />
* The developer can write the plugin without interfering with any other code except the API. This means there are a great bundle of methods like setters and getters which help writing good code.<br />
* UI team can make any changes to the core of the application, but as long as the API stays the same, the plugins will work. This way, the application can be improved and the developer won’t have to fix the code in order for it to work. New versions of the UI can be launched and the plugins will be compatible.<br />
* Event handling - the application will notify the plugin (via the API) about the events that happen inside. Consider, for example, the addition of a new device to the unit. The developer will know, by simply listening to an event, that a device was added and so, (s)he will write the code in such a way that it will take into account the event. The user experience will be greatly improved.<br />
* Asynchronous getters and setters - because most of the actions that happen inside the UI is asynchronous, so are the API’s method written. Most of them have a signature like this: function getXXX(obj, onSuccess, onFailure), where ‘onSuccess’ and ‘onFailure’ are callback functions which are called based on the result of the call.<br />
* No more global variables to manipulate. Everything is handled through getters/setters via API.<br />
* An API reference documentation: every method and its parameters is carefully documented so that the developer would know what the function does, how to call it and what it will return.<br />
* A couple of guidelines will be given to help developers write better code in such a way that two different plugins won’t “harm” each other. The module pattern will be used as a design pattern in order to put a plugin code inside a namespace. Also, this module helps in writing code which is easier to read and use.<br />
* It will be easier for the developers to write the code by using a new feature in the UI which generates the skeleton for the plugin.<br />
<br />
'''''What is the API reference documentation ?'''''<br />
<br />
This is the part which makes the API usable. Every aspect of the API, no matter how trivial, will be stated explicitly. It contains:<br />
<br />
* a description of all the data structures it depends upon<br />
* a description of all the function signatures:<br />
** function names<br />
** function parameters (names and types)<br />
** return type of the function<br />
** if it throws any exceptions or not<br />
<br />
'''''Where is the list of functions which were replaced ?'''''<br />
<br />
In the API reference documentation the developer can find out if a function replaces an old one.<br />
<br />
'''''Why should a developer write plugins using the API when it can do some “reverse engineering” and directly access any object/functionality of the application ?'''''<br />
<br />
It is not mandatory to write the code for the plugin this way. Probably the plugin will work as long as changes are not made in the core of the application, but the API comes also with a guarantee that after application changes, the plugins will continue to work. The UI team and plugin developers have the same goal: to deliver the best experience to the user. This is where the API comes into place - an interface between the two.<br />
<br />
'''''Will the API be rewritten with each new UI release ?'''''<br />
<br />
No. It will be improved. The goal of the API is to provide a stable interface to the developer so that when changing the core of the application it won’t be necessary to rewrite the plugins.<br />
<br />
'''''Is this API going to change in the near future ?'''''<br />
<br />
It can be changed. There will be parts of it which are going to be marked as ‘deprecated’. This means that the parts will be candidates for being removed, or modified in a backward incompatible way. The developers will be advised on how are they to change their code in order to use the features which replace the deprecated parts.<br />
<br />
'''''Is the API complete ?'''''<br />
<br />
Almost. Most of the functionality is there, but developers are encouraged to request new features from the API which will be added in future releases.<br />
<br />
== Guidelines on writing Javascript code for plugins in UI7 ==<br />
<br />
* Use the module pattern to organize your code inside a namespace. Choose a well defined name for your namespace.<br />
* Generate an UUID for your plugin. This way you can use the events engine.<br />
* Use the provided API plugins to perform most of your stuff. If you can’t find an implemented method inside the API you can ASK for an implementation to it.<br />
* '''NEVER USE''' variables/functions which are not accessible through API ! They can be changed or removed at any time.<br />
* If you need to do a background job (ex: start a timer), use the events engine and register a ‘cleanup’ function in which you finish the job (clear the timer).<br />
* We encourage the use of try { … } catch { … } blocks everywhere in your functions so that errors don’t get propagated to the top of the application.<br />
* Start from the skeleton provided and expand it:<br />
<br />
<source lang="javascript"><br />
var MyPlugin = (function (api) {<br />
// example of unique identifier for this plugin...<br />
var uuid = 'B971F6C4-F315-4E2E-AD08-F029A9777517';<br />
<br />
var myModule = {};<br />
<br />
function doSomething() {<br />
// register to event ‘on_ui_cpanel_before_close’...<br />
api.registerEventHandler('on_ui_cpanel_before_close', myModule, ‘cleanUp’);<br />
// and do something... <br />
}<br />
<br />
function cleanUp() {<br />
// perform clean up...<br />
}<br />
<br />
myModule = {<br />
uuid: uuid,<br />
doSomething: doSomething,<br />
cleanUp: cleanUp<br />
};<br />
return myModule;<br />
})(api);<br />
</source><br />
<br />
Your plugin functions will be accessible via ''MyPlugin.doSomething()'' construction.<br />
When the user will leave the cpanel, your plugin will be noticed via event ''‘on_ui_cpanel_before_close’''; this way you can perform the necessary cleanup.<br />
<br />
== JavaScript API ==<br />
<br />
''Defined in'': api.js<br />
<br />
=== Class Summary ===<br />
<br />
----<br />
<br />
'''API(config, application, ui)''' <br />
<br />
- API class for plugins<br />
<br />
'''Parameters:'''<br />
<br />
* {object} config - holds configuration data<br />
* {object} application - application layer<br />
* {object} ui - interface<br />
<br />
=== Method Summary ===<br />
<br />
----<br />
<br />
==== {Object} cloneObject(obj) ====<br />
<br />
- Clones a given object<br />
<br />
- Replaces: cloneObject()<br />
<br />
'''Parameters:'''<br />
<br />
* {object} obj - object to be cloned<br />
<br />
'''Returns:'''<br />
<br />
* {Object}<br />
<br />
==== {*} getCommandURL() ==== <br />
<br />
- Retrieves command URL<br />
<br />
- Replaces: command_url<br />
<br />
'''Returns:'''<br />
<br />
* {*}<br />
<br />
==== {string} getCpanelContent() ====<br />
<br />
- Retrieves cpanel content<br />
<br />
- Replaces: get_panel_html()<br />
<br />
'''Returns:'''<br />
<br />
* {string} HTML code set in cpanel<br />
<br />
==== {number} getCpanelDeviceId() ====<br />
<br />
- Returns device id for current opened cpanel or 0 if not found<br />
<br />
'''Returns:'''<br />
<br />
* {number} - device ID<br />
<br />
==== getCurrentHouseMode(onSuccess, onFailure, context) ====<br />
<br />
- Performs a data request to retrieve the current house mode<br />
<br />
'''Parameters:'''<br />
<br />
* {*} onSuccess Optional - function to be called if the call is successfull<br />
* {*} onFailure Optional - function to be called if the call fails<br />
* {object} context Optional - context in which to execute the functions of success and/or failure<br />
<br />
==== {*} getDataRequestURL() ====<br />
<br />
- Retrieves data request URL<br />
<br />
- Replaces: data_request_url<br />
<br />
'''Returns:'''<br />
<br />
* {*}<br />
<br />
==== {number} getDeviceIndex(deviceId) ====<br />
<br />
- Retrieves device index for given device id<br />
<br />
- Replaces: get_device_index()<br />
<br />
'''Parameters:'''<br />
<br />
* {number} deviceId - id of the device<br />
<br />
'''Returns:'''<br />
<br />
* {number}<br />
<br />
==== {*} getDeviceObject(deviceId) ====<br />
<br />
- Retrieves device object given its id<br />
<br />
- Replaces: get_device_obj()<br />
<br />
'''Parameters:'''<br />
<br />
* {number} deviceId - id of the device<br />
<br />
'''Returns:'''<br />
<br />
* {number}<br />
<br />
===={object} getDeviceState(deviceId, service, variable, options)====<br />
<br />
- Retrieves device state for a device (it can be either read from user data or lu status, depending on the options set)<br />
<br />
'''Parameters:'''<br />
<br />
* {number} deviceId - id of the device<br />
* {string} service - name of the service<br />
* {string} variable - name of the variable<br />
* {object} options Optional - list of options like: 'dynamic': (true - lu_status will be used [default], false - user_data will be used)<br />
<br />
'''Returns:'''<br />
<br />
* {object} value for a given variable<br />
<br />
==== {Object|Boolean} getDeviceTemplate(deviceId) ====<br />
<br />
- Returns device template for a given device id<br />
<br />
'''Parameters:'''<br />
<br />
* {number} deviceId - id of the device<br />
<br />
'''Returns:'''<br />
<br />
* {Object|Boolean}<br />
<br />
==== {*} getDisplayedDeviceName(deviceId) ====<br />
<br />
- Retrieves displayed device name or 'unnamed device' if device doesn't have a name or undefined if device not found<br />
<br />
'''Parameters:'''<br />
<br />
* {number} deviceId - id of the device<br />
<br />
'''Returns:'''<br />
<br />
* {*} if device is found a string which contains the device name or 'Unnamed device' if device name is not set, or undefined if device wasn't found<br />
<br />
==== {*} getEventDefinition(deviceType) ====<br />
<br />
- Retrieves event list for a given device type<br />
<br />
- Replaces: get_event_definition() <br />
<br />
'''Parameters:'''<br />
<br />
* {string} deviceType - type of device<br />
<br />
'''Returns:'''<br />
<br />
* {*}<br />
<br />
==== {*} getListOfDevices() ====<br />
<br />
- Returns the list of devices from userdata<br />
<br />
'''Returns:'''<br />
<br />
* {*}<br />
<br />
==== {Array} getListOfSupportedEvents() ====<br />
<br />
- Returns the list of supported events<br />
<br />
'''Returns:'''<br />
<br />
* {Array} - list containing each event a plugin can subscribe to<br />
<br />
==== getLuSdata(onSuccess, onFailure, context) ====<br />
<br />
- Performs a data request to retrieve lu_sdata<br />
<br />
'''Parameters:'''<br />
<br />
* {*} onSuccess Optional - function to be called if the call is successfull<br />
* {*} onFailure Optional - function to be called if the call fails<br />
* {object} context Optional - context in which to execute the functions of success and/or failure<br />
<br />
==== {*|Object} getRoomObject(roomId) ====<br />
<br />
- Returns room object given a room id<br />
<br />
- Replaces: get_room_by_id()<br />
<br />
'''Parameters:'''<br />
<br />
* {number} roomId - id of the room<br />
<br />
'''Returns:'''<br />
<br />
* {*|Object}<br />
<br />
==== {*} getSysinfo() ====<br />
<br />
- Retrieves sysinfo JSON<br />
<br />
- Replaces: sysinfoJson<br />
<br />
'''Returns:'''<br />
<br />
* {*}<br />
<br />
==== {*} getUserData() ====<br />
<br />
- Retrieves userData or null if error<br />
<br />
- Replaces: jsonp.ud<br />
<br />
'''Returns:'''<br />
<br />
* {*} object containing userdata<br />
<br />
==== performActionOnDevice(deviceId, service, action, options) ====<br />
<br />
- Same as 'performLuActionOnDevice' Performs an action on a device<br />
<br />
'''Parameters:'''<br />
<br />
* {number} deviceId<br />
* {string} service<br />
* {string} action<br />
* {object} options Optional<br />
<br />
- Ex: options can be: { actionArguments: {arg1: 'val1', arg2: 'val2'}, onSuccess: function() {}, onFailure: function() {}, context: that }<br />
<br />
==== performLuActionOnDevice(deviceId, service, action, options) ====<br />
<br />
- Same as 'performActionOnDevice' Performs a lu_action on a device<br />
<br />
'''Parameters:'''<br />
<br />
* {number} deviceId<br />
* {string} service<br />
* {string} action<br />
* {object} options Optional<br />
<br />
- Ex: options can be: { actionArguments: {arg1: 'val1', arg2: 'val2'}, onSuccess: function() {}, onFailure: function() {}, context: that }<br />
<br />
==== registerEventHandler(eventName, object, functionName) ====<br />
<br />
- Register an event handler.<br />
<br />
'''Parameters:'''<br />
<br />
* {string} eventName - name of the event to register to<br />
* {object} object - the object which registers to the event<br />
* {string} functionName - the name of the function to be executed if event triggers<br />
<br />
==== runUpnpCode(code, options, onSuccess, onFailure, context) ====<br />
<br />
- Runs given Upnp code<br />
<br />
'''Parameters:'''<br />
<br />
* {string} code - code to execute<br />
* {object} options Optional - optionally options to be supplied (will be documented later)<br />
* {*} onSuccess Optional - function to be called if the call is successfull<br />
* {*} onFailure Optional - function to be called if the call fails<br />
* {object} context Optional - context in which to execute the functions of success and/or failure<br />
<br />
==== setCpanelContent(html) ====<br />
<br />
- Sets content for the cpanel<br />
<br />
- Replaces: set_panel_html()<br />
<br />
'''Parameters:'''<br />
<br />
* {string} html - the new content of the cpanel<br />
<br />
==== setCurrentHouseMode(modeValue, onSuccess, onFailure, context) ====<br />
<br />
- Sets current house mode<br />
<br />
'''Parameters:'''<br />
<br />
* {number} modeValue - new value for the house mode<br />
* {*} onSuccess Optional - function to be called if the call is successfull<br />
* {*} onFailure Optional - function to be called if the call fails<br />
* {object} context Optional - context in which to execute the functions of success and/or failure<br />
<br />
==== setDeviceStateVariable(deviceId, service, variable, value, onSuccess, onFailure, context) ====<br />
<br />
- Sets state for a device variable using variableset request.<br />
<br />
- Replaces: set_device_state()<br />
<br />
'''Parameters:'''<br />
<br />
* {number} deviceId - id of the device<br />
* {string} service - name of the service<br />
* {string} variable - name of the variable<br />
* {*} value - new value for the variable<br />
* {*} onSuccess Optional - function to be called if the call is successfull<br />
* {*} onFailure Optional - function to be called if the call fails<br />
* {object} context Optional - context in which to execute the functions of success and/or failure<br />
<br />
<br />
=== Events ===<br />
<br />
----<br />
<br />
The list of available events can be obtained with the following command:<br />
<br />
'''api.getListOfSupportedEvents()'''<br />
<br />
* on_startup_showModalLoading<br />
** triggered before loading resources in the browser<br />
*on_startup_luStatusLoaded<br />
** triggered after luStatus was successfully parsed<br />
** parameter: luStatusObject<br />
* on_startup_show2gInterface<br />
** triggered after requesting account devices only if UI is not in ‘local mode’ and ‘slowConnection’ flag is set<br />
* on_ui_requireSave<br />
** triggered if user data was changed and save wasn’t issued<br />
* on_ui_userDataFirstLoaded<br />
** fired if user data was loaded for the first time<br />
* on_ui_staticDataAdded<br />
** fired if static_data was added to user data<br />
** parameter: staticDataObject<br />
* on_ui_staticDataChanged<br />
** fired if static_data was changed after parsing user data<br />
** parameter: changedStaticDataObject<br />
* on_ui_staticDataRemoved<br />
** fired if static_data was removed after parsing user data<br />
** parameter: idForRemovedStaticDataObject<br />
* on_ui_setupDeviceAdded<br />
** fired if new setup device (menu item) is added<br />
** parameter: setupDeviceObject<br />
* on_ui_setupDeviceChanged<br />
** fired if setup device (menu item) is changed<br />
** parameter: changedSetupDeviceObject<br />
* on_ui_setupDeviceRemoved<br />
** fired if setup device (menu item) is removed<br />
** parameter: idForRemovedSetupDeviceObject<br />
* on_ui_sectionAdded<br />
** triggered when new section is added<br />
** parameter: sectionObject<br />
* on_ui_sectionChanged<br />
** fired after section was changed<br />
** parameter: changedSectionObject<br />
* on_ui_sectionRemoved<br />
** fired after section was removed<br />
** parameter: idForRemovedSectionObject<br />
* on_ui_roomAdded<br />
** fired when new room was added to user data<br />
** parameter: roomObject<br />
* on_ui_roomChanged<br />
** fired after room was changed<br />
** parameter: changedRoomObject<br />
* on_ui_roomRemoved<br />
** fired after room was removed from user data<br />
** parameter: idForRemovedRoomObject<br />
* on_ui_deviceAdded<br />
** fired after device was added to user data<br />
** parameter: deviceObject<br />
*** wrapper object for<br />
**** device: this is the actual object representing the device<br />
**** deviceTemplate: object with the static data associated to this device type<br />
* on_ui_deviceChanged<br />
** fired after device was found changed in user data<br />
** parameter: changedDeviceObject<br />
*** wrapper object for<br />
**** device: this is the actual object representing the device<br />
**** deviceTemplate: object with the static data associated to this device type<br />
* on_ui_deviceRemoved<br />
** fired after device was found removed from user data<br />
** parameter: idForRemovedDeviceObject<br />
* on_ui_deviceJobsReceived<br />
** fired when jobs are found for a device in lu_status<br />
** parameter: deviceObjectFromLuStatus<br />
* on_ui_sceneAdded<br />
** fired after scene was added<br />
** parameter: sceneObject<br />
* on_ui_sceneChanged<br />
** fired after scene was changed<br />
** parameter: changedSceneObject<br />
* on_ui_sceneChanged<br />
** fired when scene is removed<br />
** parameter: idForRemovedSceneObject<br />
* on_ui_pluginAdded<br />
** triggered when plugin is added to user data<br />
** parameter: pluginObject<br />
* on_ui_pluginChanged<br />
** triggered when plugin is changed<br />
** parameter: changedPluginObject<br />
* on_ui_pluginRemoved<br />
** triggered when plugin is removed<br />
** parameter: idForRemovedPluginObject<br />
* on_ui_extraSubmenuItemAdded<br />
** triggered when extra submenu item is added<br />
** parameter: extraSubmenuItemObject<br />
*** wrapper for:<br />
**** submenuItem: object containing submenu item<br />
**** deviceType: string which contains the type of device for which the submenu item is added<br />
* on_ui_extraSubmenuItemChanged<br />
** triggered when extra submenu item is changed<br />
** parameter: changedExtraSubmenuItemObject<br />
*** wrapper for:<br />
**** oldObj: contains previous submenu item<br />
**** newObj: wrapper for:<br />
***** submenuItem: object containing submenu item<br />
***** deviceType: string which contains the type of device for which the submenu item is added<br />
* on_ui_extraSubmenuItemRemoved:<br />
** triggered when an extra submenu item is removed<br />
** parameter: idForRemovedExtraSubmenuItemObject<br />
* on_ui_cardAdded<br />
** triggered when card is added to user data<br />
** parameter: cardObject<br />
* on_ui_cardChanged<br />
** triggered when card is found changed in user data<br />
** parameter: changedCardObject<br />
* on_ui_cardRemoved<br />
** triggered when card is removed from user data<br />
** parameter: idForRemovedCardObject<br />
* on_ui_jobsUpdated<br />
** triggered when job is updated in lu_status<br />
** parameter: luStatusJobsObject<br />
* on_ui_deviceStatusChanged<br />
** triggered when device status is changed<br />
** parameter: deviceObjectFromLuStatus<br />
* on_ui_syncClock<br />
** triggered after lu_status is parsed<br />
** parameter: luStatusLocalTime<br />
* on_ui_initFinished<br />
** fired when init has finished (UI should be ready now)<br />
* on_ui_setUserAuthenticated<br />
** fired after login is successful<br />
* on_ui_saveFinished<br />
** fired after save is finished<br />
* on_ui_initNotLogged<br />
** triggered if user is not logged in<br />
* on_ui_alertsUpdated<br />
** fired after alert list was updated<br />
* on_ui_refreshDashboardCards<br />
** triggered when dashboard cards are refreshed<br />
* on_ui_engineAvailable<br />
** triggered if engine is not busy<br />
* on_ui_2GEnabled<br />
** triggered when parsing lu_status if 2G is enabled<br />
* on_ui_userDataSetTemperatureFormat<br />
** triggered after temperature format is set in user data<br />
** parameter: userDataObject<br />
* on_ui_userDataLoaded<br />
** triggered after user data parsing is completed<br />
* on_parseUserData<br />
** triggered when user data parsing is started<br />
* on_ui_accountUnitsLoaded<br />
** fired after account lis from MMS was successfully loaded<br />
* accountInformationLoaded<br />
** triggered after account information is loaded<br />
** parameter: accountInfoObject<br />
* on_ui_finishDrawingMenu<br />
** triggered after parsing of user data setup devices has finished<br />
* on_ui_deviceTypeChanged<br />
** triggered if device type for a device has changed<br />
** parameter: deviceObject<br />
*** wrapper object for<br />
**** device: this is the actual object representing the device<br />
**** deviceTemplate: object with the static data associated to this device type<br />
* on_ui_hideModalLoading<br />
** triggered each time a time consuming job finishes (so that UI can hide modal loading)<br />
* on_ui_showUserDataSaveFailure<br />
** triggered if user data save has failed<br />
* on_ui_showErrorMessage<br />
** fired if application has error message to send to the UI<br />
* on_ui_cpanel_before_close<br />
** fired before closing the cpanel to allow plugins to cleanup their data<br />
** parameters: idForDeviceWhichOpenedTheCpanel<br />
<br />
=== Migration Walkthrough for plugins with JS ===<br />
<br />
With the introduction of our new JavaScript API, plugin mechanism slightly changed. In order to keep a backward compatibility with the UI5 version, there are a couple of thing a developer should do :<br />
<br />
* '''Update the JS file using the JavaScript API'''<br />
<br />
* '''Update the JSON file with proper calls for JavaScript functions'''<br />
<br />
For UI5 version, the JavaScript functions were called in JSON file like this :<br />
<br />
'''"ScriptName": "Your_JS_File.js",'''<br />
<br />
'''"Function": "Your_Function_Name"'''<br />
<br />
Example: Home Care Plugin - JSON file:<br />
<br />
<source lang="javascript"><br />
{<br />
"Label": {<br />
"lang_tag": "users",<br />
"text": "Users"<br />
},<br />
"TopNavigationTab": "1",<br />
"Position": "0",<br />
"TabType": "javascript",<br />
"ScriptName": "J_HomeCare.js",<br />
"Function": "ShowUsers"<br />
},<br />
</source><br />
<br />
For UI7, the JavaScript functions are called like this : <br />
<br />
'''"ScriptName": "Your_JS_File_for_UI7.js",'''<br />
<br />
'''"Function": "Your_Class_Name.Your_Function_Name"'''<br />
<br />
Example:<br />
<br />
<source lang="javascript"><br />
{<br />
"Label": {<br />
"lang_tag": "users",<br />
"text": "Users"<br />
},<br />
"TopNavigationTab": "1",<br />
"Position": "0",<br />
"TabType": "javascript",<br />
"ScriptName": "J_HomeCare_UI7.js",<br />
"Function": "HomeCare.ShowUsers"<br />
},<br />
</source><br />
<br />
By now, you should be asking yourself: "How plugin will work on UI5 if I update these files?". If you answer by yourself and the answer is : "It won't work", you are right. For this you will need to do an additional step:<br />
<br />
*'''Create different JSON and JS files and perform a check in your Luup code'''<br />
**As you can see in the above example for JSON file, our choice was to add "''_UI7''" for our JS file : "''J_HomeCare_UI7.js''". We suggest you to do the same, but this is not a requirement. We did the same with JSON file : "''D_HomeCare_UI7.json''"<br />
**In order to use the new JSON and JS files in UI7 instead of UI5 versions, "device_json" attribute of your device must set with the JSON file for UI7. For this, you can use the following function:<br />
<source lang="lua"> <br />
local function checkVersion()<br />
local ui7Check = luup.variable_get(SID, "UI7Check", lug_device) or ""<br />
if ui7Check == "" then<br />
luup.variable_set(SID, "UI7Check", "false", lug_device)<br />
ui7Check = "false"<br />
end<br />
if( luup.version_branch == 1 and luup.version_major == 7 and ui7Check == "false") then<br />
luup.variable_set(SID, "UI7Check", "true", lug_device)<br />
luup.attr_set("device_json", "Your_UI7_JSON_File", lug_device)<br />
luup.reload()<br />
end<br />
end<br />
</source><br />
''SID'' - your Service ID; ''lug_device'' - your device ID; <br />
**Call ''checkVersion()'' in your initialization function, before doing something else.<br />
<br />
=== HomeCare Plugin - updated for UI7 ===<br />
<br />
We use the HomeCare plugin as example for what need to be added/updated for UI7. Below you can download plugin files:<br />
<br />
[[File:HomeCare.zip]]<br />
<br />
This is the published version of HomeCare plugin that can be downloaded from our appstore. This version is compatible with both UI5 and UI7.</div>Andreimioshttp://wiki.mios.com/index.php/House_ModesHouse Modes2014-11-03T07:19:08Z<p>Andreimios: /* Get “Mode” variable value */</p>
<hr />
<div><br />
==“Mode” top level attribute==<br />
<br />
{| class="wikitable"<br />
|-<br />
! Mode value<br />
! House Mode<br />
|-<br />
|1<br />
|Home<br />
|-<br />
|2<br />
|Away<br />
|-<br />
|3<br />
|Night<br />
|-<br />
|4<br />
|Vacation<br />
|-<br />
|}<br />
<br />
<br />
=== Get “Mode” variable value ===<br />
http://IP:3480/data_request?id=variableget&Variable=Mode<br />
<br />
=== Set “Mode” variable value ===<br />
- luup.call_action("urn:micasaverde-com:serviceId:HomeAutomationGateway1","SetHouseMode", {Mode = value}, 0)<br><br />
- http://IP/port_3480/data_request?id=lu_action&serviceId=urn:micasaverde-com:serviceId:HomeAutomationGateway1&action=SetHouseMode&Mode=value<br />
{| style="border: 1px solid #000; border-collapse: collapse"<br />
! style="border: 1px solid #000; width: 150px" rowspan="2" | Action<br />
! style="border: 1px solid #000" colspan="2" | Arguments<br />
! style="border: 1px solid #000" rowspan="2" | Description<br />
|-<br />
! style="border: 1px solid #000; width: 130px" | Name<br />
! style="border: 1px solid #000; width: 140px" | Type or Related Variable<br />
|-<br />
| style="border: 1px solid #000" rowspan="1" | SetHouseMode<br />
| style="border: 1px solid #000" | Mode<br />
| style="border: 1px solid #000" | ui1<br />
| style="border: 1px solid #000" rowspan="1" | Change House Mode<br />
|}<br />
<br />
<br />
== “ModeSetting” top level attribute – default/custom setting for each mode ==<br />
<br />
'''Default values:'''<br><br />
- “!1:DC;2:DC*;3:DC*;4:DC* ” - user didn't configured preset modes yet; info message on dashboard is displayed;<br><br />
- “1:DC;2:DC*;3:DC*;4:DC*” - user visited the preset mode page or configured the modes; info message on dashboard is not displayed;<br><br />
'''Legend :''' <br><br />
- “DC*” - corresponding mode have the default values;<br><br />
- “C*” - corresponding mode have custom values;<br><br />
<br />
''Get ModeSetting value'' : http://IP:3480/data_request?id=variableget&Variable=ModeSetting<br><br />
''Set ModeSetting value'' : http://IP:3480/data_request?id=variableset&Variable=ModeSetting&Value=value<br><br />
<br />
<br />
== “ModeSetting” device state variable ==<br />
<br />
<br />
=== “Choose sensors to arm ” section - all the devices with category 4 ( DEVICE_CATEGORY_SECURITY_SENSOR) ===<br />
- if this variable is blank or doesn't exist it means the device isn't configured yet. Once the device is configured, the variable will be set;<br><br />
- if “A” is present it means that the sensor is “Armed”;<br><br />
- if no value is present it means that the sensor is “Disarmed/Bypassed”. <br><br />
<br />
Example :<br> <br />
“1:;2:A;3:A;4:A”<br><br />
- in “Home” mode the sensor is Disarmed/Bypassed;<br><br />
- in “Away/Night/Vacation” modes the sensor is Armed; <br><br />
<br />
<br />
=== “What to do if an armed sensor trips ? ” section - DEVICE_CATEGORY_SIREN & DEVICE_CATEGORY_SIREN ===<br />
<br />
The syntax used here is the same as for sensors<br />
<br />
<br />
=== “Who should be notified ?” section - look at the top level mode settings tag, like this: “1:D;2:DC*;3:DC*;4:DC*” ===<br />
<br />
- if the “C” is present, it means “yes” <br><br />
- if the “*” is present, it means that all users will be notify. By default, all users are “yes” in all modes except “Home”. <br><br />
- if notification for an individual user is changed, then the “*” is changed to a comma separated list of the PK_Users that are set to “yes”. For example, if the PK_User=1818 is turned to “yes” for mode “Away/2” : “1:D;2:DC,1818;3:DC*;4:DC*”. If PK_User 1819 is added with “yes” also, then it will look like this: “1:D;2:DC,1818,1819;3:DC*;4:DC*”and so on; <br><br />
<br />
<br />
=== “What to do when this mode is selected ?” section ===<br />
<br />
<br />
==== DEVICE_CATEGORY_HVAC ====<br />
<br />
No change = nothing; <br><br />
“Off” = O; <br><br />
“Heat” = H; <br><br />
“Cool” = C; <br><br />
“Auto” = A; v<br />
“,VALUE” = temperature; <br><br />
Example : <br><br />
“1:;2:H,72;3:C,73;4:A,74” - “no change” for mode #1, and the other three are heat, cool, auto.<br />
<br />
==== DEVICE_CATEGORY_DOOR_LOCK ====<br />
<br />
No Change = nothing;<br><br />
“Lock” = L;<br><br />
“Unlock” = U.<br><br />
Example : “1:;2:L;3:U;4:” - “no change” for mode #1 and #4, #2 - “Lock” and #3 - “Unlocked”<br />
<br />
<br />
==== DEVICE_CATEGORY_SWITCH & DEVICE_CATEGORY_DIMMABLE_LIGHT ====<br />
<br />
No Change = nothing;<br><br />
“On” = N;<br><br />
“Off” = F.<br><br />
Example : “1:;2:N;3:F;4:” - “no change” for mode #1 and #4, #2 - “On” and #3 - “Off”<br />
<br />
<br />
== Default modes ==<br />
<br />
DEVICE_CATEGORY_SECURITY_SENSOR (4)<br><br />
: DEVICE_SUBCATEGORY_GLASS (6) 1:A;2:A;3:A;4:A<br><br />
: DEVICE_SUBCATEGORY_SMOKE (4) 1:A;2:A;3:A;4:A<br><br />
: DEVICE_SUBCATEGORY_CO (5) 1:A;2:A;3:A;4:A<br><br />
: DEVICE_SUBCATEGORY_DOOR (1) 1:;2:A;3:A;4:A<br><br />
: Other 1:;2:A;3:;4:A<br><br />
DEVICE_CATEGORY_SIREN (24) 1:;2:A;3:A;4:A<br><br />
DEVICE_CATEGORY_CAMERA (6) 1:;2:A;3:A;4:A<br><br />
DEVICE_CATEGORY_HVAC (5) 1:;2:;3:;4:<br><br />
DEVICE_CATEGORY_DOOR_LOCK (7) 1:;2:;3:;4:<br><br />
DEVICE_CATEGORY_SWITCH (3) 1:;2:;3:;4:<br><br />
DEVICE_CATEGORY_DIMMABLE_LIGHT (2) 1:;2:;3:;4:<br></div>Andreimioshttp://wiki.mios.com/index.php/House_ModesHouse Modes2014-11-03T07:17:41Z<p>Andreimios: /* Get “Mode” variable value */</p>
<hr />
<div><br />
==“Mode” top level attribute==<br />
<br />
{| class="wikitable"<br />
|-<br />
! Mode value<br />
! House Mode<br />
|-<br />
|1<br />
|Home<br />
|-<br />
|2<br />
|Away<br />
|-<br />
|3<br />
|Night<br />
|-<br />
|4<br />
|Vacation<br />
|-<br />
|}<br />
<br />
<br />
=== Get “Mode” variable value ===<br />
http://GATEWAY_IP:3480/data_request?id=variableget&Variable=Mode<br />
<br />
=== Set “Mode” variable value ===<br />
- luup.call_action("urn:micasaverde-com:serviceId:HomeAutomationGateway1","SetHouseMode", {Mode = value}, 0)<br><br />
- http://IP/port_3480/data_request?id=lu_action&serviceId=urn:micasaverde-com:serviceId:HomeAutomationGateway1&action=SetHouseMode&Mode=value<br />
{| style="border: 1px solid #000; border-collapse: collapse"<br />
! style="border: 1px solid #000; width: 150px" rowspan="2" | Action<br />
! style="border: 1px solid #000" colspan="2" | Arguments<br />
! style="border: 1px solid #000" rowspan="2" | Description<br />
|-<br />
! style="border: 1px solid #000; width: 130px" | Name<br />
! style="border: 1px solid #000; width: 140px" | Type or Related Variable<br />
|-<br />
| style="border: 1px solid #000" rowspan="1" | SetHouseMode<br />
| style="border: 1px solid #000" | Mode<br />
| style="border: 1px solid #000" | ui1<br />
| style="border: 1px solid #000" rowspan="1" | Change House Mode<br />
|}<br />
<br />
<br />
== “ModeSetting” top level attribute – default/custom setting for each mode ==<br />
<br />
'''Default values:'''<br><br />
- “!1:DC;2:DC*;3:DC*;4:DC* ” - user didn't configured preset modes yet; info message on dashboard is displayed;<br><br />
- “1:DC;2:DC*;3:DC*;4:DC*” - user visited the preset mode page or configured the modes; info message on dashboard is not displayed;<br><br />
'''Legend :''' <br><br />
- “DC*” - corresponding mode have the default values;<br><br />
- “C*” - corresponding mode have custom values;<br><br />
<br />
''Get ModeSetting value'' : http://IP:3480/data_request?id=variableget&Variable=ModeSetting<br><br />
''Set ModeSetting value'' : http://IP:3480/data_request?id=variableset&Variable=ModeSetting&Value=value<br><br />
<br />
<br />
== “ModeSetting” device state variable ==<br />
<br />
<br />
=== “Choose sensors to arm ” section - all the devices with category 4 ( DEVICE_CATEGORY_SECURITY_SENSOR) ===<br />
- if this variable is blank or doesn't exist it means the device isn't configured yet. Once the device is configured, the variable will be set;<br><br />
- if “A” is present it means that the sensor is “Armed”;<br><br />
- if no value is present it means that the sensor is “Disarmed/Bypassed”. <br><br />
<br />
Example :<br> <br />
“1:;2:A;3:A;4:A”<br><br />
- in “Home” mode the sensor is Disarmed/Bypassed;<br><br />
- in “Away/Night/Vacation” modes the sensor is Armed; <br><br />
<br />
<br />
=== “What to do if an armed sensor trips ? ” section - DEVICE_CATEGORY_SIREN & DEVICE_CATEGORY_SIREN ===<br />
<br />
The syntax used here is the same as for sensors<br />
<br />
<br />
=== “Who should be notified ?” section - look at the top level mode settings tag, like this: “1:D;2:DC*;3:DC*;4:DC*” ===<br />
<br />
- if the “C” is present, it means “yes” <br><br />
- if the “*” is present, it means that all users will be notify. By default, all users are “yes” in all modes except “Home”. <br><br />
- if notification for an individual user is changed, then the “*” is changed to a comma separated list of the PK_Users that are set to “yes”. For example, if the PK_User=1818 is turned to “yes” for mode “Away/2” : “1:D;2:DC,1818;3:DC*;4:DC*”. If PK_User 1819 is added with “yes” also, then it will look like this: “1:D;2:DC,1818,1819;3:DC*;4:DC*”and so on; <br><br />
<br />
<br />
=== “What to do when this mode is selected ?” section ===<br />
<br />
<br />
==== DEVICE_CATEGORY_HVAC ====<br />
<br />
No change = nothing; <br><br />
“Off” = O; <br><br />
“Heat” = H; <br><br />
“Cool” = C; <br><br />
“Auto” = A; v<br />
“,VALUE” = temperature; <br><br />
Example : <br><br />
“1:;2:H,72;3:C,73;4:A,74” - “no change” for mode #1, and the other three are heat, cool, auto.<br />
<br />
==== DEVICE_CATEGORY_DOOR_LOCK ====<br />
<br />
No Change = nothing;<br><br />
“Lock” = L;<br><br />
“Unlock” = U.<br><br />
Example : “1:;2:L;3:U;4:” - “no change” for mode #1 and #4, #2 - “Lock” and #3 - “Unlocked”<br />
<br />
<br />
==== DEVICE_CATEGORY_SWITCH & DEVICE_CATEGORY_DIMMABLE_LIGHT ====<br />
<br />
No Change = nothing;<br><br />
“On” = N;<br><br />
“Off” = F.<br><br />
Example : “1:;2:N;3:F;4:” - “no change” for mode #1 and #4, #2 - “On” and #3 - “Off”<br />
<br />
<br />
== Default modes ==<br />
<br />
DEVICE_CATEGORY_SECURITY_SENSOR (4)<br><br />
: DEVICE_SUBCATEGORY_GLASS (6) 1:A;2:A;3:A;4:A<br><br />
: DEVICE_SUBCATEGORY_SMOKE (4) 1:A;2:A;3:A;4:A<br><br />
: DEVICE_SUBCATEGORY_CO (5) 1:A;2:A;3:A;4:A<br><br />
: DEVICE_SUBCATEGORY_DOOR (1) 1:;2:A;3:A;4:A<br><br />
: Other 1:;2:A;3:;4:A<br><br />
DEVICE_CATEGORY_SIREN (24) 1:;2:A;3:A;4:A<br><br />
DEVICE_CATEGORY_CAMERA (6) 1:;2:A;3:A;4:A<br><br />
DEVICE_CATEGORY_HVAC (5) 1:;2:;3:;4:<br><br />
DEVICE_CATEGORY_DOOR_LOCK (7) 1:;2:;3:;4:<br><br />
DEVICE_CATEGORY_SWITCH (3) 1:;2:;3:;4:<br><br />
DEVICE_CATEGORY_DIMMABLE_LIGHT (2) 1:;2:;3:;4:<br></div>Andreimioshttp://wiki.mios.com/index.php/House_ModesHouse Modes2014-11-03T07:11:41Z<p>Andreimios: /* Get “Mode” variable value */</p>
<hr />
<div><br />
==“Mode” top level attribute==<br />
<br />
{| class="wikitable"<br />
|-<br />
! Mode value<br />
! House Mode<br />
|-<br />
|1<br />
|Home<br />
|-<br />
|2<br />
|Away<br />
|-<br />
|3<br />
|Night<br />
|-<br />
|4<br />
|Vacation<br />
|-<br />
|}<br />
<br />
<br />
=== Get “Mode” variable value ===<br />
http://GATEWAY_IP:3480/data_request?id=variableget&Variable=Mode<br />
<br />
http://GATEWAY_IP:3480/data_request?id=variableget&DeviceNum=0&serviceId=urn:micasaverde-com:serviceId:HomeAutomationGateway1&Variable=Mode<br />
<br />
=== Set “Mode” variable value ===<br />
- luup.call_action("urn:micasaverde-com:serviceId:HomeAutomationGateway1","SetHouseMode", {Mode = value}, 0)<br><br />
- http://IP/port_3480/data_request?id=lu_action&serviceId=urn:micasaverde-com:serviceId:HomeAutomationGateway1&action=SetHouseMode&Mode=value<br />
{| style="border: 1px solid #000; border-collapse: collapse"<br />
! style="border: 1px solid #000; width: 150px" rowspan="2" | Action<br />
! style="border: 1px solid #000" colspan="2" | Arguments<br />
! style="border: 1px solid #000" rowspan="2" | Description<br />
|-<br />
! style="border: 1px solid #000; width: 130px" | Name<br />
! style="border: 1px solid #000; width: 140px" | Type or Related Variable<br />
|-<br />
| style="border: 1px solid #000" rowspan="1" | SetHouseMode<br />
| style="border: 1px solid #000" | Mode<br />
| style="border: 1px solid #000" | ui1<br />
| style="border: 1px solid #000" rowspan="1" | Change House Mode<br />
|}<br />
<br />
<br />
== “ModeSetting” top level attribute – default/custom setting for each mode ==<br />
<br />
'''Default values:'''<br><br />
- “!1:DC;2:DC*;3:DC*;4:DC* ” - user didn't configured preset modes yet; info message on dashboard is displayed;<br><br />
- “1:DC;2:DC*;3:DC*;4:DC*” - user visited the preset mode page or configured the modes; info message on dashboard is not displayed;<br><br />
'''Legend :''' <br><br />
- “DC*” - corresponding mode have the default values;<br><br />
- “C*” - corresponding mode have custom values;<br><br />
<br />
''Get ModeSetting value'' : http://IP:3480/data_request?id=variableget&Variable=ModeSetting<br><br />
''Set ModeSetting value'' : http://IP:3480/data_request?id=variableset&Variable=ModeSetting&Value=value<br><br />
<br />
<br />
== “ModeSetting” device state variable ==<br />
<br />
<br />
=== “Choose sensors to arm ” section - all the devices with category 4 ( DEVICE_CATEGORY_SECURITY_SENSOR) ===<br />
- if this variable is blank or doesn't exist it means the device isn't configured yet. Once the device is configured, the variable will be set;<br><br />
- if “A” is present it means that the sensor is “Armed”;<br><br />
- if no value is present it means that the sensor is “Disarmed/Bypassed”. <br><br />
<br />
Example :<br> <br />
“1:;2:A;3:A;4:A”<br><br />
- in “Home” mode the sensor is Disarmed/Bypassed;<br><br />
- in “Away/Night/Vacation” modes the sensor is Armed; <br><br />
<br />
<br />
=== “What to do if an armed sensor trips ? ” section - DEVICE_CATEGORY_SIREN & DEVICE_CATEGORY_SIREN ===<br />
<br />
The syntax used here is the same as for sensors<br />
<br />
<br />
=== “Who should be notified ?” section - look at the top level mode settings tag, like this: “1:D;2:DC*;3:DC*;4:DC*” ===<br />
<br />
- if the “C” is present, it means “yes” <br><br />
- if the “*” is present, it means that all users will be notify. By default, all users are “yes” in all modes except “Home”. <br><br />
- if notification for an individual user is changed, then the “*” is changed to a comma separated list of the PK_Users that are set to “yes”. For example, if the PK_User=1818 is turned to “yes” for mode “Away/2” : “1:D;2:DC,1818;3:DC*;4:DC*”. If PK_User 1819 is added with “yes” also, then it will look like this: “1:D;2:DC,1818,1819;3:DC*;4:DC*”and so on; <br><br />
<br />
<br />
=== “What to do when this mode is selected ?” section ===<br />
<br />
<br />
==== DEVICE_CATEGORY_HVAC ====<br />
<br />
No change = nothing; <br><br />
“Off” = O; <br><br />
“Heat” = H; <br><br />
“Cool” = C; <br><br />
“Auto” = A; v<br />
“,VALUE” = temperature; <br><br />
Example : <br><br />
“1:;2:H,72;3:C,73;4:A,74” - “no change” for mode #1, and the other three are heat, cool, auto.<br />
<br />
==== DEVICE_CATEGORY_DOOR_LOCK ====<br />
<br />
No Change = nothing;<br><br />
“Lock” = L;<br><br />
“Unlock” = U.<br><br />
Example : “1:;2:L;3:U;4:” - “no change” for mode #1 and #4, #2 - “Lock” and #3 - “Unlocked”<br />
<br />
<br />
==== DEVICE_CATEGORY_SWITCH & DEVICE_CATEGORY_DIMMABLE_LIGHT ====<br />
<br />
No Change = nothing;<br><br />
“On” = N;<br><br />
“Off” = F.<br><br />
Example : “1:;2:N;3:F;4:” - “no change” for mode #1 and #4, #2 - “On” and #3 - “Off”<br />
<br />
<br />
== Default modes ==<br />
<br />
DEVICE_CATEGORY_SECURITY_SENSOR (4)<br><br />
: DEVICE_SUBCATEGORY_GLASS (6) 1:A;2:A;3:A;4:A<br><br />
: DEVICE_SUBCATEGORY_SMOKE (4) 1:A;2:A;3:A;4:A<br><br />
: DEVICE_SUBCATEGORY_CO (5) 1:A;2:A;3:A;4:A<br><br />
: DEVICE_SUBCATEGORY_DOOR (1) 1:;2:A;3:A;4:A<br><br />
: Other 1:;2:A;3:;4:A<br><br />
DEVICE_CATEGORY_SIREN (24) 1:;2:A;3:A;4:A<br><br />
DEVICE_CATEGORY_CAMERA (6) 1:;2:A;3:A;4:A<br><br />
DEVICE_CATEGORY_HVAC (5) 1:;2:;3:;4:<br><br />
DEVICE_CATEGORY_DOOR_LOCK (7) 1:;2:;3:;4:<br><br />
DEVICE_CATEGORY_SWITCH (3) 1:;2:;3:;4:<br><br />
DEVICE_CATEGORY_DIMMABLE_LIGHT (2) 1:;2:;3:;4:<br></div>Andreimioshttp://wiki.mios.com/index.php/House_ModesHouse Modes2014-11-03T07:08:18Z<p>Andreimios: /* Get “Mode” variable value */</p>
<hr />
<div><br />
==“Mode” top level attribute==<br />
<br />
{| class="wikitable"<br />
|-<br />
! Mode value<br />
! House Mode<br />
|-<br />
|1<br />
|Home<br />
|-<br />
|2<br />
|Away<br />
|-<br />
|3<br />
|Night<br />
|-<br />
|4<br />
|Vacation<br />
|-<br />
|}<br />
<br />
<br />
=== Get “Mode” variable value ===<br />
http://GATEWAY_IP:3480/data_request?id=variableget&DeviceNum=0&serviceId=urn:micasaverde-com:serviceId:HomeAutomationGateway1&Variable=Mode<br />
<br />
=== Set “Mode” variable value ===<br />
- luup.call_action("urn:micasaverde-com:serviceId:HomeAutomationGateway1","SetHouseMode", {Mode = value}, 0)<br><br />
- http://IP/port_3480/data_request?id=lu_action&serviceId=urn:micasaverde-com:serviceId:HomeAutomationGateway1&action=SetHouseMode&Mode=value<br />
{| style="border: 1px solid #000; border-collapse: collapse"<br />
! style="border: 1px solid #000; width: 150px" rowspan="2" | Action<br />
! style="border: 1px solid #000" colspan="2" | Arguments<br />
! style="border: 1px solid #000" rowspan="2" | Description<br />
|-<br />
! style="border: 1px solid #000; width: 130px" | Name<br />
! style="border: 1px solid #000; width: 140px" | Type or Related Variable<br />
|-<br />
| style="border: 1px solid #000" rowspan="1" | SetHouseMode<br />
| style="border: 1px solid #000" | Mode<br />
| style="border: 1px solid #000" | ui1<br />
| style="border: 1px solid #000" rowspan="1" | Change House Mode<br />
|}<br />
<br />
<br />
== “ModeSetting” top level attribute – default/custom setting for each mode ==<br />
<br />
'''Default values:'''<br><br />
- “!1:DC;2:DC*;3:DC*;4:DC* ” - user didn't configured preset modes yet; info message on dashboard is displayed;<br><br />
- “1:DC;2:DC*;3:DC*;4:DC*” - user visited the preset mode page or configured the modes; info message on dashboard is not displayed;<br><br />
'''Legend :''' <br><br />
- “DC*” - corresponding mode have the default values;<br><br />
- “C*” - corresponding mode have custom values;<br><br />
<br />
''Get ModeSetting value'' : http://IP:3480/data_request?id=variableget&Variable=ModeSetting<br><br />
''Set ModeSetting value'' : http://IP:3480/data_request?id=variableset&Variable=ModeSetting&Value=value<br><br />
<br />
<br />
== “ModeSetting” device state variable ==<br />
<br />
<br />
=== “Choose sensors to arm ” section - all the devices with category 4 ( DEVICE_CATEGORY_SECURITY_SENSOR) ===<br />
- if this variable is blank or doesn't exist it means the device isn't configured yet. Once the device is configured, the variable will be set;<br><br />
- if “A” is present it means that the sensor is “Armed”;<br><br />
- if no value is present it means that the sensor is “Disarmed/Bypassed”. <br><br />
<br />
Example :<br> <br />
“1:;2:A;3:A;4:A”<br><br />
- in “Home” mode the sensor is Disarmed/Bypassed;<br><br />
- in “Away/Night/Vacation” modes the sensor is Armed; <br><br />
<br />
<br />
=== “What to do if an armed sensor trips ? ” section - DEVICE_CATEGORY_SIREN & DEVICE_CATEGORY_SIREN ===<br />
<br />
The syntax used here is the same as for sensors<br />
<br />
<br />
=== “Who should be notified ?” section - look at the top level mode settings tag, like this: “1:D;2:DC*;3:DC*;4:DC*” ===<br />
<br />
- if the “C” is present, it means “yes” <br><br />
- if the “*” is present, it means that all users will be notify. By default, all users are “yes” in all modes except “Home”. <br><br />
- if notification for an individual user is changed, then the “*” is changed to a comma separated list of the PK_Users that are set to “yes”. For example, if the PK_User=1818 is turned to “yes” for mode “Away/2” : “1:D;2:DC,1818;3:DC*;4:DC*”. If PK_User 1819 is added with “yes” also, then it will look like this: “1:D;2:DC,1818,1819;3:DC*;4:DC*”and so on; <br><br />
<br />
<br />
=== “What to do when this mode is selected ?” section ===<br />
<br />
<br />
==== DEVICE_CATEGORY_HVAC ====<br />
<br />
No change = nothing; <br><br />
“Off” = O; <br><br />
“Heat” = H; <br><br />
“Cool” = C; <br><br />
“Auto” = A; v<br />
“,VALUE” = temperature; <br><br />
Example : <br><br />
“1:;2:H,72;3:C,73;4:A,74” - “no change” for mode #1, and the other three are heat, cool, auto.<br />
<br />
==== DEVICE_CATEGORY_DOOR_LOCK ====<br />
<br />
No Change = nothing;<br><br />
“Lock” = L;<br><br />
“Unlock” = U.<br><br />
Example : “1:;2:L;3:U;4:” - “no change” for mode #1 and #4, #2 - “Lock” and #3 - “Unlocked”<br />
<br />
<br />
==== DEVICE_CATEGORY_SWITCH & DEVICE_CATEGORY_DIMMABLE_LIGHT ====<br />
<br />
No Change = nothing;<br><br />
“On” = N;<br><br />
“Off” = F.<br><br />
Example : “1:;2:N;3:F;4:” - “no change” for mode #1 and #4, #2 - “On” and #3 - “Off”<br />
<br />
<br />
== Default modes ==<br />
<br />
DEVICE_CATEGORY_SECURITY_SENSOR (4)<br><br />
: DEVICE_SUBCATEGORY_GLASS (6) 1:A;2:A;3:A;4:A<br><br />
: DEVICE_SUBCATEGORY_SMOKE (4) 1:A;2:A;3:A;4:A<br><br />
: DEVICE_SUBCATEGORY_CO (5) 1:A;2:A;3:A;4:A<br><br />
: DEVICE_SUBCATEGORY_DOOR (1) 1:;2:A;3:A;4:A<br><br />
: Other 1:;2:A;3:;4:A<br><br />
DEVICE_CATEGORY_SIREN (24) 1:;2:A;3:A;4:A<br><br />
DEVICE_CATEGORY_CAMERA (6) 1:;2:A;3:A;4:A<br><br />
DEVICE_CATEGORY_HVAC (5) 1:;2:;3:;4:<br><br />
DEVICE_CATEGORY_DOOR_LOCK (7) 1:;2:;3:;4:<br><br />
DEVICE_CATEGORY_SWITCH (3) 1:;2:;3:;4:<br><br />
DEVICE_CATEGORY_DIMMABLE_LIGHT (2) 1:;2:;3:;4:<br></div>Andreimioshttp://wiki.mios.com/index.php/JavaScript_APIJavaScript API2014-10-10T13:38:36Z<p>Andreimios: </p>
<hr />
<div>== Usage ==<br />
<pre>"Tabs": [<br />
{<br />
"Label": {<br />
"lang_tag": "users",<br />
"text": "Users" <br />
},<br />
"Position": "0",<br />
"TabType": "javascript",<br />
"ScriptName": "I_HomeCare.js",<br />
"Function": "showUsers"<br />
}, </pre> <br />
To generate a tab using your JavaScript functions you need to specify this by setting ''TabType'' to '''''javascript'''''. Then, you need to specify the script file's name and which function in this file will be used to draw the tab's content. That function will have one argument, which is the device number.<br> <br />
<br />
==== &lt;functionName&gt; (deviceNumber) ====<br />
<br />
This is the tab rendering function. The [[#set_panel_html_.28html.29 | set_panel_html]] function must be called at the end.<br> <br />
<br />
'''Input:''' <br />
<br />
*deviceNumber (number)<br><br />
<br />
'''Output:''' <br />
<br />
*nothing<br />
<br />
<br><br />
<br />
== Variables ==<br />
<br />
==== jsonp.ud ====<br />
<br />
This is the user data. <br />
<br />
*'''Type''': object <br />
*'''Members''': <br />
**devices (array) <br />
**scenes (array) <br />
**users (array) <br />
**rooms (array) <br />
**eventList (array) <br />
**etc.<br />
<br />
<br> <br />
<br />
==== jsonp.ud.devices ====<br />
<br />
*'''Type''': array <br />
*'''Members''': <br />
**id (number) <br />
**device_type (string) <br />
**room (number) <br />
**name (string) <br />
**category_num (number) <br />
**etc.<br />
<br />
<br> <br />
<br />
==== jsonp.ud.scenes ====<br />
<br />
*'''Type''': array <br />
*'''Members''': <br />
**id (number) <br />
**name (string) <br />
**room (number) <br />
**Timer_ids (array) <br />
**Timer (object) <br />
**etc.<br />
<br />
<br> <br />
<br />
== Functions ==<br />
<br />
==== get_device_state (deviceId, serviceId, variable, dynamic) ====<br />
<br />
'''Input:''' <br />
<br />
*deviceId (number)<br />
*serviceId (string)<br />
*variable (string)<br />
*dynamic (number): if '''1''', the variable's value is taken from ''lu_status'', else, the variable's value is taken from ''user_data''. ''user_data'' is read at Luup startup, so for variables that change their value frequently (like Watts, Temperature, etc.) ''dynamic'' should be '''1'''.<br />
<br />
'''Output:''' <br />
<br />
*variable value (string or ''undefined'')<br />
<br />
<br><br />
<br />
==== set_device_state (deviceId, serviceId, variable, value, dynamic) ====<br />
<br />
'''Input:''' <br />
<br />
*deviceId (number)<br />
*serviceId (string)<br />
*variable (string)<br />
*value (string)<br />
*dynamic (number): if '''1''', the variable's value is saved to ''lu_status'' (the value is lost after Luup is restarted), else, the variable's value is saved to a copy of ''user_data''; the real user_data is updated when LuaUPnP is restarted.<br />
<br />
'''Output:''' <br />
<br />
*''true'' if the operation succeeded, ''false'' otherwise<br />
<br />
<br><br />
<br />
==== _console (str) ====<br />
<br />
'''Input:''' <br />
<br />
*str (string): text to be written in the console. You need to have FireBug installed in order to have a console.<br />
<br />
'''Output:''' <br />
<br />
*nothing<br />
<br />
<br><br />
<br />
==== set_panel_html (html) ====<br />
<br />
Used in the tab rendering functions. <br />
<br />
'''Input:''' <br />
<br />
*html (string): The html to be used for generating the tab content.<br />
<br />
'''Output:''' <br />
<br />
*nothing<br />
<br />
[[Category:Development]]<br />
<br />
= JavaScript API for UI7 =<br />
<br />
== Introduction ==<br />
<br />
One of the new features of UI7 is the Javascript API for writing plugins. This is a free programming interface which is robust, well documented and comes with a guarantee that it will be compatible with the following UI releases.<br />
<br />
'''''What is this “API” ?'''''<br />
<br />
Simply said: it is a layer between the UI and the plugin developer. This way, the developer can use the features available in the UI by interacting only with the API. By using the new features available in the API, the overall user experience can be visibly improved.<br />
<br />
'''''How does it work ?'''''<br />
<br />
The API comes in the form of a library which exposes to the developer the objects and methods/functions needed to implement functionality in their plugins.<br />
<br />
'''''How is this different from the previous way of writing plugins ?'''''<br />
<br />
The developers were writing Javascript code and they had full access to the core of the application. There were a couple of objects and functions written by the UI team which were easing the work for the developer.<br />
By using the new API, the developer can write code without interfering with the core of the application.<br />
<br />
'''''What is new ?'''''<br />
<br />
* The developer can write the plugin without interfering with any other code except the API. This means there are a great bundle of methods like setters and getters which help writing good code.<br />
* UI team can make any changes to the core of the application, but as long as the API stays the same, the plugins will work. This way, the application can be improved and the developer won’t have to fix the code in order for it to work. New versions of the UI can be launched and the plugins will be compatible.<br />
* Event handling - the application will notify the plugin (via the API) about the events that happen inside. Consider, for example, the addition of a new device to the unit. The developer will know, by simply listening to an event, that a device was added and so, (s)he will write the code in such a way that it will take into account the event. The user experience will be greatly improved.<br />
* Asynchronous getters and setters - because most of the actions that happen inside the UI is asynchronous, so are the API’s method written. Most of them have a signature like this: function getXXX(obj, onSuccess, onFailure), where ‘onSuccess’ and ‘onFailure’ are callback functions which are called based on the result of the call.<br />
* No more global variables to manipulate. Everything is handled through getters/setters via API.<br />
* An API reference documentation: every method and its parameters is carefully documented so that the developer would know what the function does, how to call it and what it will return.<br />
* A couple of guidelines will be given to help developers write better code in such a way that two different plugins won’t “harm” each other. The module pattern will be used as a design pattern in order to put a plugin code inside a namespace. Also, this module helps in writing code which is easier to read and use.<br />
* It will be easier for the developers to write the code by using a new feature in the UI which generates the skeleton for the plugin.<br />
<br />
'''''What is the API reference documentation ?'''''<br />
<br />
This is the part which makes the API usable. Every aspect of the API, no matter how trivial, will be stated explicitly. It contains:<br />
<br />
* a description of all the data structures it depends upon<br />
* a description of all the function signatures:<br />
** function names<br />
** function parameters (names and types)<br />
** return type of the function<br />
** if it throws any exceptions or not<br />
<br />
'''''Where is the list of functions which were replaced ?'''''<br />
<br />
In the API reference documentation the developer can find out if a function replaces an old one.<br />
<br />
'''''Why should a developer write plugins using the API when it can do some “reverse engineering” and directly access any object/functionality of the application ?'''''<br />
<br />
It is not mandatory to write the code for the plugin this way. Probably the plugin will work as long as changes are not made in the core of the application, but the API comes also with a guarantee that after application changes, the plugins will continue to work. The UI team and plugin developers have the same goal: to deliver the best experience to the user. This is where the API comes into place - an interface between the two.<br />
<br />
'''''Will the API be rewritten with each new UI release ?'''''<br />
<br />
No. It will be improved. The goal of the API is to provide a stable interface to the developer so that when changing the core of the application it won’t be necessary to rewrite the plugins.<br />
<br />
'''''Is this API going to change in the near future ?'''''<br />
<br />
It can be changed. There will be parts of it which are going to be marked as ‘deprecated’. This means that the parts will be candidates for being removed, or modified in a backward incompatible way. The developers will be advised on how are they to change their code in order to use the features which replace the deprecated parts.<br />
<br />
'''''Is the API complete ?'''''<br />
<br />
Almost. Most of the functionality is there, but developers are encouraged to request new features from the API which will be added in future releases.<br />
<br />
== Guidelines on writing Javascript code for plugins in UI7 ==<br />
<br />
* Use the module pattern to organize your code inside a namespace. Choose a well defined name for your namespace.<br />
* Generate an UUID for your plugin. This way you can use the events engine.<br />
* Use the provided API plugins to perform most of your stuff. If you can’t find an implemented method inside the API you can ASK for an implementation to it.<br />
* '''NEVER USE''' variables/functions which are not accessible through API ! They can be changed or removed at any time.<br />
* If you need to do a background job (ex: start a timer), use the events engine and register a ‘cleanup’ function in which you finish the job (clear the timer).<br />
* We encourage the use of try { … } catch { … } blocks everywhere in your functions so that errors don’t get propagated to the top of the application.<br />
* Start from the skeleton provided and expand it:<br />
<br />
<source lang="javascript"><br />
var MyPlugin = (function (api) {<br />
// example of unique identifier for this plugin...<br />
var uuid = 'B971F6C4-F315-4E2E-AD08-F029A9777517';<br />
<br />
var myModule = {};<br />
<br />
function doSomething() {<br />
// register to event ‘on_ui_cpanel_before_close’...<br />
api.registerEventHandler('on_ui_cpanel_before_close', myModule, ‘cleanUp’);<br />
// and do something... <br />
}<br />
<br />
function cleanUp() {<br />
// perform clean up...<br />
}<br />
<br />
myModule = {<br />
uuid: uuid,<br />
doSomething: doSomething,<br />
cleanUp: cleanUp<br />
};<br />
return myModule;<br />
})(api);<br />
</source><br />
<br />
Your plugin functions will be accessible via ''MyPlugin.doSomething()'' construction.<br />
When the user will leave the cpanel, your plugin will be noticed via event ''‘on_ui_cpanel_before_close’''; this way you can perform the necessary cleanup.<br />
<br />
== JavaScript API ==<br />
<br />
''Defined in'': api.js<br />
<br />
=== Class Summary ===<br />
<br />
----<br />
<br />
'''API(config, application, ui)''' <br />
<br />
- API class for plugins<br />
<br />
'''Parameters:'''<br />
<br />
* {object} config - holds configuration data<br />
* {object} application - application layer<br />
* {object} ui - interface<br />
<br />
=== Method Summary ===<br />
<br />
----<br />
<br />
==== {Object} cloneObject(obj) ====<br />
<br />
- Clones a given object<br />
<br />
- Replaces: cloneObject()<br />
<br />
'''Parameters:'''<br />
<br />
* {object} obj - object to be cloned<br />
<br />
'''Returns:'''<br />
<br />
* {Object}<br />
<br />
==== {string} getCpanelContent() ====<br />
<br />
- Retrieves cpanel content<br />
<br />
- Replaces: get_panel_html()<br />
<br />
'''Returns:'''<br />
<br />
* {string} HTML code set in cpanel<br />
<br />
==== {number} getCpanelDeviceId() ====<br />
<br />
- Returns device id for current opened cpanel or 0 if not found<br />
<br />
'''Returns:'''<br />
<br />
* {number} - device ID<br />
<br />
==== getCurrentHouseMode(onSuccess, onFailure, context) ====<br />
<br />
- Performs a data request to retrieve the current house mode<br />
<br />
'''Parameters:'''<br />
<br />
* {*} onSuccess Optional - function to be called if the call is successfull<br />
* {*} onFailure Optional - function to be called if the call fails<br />
* {object} context Optional - context in which to execute the functions of success and/or failure<br />
<br />
==== {number} getDeviceIndex(deviceId) ====<br />
<br />
- Retrieves device index for given device id<br />
<br />
- Replaces: get_device_index()<br />
<br />
'''Parameters:'''<br />
<br />
* {number} deviceId - id of the device<br />
<br />
'''Returns:'''<br />
<br />
* {number}<br />
<br />
==== {*} getDeviceObject(deviceId) ====<br />
<br />
- Retrieves device object given its id<br />
<br />
- Replaces: get_device_obj()<br />
<br />
'''Parameters:'''<br />
<br />
* {number} deviceId - id of the device<br />
<br />
'''Returns:'''<br />
<br />
* {number}<br />
<br />
===={object} getDeviceState(deviceId, service, variable, options)====<br />
<br />
- Retrieves device state for a device (it can be either read from user data or lu status, depending on the options set)<br />
<br />
'''Parameters:'''<br />
<br />
* {number} deviceId - id of the device<br />
* {string} service - name of the service<br />
* {string} variable - name of the variable<br />
* {object} options Optional - list of options like: 'dynamic': (true - lu_status will be used [default], false - user_data will be used)<br />
<br />
'''Returns:'''<br />
<br />
* {object} value for a given variable<br />
<br />
==== {Object|Boolean} getDeviceTemplate(deviceId) ====<br />
<br />
- Returns device template for a given device id<br />
<br />
'''Parameters:'''<br />
<br />
* {number} deviceId - id of the device<br />
<br />
'''Returns:'''<br />
<br />
* {Object|Boolean}<br />
<br />
==== {*} getDisplayedDeviceName(deviceId) ====<br />
<br />
- Retrieves displayed device name or 'unnamed device' if device doesn't have a name or undefined if device not found<br />
<br />
'''Parameters:'''<br />
<br />
* {number} deviceId - id of the device<br />
<br />
'''Returns:'''<br />
<br />
* {*} if device is found a string which contains the device name or 'Unnamed device' if device name is not set, or undefined if device wasn't found<br />
<br />
==== {*} getEventDefinition(deviceType) ====<br />
<br />
- Retrieves event list for a given device type<br />
<br />
- Replaces: get_event_definition() <br />
<br />
'''Parameters:'''<br />
<br />
* {string} deviceType - type of device<br />
<br />
'''Returns:'''<br />
<br />
* {*}<br />
<br />
==== {*} getListOfDevices() ====<br />
<br />
- Returns the list of devices from userdata<br />
<br />
'''Returns:'''<br />
<br />
* {*}<br />
<br />
==== getLuSdata(onSuccess, onFailure, context) ====<br />
<br />
- Performs a data request to retrieve lu_sdata<br />
<br />
'''Parameters:'''<br />
<br />
* {*} onSuccess Optional - function to be called if the call is successfull<br />
* {*} onFailure Optional - function to be called if the call fails<br />
* {object} context Optional - context in which to execute the functions of success and/or failure<br />
<br />
==== {*|Object} getRoomObject(roomId) ====<br />
<br />
- Returns room object given a room id<br />
<br />
- Replaces: get_room_by_id()<br />
<br />
'''Parameters:'''<br />
<br />
* {number} roomId - id of the room<br />
<br />
'''Returns:'''<br />
<br />
* {*|Object}<br />
<br />
==== {*} getUserData() ====<br />
<br />
- Retrieves userData or null if error<br />
<br />
- Replaces: jsonp.ud<br />
<br />
'''Returns:'''<br />
<br />
* {*} object containing userdata<br />
<br />
==== registerEventHandler(eventName, object, functionName) ====<br />
<br />
- Register an event handler.<br />
<br />
'''Parameters:'''<br />
<br />
* {string} eventName - name of the event to register to<br />
* {object} object - the object which registers to the event<br />
* {string} functionName - the name of the function to be executed if event triggers<br />
<br />
==== runUpnpCode(code, options, onSuccess, onFailure, context) ====<br />
<br />
- Runs given Upnp code<br />
<br />
'''Parameters:'''<br />
<br />
* {string} code - code to execute<br />
* {object} options Optional - optionally options to be supplied (will be documented later)<br />
* {*} onSuccess Optional - function to be called if the call is successfull<br />
* {*} onFailure Optional - function to be called if the call fails<br />
* {object} context Optional - context in which to execute the functions of success and/or failure<br />
<br />
==== setCpanelContent(html) ====<br />
<br />
- Sets content for the cpanel<br />
<br />
- Replaces: set_panel_html()<br />
<br />
'''Parameters:'''<br />
<br />
* {string} html - the new content of the cpanel<br />
<br />
==== setCurrentHouseMode(modeValue, onSuccess, onFailure, context) ====<br />
<br />
- Sets current house mode<br />
<br />
'''Parameters:'''<br />
<br />
* {number} modeValue - new value for the house mode<br />
* {*} onSuccess Optional - function to be called if the call is successfull<br />
* {*} onFailure Optional - function to be called if the call fails<br />
* {object} context Optional - context in which to execute the functions of success and/or failure<br />
<br />
==== setDeviceStateVariable(deviceId, service, variable, value, onSuccess, onFailure, context) ====<br />
<br />
- Sets state for a device variable using variableset request.<br />
<br />
- Replaces: set_device_state()<br />
<br />
'''Parameters:'''<br />
<br />
* {number} deviceId - id of the device<br />
* {string} service - name of the service<br />
* {string} variable - name of the variable<br />
* {*} value - new value for the variable<br />
* {*} onSuccess Optional - function to be called if the call is successfull<br />
* {*} onFailure Optional - function to be called if the call fails<br />
* {object} context Optional - context in which to execute the functions of success and/or failure<br />
<br />
<br />
=== Events ===<br />
<br />
----<br />
<br />
The list of available events can be obtained with the following command:<br />
<br />
'''api.getListOfSupportedEvents()'''<br />
<br />
* on_startup_showModalLoading<br />
** triggered before loading resources in the browser<br />
*on_startup_luStatusLoaded<br />
** triggered after luStatus was successfully parsed<br />
** parameter: luStatusObject<br />
* on_startup_show2gInterface<br />
** triggered after requesting account devices only if UI is not in ‘local mode’ and ‘slowConnection’ flag is set<br />
* on_ui_requireSave<br />
** triggered if user data was changed and save wasn’t issued<br />
* on_ui_userDataFirstLoaded<br />
** fired if user data was loaded for the first time<br />
* on_ui_staticDataAdded<br />
** fired if static_data was added to user data<br />
** parameter: staticDataObject<br />
* on_ui_staticDataChanged<br />
** fired if static_data was changed after parsing user data<br />
** parameter: changedStaticDataObject<br />
* on_ui_staticDataRemoved<br />
** fired if static_data was removed after parsing user data<br />
** parameter: idForRemovedStaticDataObject<br />
* on_ui_setupDeviceAdded<br />
** fired if new setup device (menu item) is added<br />
** parameter: setupDeviceObject<br />
* on_ui_setupDeviceChanged<br />
** fired if setup device (menu item) is changed<br />
** parameter: changedSetupDeviceObject<br />
* on_ui_setupDeviceRemoved<br />
** fired if setup device (menu item) is removed<br />
** parameter: idForRemovedSetupDeviceObject<br />
* on_ui_sectionAdded<br />
** triggered when new section is added<br />
** parameter: sectionObject<br />
* on_ui_sectionChanged<br />
** fired after section was changed<br />
** parameter: changedSectionObject<br />
* on_ui_sectionRemoved<br />
** fired after section was removed<br />
** parameter: idForRemovedSectionObject<br />
* on_ui_roomAdded<br />
** fired when new room was added to user data<br />
** parameter: roomObject<br />
* on_ui_roomChanged<br />
** fired after room was changed<br />
** parameter: changedRoomObject<br />
* on_ui_roomRemoved<br />
** fired after room was removed from user data<br />
** parameter: idForRemovedRoomObject<br />
* on_ui_deviceAdded<br />
** fired after device was added to user data<br />
** parameter: deviceObject<br />
*** wrapper object for<br />
**** device: this is the actual object representing the device<br />
**** deviceTemplate: object with the static data associated to this device type<br />
* on_ui_deviceChanged<br />
** fired after device was found changed in user data<br />
** parameter: changedDeviceObject<br />
*** wrapper object for<br />
**** device: this is the actual object representing the device<br />
**** deviceTemplate: object with the static data associated to this device type<br />
* on_ui_deviceRemoved<br />
** fired after device was found removed from user data<br />
** parameter: idForRemovedDeviceObject<br />
* on_ui_deviceJobsReceived<br />
** fired when jobs are found for a device in lu_status<br />
** parameter: deviceObjectFromLuStatus<br />
* on_ui_sceneAdded<br />
** fired after scene was added<br />
** parameter: sceneObject<br />
* on_ui_sceneChanged<br />
** fired after scene was changed<br />
** parameter: changedSceneObject<br />
* on_ui_sceneChanged<br />
** fired when scene is removed<br />
** parameter: idForRemovedSceneObject<br />
* on_ui_pluginAdded<br />
** triggered when plugin is added to user data<br />
** parameter: pluginObject<br />
* on_ui_pluginChanged<br />
** triggered when plugin is changed<br />
** parameter: changedPluginObject<br />
* on_ui_pluginRemoved<br />
** triggered when plugin is removed<br />
** parameter: idForRemovedPluginObject<br />
* on_ui_extraSubmenuItemAdded<br />
** triggered when extra submenu item is added<br />
** parameter: extraSubmenuItemObject<br />
*** wrapper for:<br />
**** submenuItem: object containing submenu item<br />
**** deviceType: string which contains the type of device for which the submenu item is added<br />
* on_ui_extraSubmenuItemChanged<br />
** triggered when extra submenu item is changed<br />
** parameter: changedExtraSubmenuItemObject<br />
*** wrapper for:<br />
**** oldObj: contains previous submenu item<br />
**** newObj: wrapper for:<br />
***** submenuItem: object containing submenu item<br />
***** deviceType: string which contains the type of device for which the submenu item is added<br />
* on_ui_extraSubmenuItemRemoved:<br />
** triggered when an extra submenu item is removed<br />
** parameter: idForRemovedExtraSubmenuItemObject<br />
* on_ui_cardAdded<br />
** triggered when card is added to user data<br />
** parameter: cardObject<br />
* on_ui_cardChanged<br />
** triggered when card is found changed in user data<br />
** parameter: changedCardObject<br />
* on_ui_cardRemoved<br />
** triggered when card is removed from user data<br />
** parameter: idForRemovedCardObject<br />
* on_ui_jobsUpdated<br />
** triggered when job is updated in lu_status<br />
** parameter: luStatusJobsObject<br />
* on_ui_deviceStatusChanged<br />
** triggered when device status is changed<br />
** parameter: deviceObjectFromLuStatus<br />
* on_ui_syncClock<br />
** triggered after lu_status is parsed<br />
** parameter: luStatusLocalTime<br />
* on_ui_initFinished<br />
** fired when init has finished (UI should be ready now)<br />
* on_ui_setUserAuthenticated<br />
** fired after login is successful<br />
* on_ui_saveFinished<br />
** fired after save is finished<br />
* on_ui_initNotLogged<br />
** triggered if user is not logged in<br />
* on_ui_alertsUpdated<br />
** fired after alert list was updated<br />
* on_ui_refreshDashboardCards<br />
** triggered when dashboard cards are refreshed<br />
* on_ui_engineAvailable<br />
** triggered if engine is not busy<br />
* on_ui_2GEnabled<br />
** triggered when parsing lu_status if 2G is enabled<br />
* on_ui_userDataSetTemperatureFormat<br />
** triggered after temperature format is set in user data<br />
** parameter: userDataObject<br />
* on_ui_userDataLoaded<br />
** triggered after user data parsing is completed<br />
* on_parseUserData<br />
** triggered when user data parsing is started<br />
* on_ui_accountUnitsLoaded<br />
** fired after account lis from MMS was successfully loaded<br />
* accountInformationLoaded<br />
** triggered after account information is loaded<br />
** parameter: accountInfoObject<br />
* on_ui_finishDrawingMenu<br />
** triggered after parsing of user data setup devices has finished<br />
* on_ui_deviceTypeChanged<br />
** triggered if device type for a device has changed<br />
** parameter: deviceObject<br />
*** wrapper object for<br />
**** device: this is the actual object representing the device<br />
**** deviceTemplate: object with the static data associated to this device type<br />
* on_ui_hideModalLoading<br />
** triggered each time a time consuming job finishes (so that UI can hide modal loading)<br />
* on_ui_showUserDataSaveFailure<br />
** triggered if user data save has failed<br />
* on_ui_showErrorMessage<br />
** fired if application has error message to send to the UI<br />
* on_ui_cpanel_before_close<br />
** fired before closing the cpanel to allow plugins to cleanup their data<br />
** parameters: idForDeviceWhichOpenedTheCpanel<br />
<br />
=== Migration Walkthrough for plugins with JS ===<br />
<br />
With the introduction of our new JavaScript API, plugin mechanism slightly changed. In order to keep a backward compatibility with the UI5 version, there are a couple of thing a developer should do :<br />
<br />
* '''Update the JS file using the JavaScript API'''<br />
<br />
* '''Update the JSON file with proper calls for JavaScript functions'''<br />
<br />
For UI5 version, the JavaScript functions were called in JSON file like this :<br />
<br />
'''"ScriptName": "Your_JS_File.js",'''<br />
<br />
'''"Function": "Your_Function_Name"'''<br />
<br />
Example: Home Care Plugin - JSON file:<br />
<br />
<source lang="javascript"><br />
{<br />
"Label": {<br />
"lang_tag": "users",<br />
"text": "Users"<br />
},<br />
"TopNavigationTab": "1",<br />
"Position": "0",<br />
"TabType": "javascript",<br />
"ScriptName": "J_HomeCare.js",<br />
"Function": "ShowUsers"<br />
},<br />
</source><br />
<br />
For UI7, the JavaScript functions are called like this : <br />
<br />
'''"ScriptName": "Your_JS_File_for_UI7.js",'''<br />
<br />
'''"Function": "Your_Class_Name.Your_Function_Name"'''<br />
<br />
Example:<br />
<br />
<source lang="javascript"><br />
{<br />
"Label": {<br />
"lang_tag": "users",<br />
"text": "Users"<br />
},<br />
"TopNavigationTab": "1",<br />
"Position": "0",<br />
"TabType": "javascript",<br />
"ScriptName": "J_HomeCare_UI7.js",<br />
"Function": "HomeCare.ShowUsers"<br />
},<br />
</source><br />
<br />
By now, you should be asking yourself: "How plugin will work on UI5 if I update these files?". If you answer by yourself and the answer is : "It won't work", you are right. For this you will need to do an additional step:<br />
<br />
*'''Create different JSON and JS files and perform a check in your Luup code'''<br />
**As you can see in the above example for JSON file, our choice was to add "''_UI7''" for our JS file : "''J_HomeCare_UI7.js''". We suggest you to do the same, but this is not a requirement. We did the same with JSON file : "''D_HomeCare_UI7.json''"<br />
**In order to use the new JSON and JS files in UI7 instead of UI5 versions, "device_json" attribute of your device must set with the JSON file for UI7. For this, you can use the following function:<br />
<source lang="lua"> <br />
local function checkVersion()<br />
local ui7Check = luup.variable_get(SID, "UI7Check", lug_device) or ""<br />
if ui7Check == "" then<br />
luup.variable_set(SID, "UI7Check", "false", lug_device)<br />
ui7Check = "false"<br />
end<br />
if( luup.version_branch == 1 and luup.version_major == 7 and ui7Check == "false") then<br />
luup.variable_set(SID, "UI7Check", "true", lug_device)<br />
luup.attr_set("device_json", "Your_UI7_JSON_File", lug_device)<br />
luup.reload()<br />
end<br />
end<br />
</source><br />
''SID'' - your Service ID; ''lug_device'' - your device ID; <br />
**Call ''checkVersion()'' in your initialization function, before doing something else.<br />
<br />
=== HomeCare Plugin - updated for UI7 ===<br />
<br />
We use the HomeCare plugin as example for what need to be added/updated for UI7. Below you can download plugin files:<br />
<br />
[[File:HomeCare.zip]]<br />
<br />
This is the published version of HomeCare plugin that can be downloaded from our appstore. This version is compatible with both UI5 and UI7.</div>Andreimioshttp://wiki.mios.com/index.php/File:HomeCare.zipFile:HomeCare.zip2014-10-10T12:42:33Z<p>Andreimios: Andreimios uploaded a new version of &quot;File:HomeCare.zip&quot;</p>
<hr />
<div></div>Andreimioshttp://wiki.mios.com/index.php/JavaScript_APIJavaScript API2014-10-10T11:17:30Z<p>Andreimios: </p>
<hr />
<div>== Usage ==<br />
<pre>"Tabs": [<br />
{<br />
"Label": {<br />
"lang_tag": "users",<br />
"text": "Users" <br />
},<br />
"Position": "0",<br />
"TabType": "javascript",<br />
"ScriptName": "I_HomeCare.js",<br />
"Function": "showUsers"<br />
}, </pre> <br />
To generate a tab using your JavaScript functions you need to specify this by setting ''TabType'' to '''''javascript'''''. Then, you need to specify the script file's name and which function in this file will be used to draw the tab's content. That function will have one argument, which is the device number.<br> <br />
<br />
==== &lt;functionName&gt; (deviceNumber) ====<br />
<br />
This is the tab rendering function. The [[#set_panel_html_.28html.29 | set_panel_html]] function must be called at the end.<br> <br />
<br />
'''Input:''' <br />
<br />
*deviceNumber (number)<br><br />
<br />
'''Output:''' <br />
<br />
*nothing<br />
<br />
<br><br />
<br />
== Variables ==<br />
<br />
==== jsonp.ud ====<br />
<br />
This is the user data. <br />
<br />
*'''Type''': object <br />
*'''Members''': <br />
**devices (array) <br />
**scenes (array) <br />
**users (array) <br />
**rooms (array) <br />
**eventList (array) <br />
**etc.<br />
<br />
<br> <br />
<br />
==== jsonp.ud.devices ====<br />
<br />
*'''Type''': array <br />
*'''Members''': <br />
**id (number) <br />
**device_type (string) <br />
**room (number) <br />
**name (string) <br />
**category_num (number) <br />
**etc.<br />
<br />
<br> <br />
<br />
==== jsonp.ud.scenes ====<br />
<br />
*'''Type''': array <br />
*'''Members''': <br />
**id (number) <br />
**name (string) <br />
**room (number) <br />
**Timer_ids (array) <br />
**Timer (object) <br />
**etc.<br />
<br />
<br> <br />
<br />
== Functions ==<br />
<br />
==== get_device_state (deviceId, serviceId, variable, dynamic) ====<br />
<br />
'''Input:''' <br />
<br />
*deviceId (number)<br />
*serviceId (string)<br />
*variable (string)<br />
*dynamic (number): if '''1''', the variable's value is taken from ''lu_status'', else, the variable's value is taken from ''user_data''. ''user_data'' is read at Luup startup, so for variables that change their value frequently (like Watts, Temperature, etc.) ''dynamic'' should be '''1'''.<br />
<br />
'''Output:''' <br />
<br />
*variable value (string or ''undefined'')<br />
<br />
<br><br />
<br />
==== set_device_state (deviceId, serviceId, variable, value, dynamic) ====<br />
<br />
'''Input:''' <br />
<br />
*deviceId (number)<br />
*serviceId (string)<br />
*variable (string)<br />
*value (string)<br />
*dynamic (number): if '''1''', the variable's value is saved to ''lu_status'' (the value is lost after Luup is restarted), else, the variable's value is saved to a copy of ''user_data''; the real user_data is updated when LuaUPnP is restarted.<br />
<br />
'''Output:''' <br />
<br />
*''true'' if the operation succeeded, ''false'' otherwise<br />
<br />
<br><br />
<br />
==== _console (str) ====<br />
<br />
'''Input:''' <br />
<br />
*str (string): text to be written in the console. You need to have FireBug installed in order to have a console.<br />
<br />
'''Output:''' <br />
<br />
*nothing<br />
<br />
<br><br />
<br />
==== set_panel_html (html) ====<br />
<br />
Used in the tab rendering functions. <br />
<br />
'''Input:''' <br />
<br />
*html (string): The html to be used for generating the tab content.<br />
<br />
'''Output:''' <br />
<br />
*nothing<br />
<br />
[[Category:Development]]<br />
<br />
= JavaScript API for UI7 =<br />
<br />
== Introduction ==<br />
<br />
One of the new features of UI7 is the Javascript API for writing plugins. This is a free programming interface which is robust, well documented and comes with a guarantee that it will be compatible with the following UI releases.<br />
<br />
'''''What is this “API” ?'''''<br />
<br />
Simply said: it is a layer between the UI and the plugin developer. This way, the developer can use the features available in the UI by interacting only with the API. By using the new features available in the API, the overall user experience can be visibly improved.<br />
<br />
'''''How does it work ?'''''<br />
<br />
The API comes in the form of a library which exposes to the developer the objects and methods/functions needed to implement functionality in their plugins.<br />
<br />
'''''How is this different from the previous way of writing plugins ?'''''<br />
<br />
The developers were writing Javascript code and they had full access to the core of the application. There were a couple of objects and functions written by the UI team which were easing the work for the developer.<br />
By using the new API, the developer can write code without interfering with the core of the application.<br />
<br />
'''''What is new ?'''''<br />
<br />
* The developer can write the plugin without interfering with any other code except the API. This means there are a great bundle of methods like setters and getters which help writing good code.<br />
* UI team can make any changes to the core of the application, but as long as the API stays the same, the plugins will work. This way, the application can be improved and the developer won’t have to fix the code in order for it to work. New versions of the UI can be launched and the plugins will be compatible.<br />
* Event handling - the application will notify the plugin (via the API) about the events that happen inside. Consider, for example, the addition of a new device to the unit. The developer will know, by simply listening to an event, that a device was added and so, (s)he will write the code in such a way that it will take into account the event. The user experience will be greatly improved.<br />
* Asynchronous getters and setters - because most of the actions that happen inside the UI is asynchronous, so are the API’s method written. Most of them have a signature like this: function getXXX(obj, onSuccess, onFailure), where ‘onSuccess’ and ‘onFailure’ are callback functions which are called based on the result of the call.<br />
* No more global variables to manipulate. Everything is handled through getters/setters via API.<br />
* An API reference documentation: every method and its parameters is carefully documented so that the developer would know what the function does, how to call it and what it will return.<br />
* A couple of guidelines will be given to help developers write better code in such a way that two different plugins won’t “harm” each other. The module pattern will be used as a design pattern in order to put a plugin code inside a namespace. Also, this module helps in writing code which is easier to read and use.<br />
* It will be easier for the developers to write the code by using a new feature in the UI which generates the skeleton for the plugin.<br />
<br />
'''''What is the API reference documentation ?'''''<br />
<br />
This is the part which makes the API usable. Every aspect of the API, no matter how trivial, will be stated explicitly. It contains:<br />
<br />
* a description of all the data structures it depends upon<br />
* a description of all the function signatures:<br />
** function names<br />
** function parameters (names and types)<br />
** return type of the function<br />
** if it throws any exceptions or not<br />
<br />
'''''Where is the list of functions which were replaced ?'''''<br />
<br />
In the API reference documentation the developer can find out if a function replaces an old one.<br />
<br />
'''''Why should a developer write plugins using the API when it can do some “reverse engineering” and directly access any object/functionality of the application ?'''''<br />
<br />
It is not mandatory to write the code for the plugin this way. Probably the plugin will work as long as changes are not made in the core of the application, but the API comes also with a guarantee that after application changes, the plugins will continue to work. The UI team and plugin developers have the same goal: to deliver the best experience to the user. This is where the API comes into place - an interface between the two.<br />
<br />
'''''Will the API be rewritten with each new UI release ?'''''<br />
<br />
No. It will be improved. The goal of the API is to provide a stable interface to the developer so that when changing the core of the application it won’t be necessary to rewrite the plugins.<br />
<br />
'''''Is this API going to change in the near future ?'''''<br />
<br />
It can be changed. There will be parts of it which are going to be marked as ‘deprecated’. This means that the parts will be candidates for being removed, or modified in a backward incompatible way. The developers will be advised on how are they to change their code in order to use the features which replace the deprecated parts.<br />
<br />
'''''Is the API complete ?'''''<br />
<br />
Almost. Most of the functionality is there, but developers are encouraged to request new features from the API which will be added in future releases.<br />
<br />
== Guidelines on writing Javascript code for plugins in UI7 ==<br />
<br />
* Use the module pattern to organize your code inside a namespace. Choose a well defined name for your namespace.<br />
* Generate an UUID for your plugin. This way you can use the events engine.<br />
* Use the provided API plugins to perform most of your stuff. If you can’t find an implemented method inside the API you can ASK for an implementation to it.<br />
* '''NEVER USE''' variables/functions which are not accessible through API ! They can be changed or removed at any time.<br />
* If you need to do a background job (ex: start a timer), use the events engine and register a ‘cleanup’ function in which you finish the job (clear the timer).<br />
* We encourage the use of try { … } catch { … } blocks everywhere in your functions so that errors don’t get propagated to the top of the application.<br />
* Start from the skeleton provided and expand it:<br />
<br />
<source lang="javascript"><br />
var MyPlugin = (function (api) {<br />
// example of unique identifier for this plugin...<br />
var uuid = 'B971F6C4-F315-4E2E-AD08-F029A9777517';<br />
<br />
var myModule = {};<br />
<br />
function doSomething() {<br />
// register to event ‘on_ui_cpanel_before_close’...<br />
api.registerEventHandler('on_ui_cpanel_before_close', myModule, ‘cleanUp’);<br />
// and do something... <br />
}<br />
<br />
function cleanUp() {<br />
// perform clean up...<br />
}<br />
<br />
myModule = {<br />
uuid: uuid,<br />
doSomething: doSomething,<br />
cleanUp: cleanUp<br />
};<br />
return myModule;<br />
})(api);<br />
</source><br />
<br />
Your plugin functions will be accessible via ''MyPlugin.doSomething()'' construction.<br />
When the user will leave the cpanel, your plugin will be noticed via event ''‘on_ui_cpanel_before_close’''; this way you can perform the necessary cleanup.<br />
<br />
== JavaScript API ==<br />
<br />
''Defined in'': api.js<br />
<br />
=== Class Summary ===<br />
<br />
----<br />
<br />
'''API(config, application, ui)''' <br />
<br />
- API class for plugins<br />
<br />
'''Parameters:'''<br />
<br />
* {object} config - holds configuration data<br />
* {object} application - application layer<br />
* {object} ui - interface<br />
<br />
=== Method Summary ===<br />
<br />
----<br />
<br />
==== {Object} cloneObject(obj) ====<br />
<br />
- Clones a given object<br />
<br />
- Replaces: cloneObject()<br />
<br />
'''Parameters:'''<br />
<br />
* {object} obj - object to be cloned<br />
<br />
'''Returns:'''<br />
<br />
* {Object}<br />
<br />
==== {string} getCpanelContent() ====<br />
<br />
- Retrieves cpanel content<br />
<br />
- Replaces: get_panel_html()<br />
<br />
'''Returns:'''<br />
<br />
* {string} HTML code set in cpanel<br />
<br />
==== {number} getCpanelDeviceId() ====<br />
<br />
- Returns device id for current opened cpanel or 0 if not found<br />
<br />
'''Returns:'''<br />
<br />
* {number} - device ID<br />
<br />
==== getCurrentHouseMode(onSuccess, onFailure, context) ====<br />
<br />
- Performs a data request to retrieve the current house mode<br />
<br />
'''Parameters:'''<br />
<br />
* {*} onSuccess Optional - function to be called if the call is successfull<br />
* {*} onFailure Optional - function to be called if the call fails<br />
* {object} context Optional - context in which to execute the functions of success and/or failure<br />
<br />
==== {number} getDeviceIndex(deviceId) ====<br />
<br />
- Retrieves device index for given device id<br />
<br />
- Replaces: get_device_index()<br />
<br />
'''Parameters:'''<br />
<br />
* {number} deviceId - id of the device<br />
<br />
'''Returns:'''<br />
<br />
* {number}<br />
<br />
==== {*} getDeviceObject(deviceId) ====<br />
<br />
- Retrieves device object given its id<br />
<br />
- Replaces: get_device_obj()<br />
<br />
'''Parameters:'''<br />
<br />
* {number} deviceId - id of the device<br />
<br />
'''Returns:'''<br />
<br />
* {number}<br />
<br />
===={object} getDeviceState(deviceId, service, variable, options)====<br />
<br />
- Retrieves device state for a device (it can be either read from user data or lu status, depending on the options set)<br />
<br />
'''Parameters:'''<br />
<br />
* {number} deviceId - id of the device<br />
* {string} service - name of the service<br />
* {string} variable - name of the variable<br />
* {object} options Optional - list of options like: 'dynamic': (true - lu_status will be used [default], false - user_data will be used)<br />
<br />
'''Returns:'''<br />
<br />
* {object} value for a given variable<br />
<br />
==== {Object|Boolean} getDeviceTemplate(deviceId) ====<br />
<br />
- Returns device template for a given device id<br />
<br />
'''Parameters:'''<br />
<br />
* {number} deviceId - id of the device<br />
<br />
'''Returns:'''<br />
<br />
* {Object|Boolean}<br />
<br />
==== {*} getDisplayedDeviceName(deviceId) ====<br />
<br />
- Retrieves displayed device name or 'unnamed device' if device doesn't have a name or undefined if device not found<br />
<br />
'''Parameters:'''<br />
<br />
* {number} deviceId - id of the device<br />
<br />
'''Returns:'''<br />
<br />
* {*} if device is found a string which contains the device name or 'Unnamed device' if device name is not set, or undefined if device wasn't found<br />
<br />
==== {*} getEventDefinition(deviceType) ====<br />
<br />
- Retrieves event list for a given device type<br />
<br />
- Replaces: get_event_definition() <br />
<br />
'''Parameters:'''<br />
<br />
* {string} deviceType - type of device<br />
<br />
'''Returns:'''<br />
<br />
* {*}<br />
<br />
==== {*} getListOfDevices() ====<br />
<br />
- Returns the list of devices from userdata<br />
<br />
'''Returns:'''<br />
<br />
* {*}<br />
<br />
==== getLuSdata(onSuccess, onFailure, context) ====<br />
<br />
- Performs a data request to retrieve lu_sdata<br />
<br />
'''Parameters:'''<br />
<br />
* {*} onSuccess Optional - function to be called if the call is successfull<br />
* {*} onFailure Optional - function to be called if the call fails<br />
* {object} context Optional - context in which to execute the functions of success and/or failure<br />
<br />
==== {*|Object} getRoomObject(roomId) ====<br />
<br />
- Returns room object given a room id<br />
<br />
- Replaces: get_room_by_id()<br />
<br />
'''Parameters:'''<br />
<br />
* {number} roomId - id of the room<br />
<br />
'''Returns:'''<br />
<br />
* {*|Object}<br />
<br />
==== {*} getUserData() ====<br />
<br />
- Retrieves userData or null if error<br />
<br />
- Replaces: jsonp.ud<br />
<br />
'''Returns:'''<br />
<br />
* {*} object containing userdata<br />
<br />
==== registerEventHandler(eventName, object, functionName) ====<br />
<br />
- Register an event handler.<br />
<br />
'''Parameters:'''<br />
<br />
* {string} eventName - name of the event to register to<br />
* {object} object - the object which registers to the event<br />
* {string} functionName - the name of the function to be executed if event triggers<br />
<br />
==== runUpnpCode(code, options, onSuccess, onFailure, context) ====<br />
<br />
- Runs given Upnp code<br />
<br />
'''Parameters:'''<br />
<br />
* {string} code - code to execute<br />
* {object} options Optional - optionally options to be supplied (will be documented later)<br />
* {*} onSuccess Optional - function to be called if the call is successfull<br />
* {*} onFailure Optional - function to be called if the call fails<br />
* {object} context Optional - context in which to execute the functions of success and/or failure<br />
<br />
==== setCpanelContent(html) ====<br />
<br />
- Sets content for the cpanel<br />
<br />
- Replaces: set_panel_html()<br />
<br />
'''Parameters:'''<br />
<br />
* {string} html - the new content of the cpanel<br />
<br />
==== setCurrentHouseMode(modeValue, onSuccess, onFailure, context) ====<br />
<br />
- Sets current house mode<br />
<br />
'''Parameters:'''<br />
<br />
* {number} modeValue - new value for the house mode<br />
* {*} onSuccess Optional - function to be called if the call is successfull<br />
* {*} onFailure Optional - function to be called if the call fails<br />
* {object} context Optional - context in which to execute the functions of success and/or failure<br />
<br />
==== setDeviceStateVariable(deviceId, service, variable, value, onSuccess, onFailure, context) ====<br />
<br />
- Sets state for a device variable using variableset request.<br />
<br />
- Replaces: set_device_state()<br />
<br />
'''Parameters:'''<br />
<br />
* {number} deviceId - id of the device<br />
* {string} service - name of the service<br />
* {string} variable - name of the variable<br />
* {*} value - new value for the variable<br />
* {*} onSuccess Optional - function to be called if the call is successfull<br />
* {*} onFailure Optional - function to be called if the call fails<br />
* {object} context Optional - context in which to execute the functions of success and/or failure<br />
<br />
<br />
=== Events ===<br />
<br />
----<br />
<br />
The list of available events can be obtained with the following command:<br />
<br />
'''api.getListOfSupportedEvents()'''<br />
<br />
* on_startup_showModalLoading<br />
** triggered before loading resources in the browser<br />
*on_startup_luStatusLoaded<br />
** triggered after luStatus was successfully parsed<br />
** parameter: luStatusObject<br />
* on_startup_show2gInterface<br />
** triggered after requesting account devices only if UI is not in ‘local mode’ and ‘slowConnection’ flag is set<br />
* on_ui_requireSave<br />
** triggered if user data was changed and save wasn’t issued<br />
* on_ui_userDataFirstLoaded<br />
** fired if user data was loaded for the first time<br />
* on_ui_staticDataAdded<br />
** fired if static_data was added to user data<br />
** parameter: staticDataObject<br />
* on_ui_staticDataChanged<br />
** fired if static_data was changed after parsing user data<br />
** parameter: changedStaticDataObject<br />
* on_ui_staticDataRemoved<br />
** fired if static_data was removed after parsing user data<br />
** parameter: idForRemovedStaticDataObject<br />
* on_ui_setupDeviceAdded<br />
** fired if new setup device (menu item) is added<br />
** parameter: setupDeviceObject<br />
* on_ui_setupDeviceChanged<br />
** fired if setup device (menu item) is changed<br />
** parameter: changedSetupDeviceObject<br />
* on_ui_setupDeviceRemoved<br />
** fired if setup device (menu item) is removed<br />
** parameter: idForRemovedSetupDeviceObject<br />
* on_ui_sectionAdded<br />
** triggered when new section is added<br />
** parameter: sectionObject<br />
* on_ui_sectionChanged<br />
** fired after section was changed<br />
** parameter: changedSectionObject<br />
* on_ui_sectionRemoved<br />
** fired after section was removed<br />
** parameter: idForRemovedSectionObject<br />
* on_ui_roomAdded<br />
** fired when new room was added to user data<br />
** parameter: roomObject<br />
* on_ui_roomChanged<br />
** fired after room was changed<br />
** parameter: changedRoomObject<br />
* on_ui_roomRemoved<br />
** fired after room was removed from user data<br />
** parameter: idForRemovedRoomObject<br />
* on_ui_deviceAdded<br />
** fired after device was added to user data<br />
** parameter: deviceObject<br />
*** wrapper object for<br />
**** device: this is the actual object representing the device<br />
**** deviceTemplate: object with the static data associated to this device type<br />
* on_ui_deviceChanged<br />
** fired after device was found changed in user data<br />
** parameter: changedDeviceObject<br />
*** wrapper object for<br />
**** device: this is the actual object representing the device<br />
**** deviceTemplate: object with the static data associated to this device type<br />
* on_ui_deviceRemoved<br />
** fired after device was found removed from user data<br />
** parameter: idForRemovedDeviceObject<br />
* on_ui_deviceJobsReceived<br />
** fired when jobs are found for a device in lu_status<br />
** parameter: deviceObjectFromLuStatus<br />
* on_ui_sceneAdded<br />
** fired after scene was added<br />
** parameter: sceneObject<br />
* on_ui_sceneChanged<br />
** fired after scene was changed<br />
** parameter: changedSceneObject<br />
* on_ui_sceneChanged<br />
** fired when scene is removed<br />
** parameter: idForRemovedSceneObject<br />
* on_ui_pluginAdded<br />
** triggered when plugin is added to user data<br />
** parameter: pluginObject<br />
* on_ui_pluginChanged<br />
** triggered when plugin is changed<br />
** parameter: changedPluginObject<br />
* on_ui_pluginRemoved<br />
** triggered when plugin is removed<br />
** parameter: idForRemovedPluginObject<br />
* on_ui_extraSubmenuItemAdded<br />
** triggered when extra submenu item is added<br />
** parameter: extraSubmenuItemObject<br />
*** wrapper for:<br />
**** submenuItem: object containing submenu item<br />
**** deviceType: string which contains the type of device for which the submenu item is added<br />
* on_ui_extraSubmenuItemChanged<br />
** triggered when extra submenu item is changed<br />
** parameter: changedExtraSubmenuItemObject<br />
*** wrapper for:<br />
**** oldObj: contains previous submenu item<br />
**** newObj: wrapper for:<br />
***** submenuItem: object containing submenu item<br />
***** deviceType: string which contains the type of device for which the submenu item is added<br />
* on_ui_extraSubmenuItemRemoved:<br />
** triggered when an extra submenu item is removed<br />
** parameter: idForRemovedExtraSubmenuItemObject<br />
* on_ui_cardAdded<br />
** triggered when card is added to user data<br />
** parameter: cardObject<br />
* on_ui_cardChanged<br />
** triggered when card is found changed in user data<br />
** parameter: changedCardObject<br />
* on_ui_cardRemoved<br />
** triggered when card is removed from user data<br />
** parameter: idForRemovedCardObject<br />
* on_ui_jobsUpdated<br />
** triggered when job is updated in lu_status<br />
** parameter: luStatusJobsObject<br />
* on_ui_deviceStatusChanged<br />
** triggered when device status is changed<br />
** parameter: deviceObjectFromLuStatus<br />
* on_ui_syncClock<br />
** triggered after lu_status is parsed<br />
** parameter: luStatusLocalTime<br />
* on_ui_initFinished<br />
** fired when init has finished (UI should be ready now)<br />
* on_ui_setUserAuthenticated<br />
** fired after login is successful<br />
* on_ui_saveFinished<br />
** fired after save is finished<br />
* on_ui_initNotLogged<br />
** triggered if user is not logged in<br />
* on_ui_alertsUpdated<br />
** fired after alert list was updated<br />
* on_ui_refreshDashboardCards<br />
** triggered when dashboard cards are refreshed<br />
* on_ui_engineAvailable<br />
** triggered if engine is not busy<br />
* on_ui_2GEnabled<br />
** triggered when parsing lu_status if 2G is enabled<br />
* on_ui_userDataSetTemperatureFormat<br />
** triggered after temperature format is set in user data<br />
** parameter: userDataObject<br />
* on_ui_userDataLoaded<br />
** triggered after user data parsing is completed<br />
* on_parseUserData<br />
** triggered when user data parsing is started<br />
* on_ui_accountUnitsLoaded<br />
** fired after account lis from MMS was successfully loaded<br />
* accountInformationLoaded<br />
** triggered after account information is loaded<br />
** parameter: accountInfoObject<br />
* on_ui_finishDrawingMenu<br />
** triggered after parsing of user data setup devices has finished<br />
* on_ui_deviceTypeChanged<br />
** triggered if device type for a device has changed<br />
** parameter: deviceObject<br />
*** wrapper object for<br />
**** device: this is the actual object representing the device<br />
**** deviceTemplate: object with the static data associated to this device type<br />
* on_ui_hideModalLoading<br />
** triggered each time a time consuming job finishes (so that UI can hide modal loading)<br />
* on_ui_showUserDataSaveFailure<br />
** triggered if user data save has failed<br />
* on_ui_showErrorMessage<br />
** fired if application has error message to send to the UI<br />
* on_ui_cpanel_before_close<br />
** fired before closing the cpanel to allow plugins to cleanup their data<br />
** parameters: idForDeviceWhichOpenedTheCpanel<br />
<br />
<br />
=== HomeCare Plugin - updated for UI7 ===<br />
<br />
We use the HomeCare plugin as example for what need to be added/updated for UI7. Below you can download plugin files:<br />
<br />
[[File:HomeCare.zip]]<br />
<br />
This is the published version of HomeCare plugin that can be downloaded from our appstore. This version is compatible with both UI5 and UI7.</div>Andreimioshttp://wiki.mios.com/index.php/File:HomeCare.zipFile:HomeCare.zip2014-10-10T11:08:43Z<p>Andreimios: Andreimios uploaded a new version of &quot;File:HomeCare.zip&quot;: - added all HomeCare Plugin files</p>
<hr />
<div></div>Andreimioshttp://wiki.mios.com/index.php/JavaScript_APIJavaScript API2014-10-06T12:22:45Z<p>Andreimios: </p>
<hr />
<div>== Usage ==<br />
<pre>"Tabs": [<br />
{<br />
"Label": {<br />
"lang_tag": "users",<br />
"text": "Users" <br />
},<br />
"Position": "0",<br />
"TabType": "javascript",<br />
"ScriptName": "I_HomeCare.js",<br />
"Function": "showUsers"<br />
}, </pre> <br />
To generate a tab using your JavaScript functions you need to specify this by setting ''TabType'' to '''''javascript'''''. Then, you need to specify the script file's name and which function in this file will be used to draw the tab's content. That function will have one argument, which is the device number.<br> <br />
<br />
==== &lt;functionName&gt; (deviceNumber) ====<br />
<br />
This is the tab rendering function. The [[#set_panel_html_.28html.29 | set_panel_html]] function must be called at the end.<br> <br />
<br />
'''Input:''' <br />
<br />
*deviceNumber (number)<br><br />
<br />
'''Output:''' <br />
<br />
*nothing<br />
<br />
<br><br />
<br />
== Variables ==<br />
<br />
==== jsonp.ud ====<br />
<br />
This is the user data. <br />
<br />
*'''Type''': object <br />
*'''Members''': <br />
**devices (array) <br />
**scenes (array) <br />
**users (array) <br />
**rooms (array) <br />
**eventList (array) <br />
**etc.<br />
<br />
<br> <br />
<br />
==== jsonp.ud.devices ====<br />
<br />
*'''Type''': array <br />
*'''Members''': <br />
**id (number) <br />
**device_type (string) <br />
**room (number) <br />
**name (string) <br />
**category_num (number) <br />
**etc.<br />
<br />
<br> <br />
<br />
==== jsonp.ud.scenes ====<br />
<br />
*'''Type''': array <br />
*'''Members''': <br />
**id (number) <br />
**name (string) <br />
**room (number) <br />
**Timer_ids (array) <br />
**Timer (object) <br />
**etc.<br />
<br />
<br> <br />
<br />
== Functions ==<br />
<br />
==== get_device_state (deviceId, serviceId, variable, dynamic) ====<br />
<br />
'''Input:''' <br />
<br />
*deviceId (number)<br />
*serviceId (string)<br />
*variable (string)<br />
*dynamic (number): if '''1''', the variable's value is taken from ''lu_status'', else, the variable's value is taken from ''user_data''. ''user_data'' is read at Luup startup, so for variables that change their value frequently (like Watts, Temperature, etc.) ''dynamic'' should be '''1'''.<br />
<br />
'''Output:''' <br />
<br />
*variable value (string or ''undefined'')<br />
<br />
<br><br />
<br />
==== set_device_state (deviceId, serviceId, variable, value, dynamic) ====<br />
<br />
'''Input:''' <br />
<br />
*deviceId (number)<br />
*serviceId (string)<br />
*variable (string)<br />
*value (string)<br />
*dynamic (number): if '''1''', the variable's value is saved to ''lu_status'' (the value is lost after Luup is restarted), else, the variable's value is saved to a copy of ''user_data''; the real user_data is updated when LuaUPnP is restarted.<br />
<br />
'''Output:''' <br />
<br />
*''true'' if the operation succeeded, ''false'' otherwise<br />
<br />
<br><br />
<br />
==== _console (str) ====<br />
<br />
'''Input:''' <br />
<br />
*str (string): text to be written in the console. You need to have FireBug installed in order to have a console.<br />
<br />
'''Output:''' <br />
<br />
*nothing<br />
<br />
<br><br />
<br />
==== set_panel_html (html) ====<br />
<br />
Used in the tab rendering functions. <br />
<br />
'''Input:''' <br />
<br />
*html (string): The html to be used for generating the tab content.<br />
<br />
'''Output:''' <br />
<br />
*nothing<br />
<br />
[[Category:Development]]<br />
<br />
= JavaScript API for UI7 =<br />
<br />
== Introduction ==<br />
<br />
One of the new features of UI7 is the Javascript API for writing plugins. This is a free programming interface which is robust, well documented and comes with a guarantee that it will be compatible with the following UI releases.<br />
<br />
'''''What is this “API” ?'''''<br />
<br />
Simply said: it is a layer between the UI and the plugin developer. This way, the developer can use the features available in the UI by interacting only with the API. By using the new features available in the API, the overall user experience can be visibly improved.<br />
<br />
'''''How does it work ?'''''<br />
<br />
The API comes in the form of a library which exposes to the developer the objects and methods/functions needed to implement functionality in their plugins.<br />
<br />
'''''How is this different from the previous way of writing plugins ?'''''<br />
<br />
The developers were writing Javascript code and they had full access to the core of the application. There were a couple of objects and functions written by the UI team which were easing the work for the developer.<br />
By using the new API, the developer can write code without interfering with the core of the application.<br />
<br />
'''''What is new ?'''''<br />
<br />
* The developer can write the plugin without interfering with any other code except the API. This means there are a great bundle of methods like setters and getters which help writing good code.<br />
* UI team can make any changes to the core of the application, but as long as the API stays the same, the plugins will work. This way, the application can be improved and the developer won’t have to fix the code in order for it to work. New versions of the UI can be launched and the plugins will be compatible.<br />
* Event handling - the application will notify the plugin (via the API) about the events that happen inside. Consider, for example, the addition of a new device to the unit. The developer will know, by simply listening to an event, that a device was added and so, (s)he will write the code in such a way that it will take into account the event. The user experience will be greatly improved.<br />
* Asynchronous getters and setters - because most of the actions that happen inside the UI is asynchronous, so are the API’s method written. Most of them have a signature like this: function getXXX(obj, onSuccess, onFailure), where ‘onSuccess’ and ‘onFailure’ are callback functions which are called based on the result of the call.<br />
* No more global variables to manipulate. Everything is handled through getters/setters via API.<br />
* An API reference documentation: every method and its parameters is carefully documented so that the developer would know what the function does, how to call it and what it will return.<br />
* A couple of guidelines will be given to help developers write better code in such a way that two different plugins won’t “harm” each other. The module pattern will be used as a design pattern in order to put a plugin code inside a namespace. Also, this module helps in writing code which is easier to read and use.<br />
* It will be easier for the developers to write the code by using a new feature in the UI which generates the skeleton for the plugin.<br />
<br />
'''''What is the API reference documentation ?'''''<br />
<br />
This is the part which makes the API usable. Every aspect of the API, no matter how trivial, will be stated explicitly. It contains:<br />
<br />
* a description of all the data structures it depends upon<br />
* a description of all the function signatures:<br />
** function names<br />
** function parameters (names and types)<br />
** return type of the function<br />
** if it throws any exceptions or not<br />
<br />
'''''Where is the list of functions which were replaced ?'''''<br />
<br />
In the API reference documentation the developer can find out if a function replaces an old one.<br />
<br />
'''''Why should a developer write plugins using the API when it can do some “reverse engineering” and directly access any object/functionality of the application ?'''''<br />
<br />
It is not mandatory to write the code for the plugin this way. Probably the plugin will work as long as changes are not made in the core of the application, but the API comes also with a guarantee that after application changes, the plugins will continue to work. The UI team and plugin developers have the same goal: to deliver the best experience to the user. This is where the API comes into place - an interface between the two.<br />
<br />
'''''Will the API be rewritten with each new UI release ?'''''<br />
<br />
No. It will be improved. The goal of the API is to provide a stable interface to the developer so that when changing the core of the application it won’t be necessary to rewrite the plugins.<br />
<br />
'''''Is this API going to change in the near future ?'''''<br />
<br />
It can be changed. There will be parts of it which are going to be marked as ‘deprecated’. This means that the parts will be candidates for being removed, or modified in a backward incompatible way. The developers will be advised on how are they to change their code in order to use the features which replace the deprecated parts.<br />
<br />
'''''Is the API complete ?'''''<br />
<br />
Almost. Most of the functionality is there, but developers are encouraged to request new features from the API which will be added in future releases.<br />
<br />
== Guidelines on writing Javascript code for plugins in UI7 ==<br />
<br />
* Use the module pattern to organize your code inside a namespace. Choose a well defined name for your namespace.<br />
* Generate an UUID for your plugin. This way you can use the events engine.<br />
* Use the provided API plugins to perform most of your stuff. If you can’t find an implemented method inside the API you can ASK for an implementation to it.<br />
* '''NEVER USE''' variables/functions which are not accessible through API ! They can be changed or removed at any time.<br />
* If you need to do a background job (ex: start a timer), use the events engine and register a ‘cleanup’ function in which you finish the job (clear the timer).<br />
* We encourage the use of try { … } catch { … } blocks everywhere in your functions so that errors don’t get propagated to the top of the application.<br />
* Start from the skeleton provided and expand it:<br />
<br />
<source lang="javascript"><br />
var MyPlugin = (function (api) {<br />
// example of unique identifier for this plugin...<br />
var uuid = 'B971F6C4-F315-4E2E-AD08-F029A9777517';<br />
<br />
var myModule = {};<br />
<br />
function doSomething() {<br />
// register to event ‘on_ui_cpanel_before_close’...<br />
api.registerEventHandler('on_ui_cpanel_before_close', myModule, ‘cleanUp’);<br />
// and do something... <br />
}<br />
<br />
function cleanUp() {<br />
// perform clean up...<br />
}<br />
<br />
myModule = {<br />
uuid: uuid,<br />
doSomething: doSomething,<br />
cleanUp: cleanUp<br />
};<br />
return myModule;<br />
})(api);<br />
</source><br />
<br />
Your plugin functions will be accessible via ''MyPlugin.doSomething()'' construction.<br />
When the user will leave the cpanel, your plugin will be noticed via event ''‘on_ui_cpanel_before_close’''; this way you can perform the necessary cleanup.<br />
<br />
== JavaScript API ==<br />
<br />
''Defined in'': api.js<br />
<br />
=== Class Summary ===<br />
<br />
----<br />
<br />
'''API(config, application, ui)''' <br />
<br />
- API class for plugins<br />
<br />
'''Parameters:'''<br />
<br />
* {object} config - holds configuration data<br />
* {object} application - application layer<br />
* {object} ui - interface<br />
<br />
=== Method Summary ===<br />
<br />
----<br />
<br />
==== {Object} cloneObject(obj) ====<br />
<br />
- Clones a given object<br />
<br />
- Replaces: cloneObject()<br />
<br />
'''Parameters:'''<br />
<br />
* {object} obj - object to be cloned<br />
<br />
'''Returns:'''<br />
<br />
* {Object}<br />
<br />
==== {string} getCpanelContent() ====<br />
<br />
- Retrieves cpanel content<br />
<br />
- Replaces: get_panel_html()<br />
<br />
'''Returns:'''<br />
<br />
* {string} HTML code set in cpanel<br />
<br />
==== {number} getCpanelDeviceId() ====<br />
<br />
- Returns device id for current opened cpanel or 0 if not found<br />
<br />
'''Returns:'''<br />
<br />
* {number} - device ID<br />
<br />
==== getCurrentHouseMode(onSuccess, onFailure, context) ====<br />
<br />
- Performs a data request to retrieve the current house mode<br />
<br />
'''Parameters:'''<br />
<br />
* {*} onSuccess Optional - function to be called if the call is successfull<br />
* {*} onFailure Optional - function to be called if the call fails<br />
* {object} context Optional - context in which to execute the functions of success and/or failure<br />
<br />
==== {number} getDeviceIndex(deviceId) ====<br />
<br />
- Retrieves device index for given device id<br />
<br />
- Replaces: get_device_index()<br />
<br />
'''Parameters:'''<br />
<br />
* {number} deviceId - id of the device<br />
<br />
'''Returns:'''<br />
<br />
* {number}<br />
<br />
==== {*} getDeviceObject(deviceId) ====<br />
<br />
- Retrieves device object given its id<br />
<br />
- Replaces: get_device_obj()<br />
<br />
'''Parameters:'''<br />
<br />
* {number} deviceId - id of the device<br />
<br />
'''Returns:'''<br />
<br />
* {number}<br />
<br />
===={object} getDeviceState(deviceId, service, variable, options)====<br />
<br />
- Retrieves device state for a device (it can be either read from user data or lu status, depending on the options set)<br />
<br />
'''Parameters:'''<br />
<br />
* {number} deviceId - id of the device<br />
* {string} service - name of the service<br />
* {string} variable - name of the variable<br />
* {object} options Optional - list of options like: 'dynamic': (true - lu_status will be used [default], false - user_data will be used)<br />
<br />
'''Returns:'''<br />
<br />
* {object} value for a given variable<br />
<br />
==== {Object|Boolean} getDeviceTemplate(deviceId) ====<br />
<br />
- Returns device template for a given device id<br />
<br />
'''Parameters:'''<br />
<br />
* {number} deviceId - id of the device<br />
<br />
'''Returns:'''<br />
<br />
* {Object|Boolean}<br />
<br />
==== {*} getDisplayedDeviceName(deviceId) ====<br />
<br />
- Retrieves displayed device name or 'unnamed device' if device doesn't have a name or undefined if device not found<br />
<br />
'''Parameters:'''<br />
<br />
* {number} deviceId - id of the device<br />
<br />
'''Returns:'''<br />
<br />
* {*} if device is found a string which contains the device name or 'Unnamed device' if device name is not set, or undefined if device wasn't found<br />
<br />
==== {*} getEventDefinition(deviceType) ====<br />
<br />
- Retrieves event list for a given device type<br />
<br />
- Replaces: get_event_definition() <br />
<br />
'''Parameters:'''<br />
<br />
* {string} deviceType - type of device<br />
<br />
'''Returns:'''<br />
<br />
* {*}<br />
<br />
==== {*} getListOfDevices() ====<br />
<br />
- Returns the list of devices from userdata<br />
<br />
'''Returns:'''<br />
<br />
* {*}<br />
<br />
==== getLuSdata(onSuccess, onFailure, context) ====<br />
<br />
- Performs a data request to retrieve lu_sdata<br />
<br />
'''Parameters:'''<br />
<br />
* {*} onSuccess Optional - function to be called if the call is successfull<br />
* {*} onFailure Optional - function to be called if the call fails<br />
* {object} context Optional - context in which to execute the functions of success and/or failure<br />
<br />
==== {*|Object} getRoomObject(roomId) ====<br />
<br />
- Returns room object given a room id<br />
<br />
- Replaces: get_room_by_id()<br />
<br />
'''Parameters:'''<br />
<br />
* {number} roomId - id of the room<br />
<br />
'''Returns:'''<br />
<br />
* {*|Object}<br />
<br />
==== {*} getUserData() ====<br />
<br />
- Retrieves userData or null if error<br />
<br />
- Replaces: jsonp.ud<br />
<br />
'''Returns:'''<br />
<br />
* {*} object containing userdata<br />
<br />
==== registerEventHandler(eventName, object, functionName) ====<br />
<br />
- Register an event handler.<br />
<br />
'''Parameters:'''<br />
<br />
* {string} eventName - name of the event to register to<br />
* {object} object - the object which registers to the event<br />
* {string} functionName - the name of the function to be executed if event triggers<br />
<br />
==== runUpnpCode(code, options, onSuccess, onFailure, context) ====<br />
<br />
- Runs given Upnp code<br />
<br />
'''Parameters:'''<br />
<br />
* {string} code - code to execute<br />
* {object} options Optional - optionally options to be supplied (will be documented later)<br />
* {*} onSuccess Optional - function to be called if the call is successfull<br />
* {*} onFailure Optional - function to be called if the call fails<br />
* {object} context Optional - context in which to execute the functions of success and/or failure<br />
<br />
==== setCpanelContent(html) ====<br />
<br />
- Sets content for the cpanel<br />
<br />
- Replaces: set_panel_html()<br />
<br />
'''Parameters:'''<br />
<br />
* {string} html - the new content of the cpanel<br />
<br />
==== setCurrentHouseMode(modeValue, onSuccess, onFailure, context) ====<br />
<br />
- Sets current house mode<br />
<br />
'''Parameters:'''<br />
<br />
* {number} modeValue - new value for the house mode<br />
* {*} onSuccess Optional - function to be called if the call is successfull<br />
* {*} onFailure Optional - function to be called if the call fails<br />
* {object} context Optional - context in which to execute the functions of success and/or failure<br />
<br />
==== setDeviceStateVariable(deviceId, service, variable, value, onSuccess, onFailure, context) ====<br />
<br />
- Sets state for a device variable using variableset request.<br />
<br />
- Replaces: set_device_state()<br />
<br />
'''Parameters:'''<br />
<br />
* {number} deviceId - id of the device<br />
* {string} service - name of the service<br />
* {string} variable - name of the variable<br />
* {*} value - new value for the variable<br />
* {*} onSuccess Optional - function to be called if the call is successfull<br />
* {*} onFailure Optional - function to be called if the call fails<br />
* {object} context Optional - context in which to execute the functions of success and/or failure<br />
<br />
<br />
=== Events ===<br />
<br />
----<br />
<br />
The list of available events can be obtained with the following command:<br />
<br />
'''api.getListOfSupportedEvents()'''<br />
<br />
* on_startup_showModalLoading<br />
** triggered before loading resources in the browser<br />
*on_startup_luStatusLoaded<br />
** triggered after luStatus was successfully parsed<br />
** parameter: luStatusObject<br />
* on_startup_show2gInterface<br />
** triggered after requesting account devices only if UI is not in ‘local mode’ and ‘slowConnection’ flag is set<br />
* on_ui_requireSave<br />
** triggered if user data was changed and save wasn’t issued<br />
* on_ui_userDataFirstLoaded<br />
** fired if user data was loaded for the first time<br />
* on_ui_staticDataAdded<br />
** fired if static_data was added to user data<br />
** parameter: staticDataObject<br />
* on_ui_staticDataChanged<br />
** fired if static_data was changed after parsing user data<br />
** parameter: changedStaticDataObject<br />
* on_ui_staticDataRemoved<br />
** fired if static_data was removed after parsing user data<br />
** parameter: idForRemovedStaticDataObject<br />
* on_ui_setupDeviceAdded<br />
** fired if new setup device (menu item) is added<br />
** parameter: setupDeviceObject<br />
* on_ui_setupDeviceChanged<br />
** fired if setup device (menu item) is changed<br />
** parameter: changedSetupDeviceObject<br />
* on_ui_setupDeviceRemoved<br />
** fired if setup device (menu item) is removed<br />
** parameter: idForRemovedSetupDeviceObject<br />
* on_ui_sectionAdded<br />
** triggered when new section is added<br />
** parameter: sectionObject<br />
* on_ui_sectionChanged<br />
** fired after section was changed<br />
** parameter: changedSectionObject<br />
* on_ui_sectionRemoved<br />
** fired after section was removed<br />
** parameter: idForRemovedSectionObject<br />
* on_ui_roomAdded<br />
** fired when new room was added to user data<br />
** parameter: roomObject<br />
* on_ui_roomChanged<br />
** fired after room was changed<br />
** parameter: changedRoomObject<br />
* on_ui_roomRemoved<br />
** fired after room was removed from user data<br />
** parameter: idForRemovedRoomObject<br />
* on_ui_deviceAdded<br />
** fired after device was added to user data<br />
** parameter: deviceObject<br />
*** wrapper object for<br />
**** device: this is the actual object representing the device<br />
**** deviceTemplate: object with the static data associated to this device type<br />
* on_ui_deviceChanged<br />
** fired after device was found changed in user data<br />
** parameter: changedDeviceObject<br />
*** wrapper object for<br />
**** device: this is the actual object representing the device<br />
**** deviceTemplate: object with the static data associated to this device type<br />
* on_ui_deviceRemoved<br />
** fired after device was found removed from user data<br />
** parameter: idForRemovedDeviceObject<br />
* on_ui_deviceJobsReceived<br />
** fired when jobs are found for a device in lu_status<br />
** parameter: deviceObjectFromLuStatus<br />
* on_ui_sceneAdded<br />
** fired after scene was added<br />
** parameter: sceneObject<br />
* on_ui_sceneChanged<br />
** fired after scene was changed<br />
** parameter: changedSceneObject<br />
* on_ui_sceneChanged<br />
** fired when scene is removed<br />
** parameter: idForRemovedSceneObject<br />
* on_ui_pluginAdded<br />
** triggered when plugin is added to user data<br />
** parameter: pluginObject<br />
* on_ui_pluginChanged<br />
** triggered when plugin is changed<br />
** parameter: changedPluginObject<br />
* on_ui_pluginRemoved<br />
** triggered when plugin is removed<br />
** parameter: idForRemovedPluginObject<br />
* on_ui_extraSubmenuItemAdded<br />
** triggered when extra submenu item is added<br />
** parameter: extraSubmenuItemObject<br />
*** wrapper for:<br />
**** submenuItem: object containing submenu item<br />
**** deviceType: string which contains the type of device for which the submenu item is added<br />
* on_ui_extraSubmenuItemChanged<br />
** triggered when extra submenu item is changed<br />
** parameter: changedExtraSubmenuItemObject<br />
*** wrapper for:<br />
**** oldObj: contains previous submenu item<br />
**** newObj: wrapper for:<br />
***** submenuItem: object containing submenu item<br />
***** deviceType: string which contains the type of device for which the submenu item is added<br />
* on_ui_extraSubmenuItemRemoved:<br />
** triggered when an extra submenu item is removed<br />
** parameter: idForRemovedExtraSubmenuItemObject<br />
* on_ui_cardAdded<br />
** triggered when card is added to user data<br />
** parameter: cardObject<br />
* on_ui_cardChanged<br />
** triggered when card is found changed in user data<br />
** parameter: changedCardObject<br />
* on_ui_cardRemoved<br />
** triggered when card is removed from user data<br />
** parameter: idForRemovedCardObject<br />
* on_ui_jobsUpdated<br />
** triggered when job is updated in lu_status<br />
** parameter: luStatusJobsObject<br />
* on_ui_deviceStatusChanged<br />
** triggered when device status is changed<br />
** parameter: deviceObjectFromLuStatus<br />
* on_ui_syncClock<br />
** triggered after lu_status is parsed<br />
** parameter: luStatusLocalTime<br />
* on_ui_initFinished<br />
** fired when init has finished (UI should be ready now)<br />
* on_ui_setUserAuthenticated<br />
** fired after login is successful<br />
* on_ui_saveFinished<br />
** fired after save is finished<br />
* on_ui_initNotLogged<br />
** triggered if user is not logged in<br />
* on_ui_alertsUpdated<br />
** fired after alert list was updated<br />
* on_ui_refreshDashboardCards<br />
** triggered when dashboard cards are refreshed<br />
* on_ui_engineAvailable<br />
** triggered if engine is not busy<br />
* on_ui_2GEnabled<br />
** triggered when parsing lu_status if 2G is enabled<br />
* on_ui_userDataSetTemperatureFormat<br />
** triggered after temperature format is set in user data<br />
** parameter: userDataObject<br />
* on_ui_userDataLoaded<br />
** triggered after user data parsing is completed<br />
* on_parseUserData<br />
** triggered when user data parsing is started<br />
* on_ui_accountUnitsLoaded<br />
** fired after account lis from MMS was successfully loaded<br />
* accountInformationLoaded<br />
** triggered after account information is loaded<br />
** parameter: accountInfoObject<br />
* on_ui_finishDrawingMenu<br />
** triggered after parsing of user data setup devices has finished<br />
* on_ui_deviceTypeChanged<br />
** triggered if device type for a device has changed<br />
** parameter: deviceObject<br />
*** wrapper object for<br />
**** device: this is the actual object representing the device<br />
**** deviceTemplate: object with the static data associated to this device type<br />
* on_ui_hideModalLoading<br />
** triggered each time a time consuming job finishes (so that UI can hide modal loading)<br />
* on_ui_showUserDataSaveFailure<br />
** triggered if user data save has failed<br />
* on_ui_showErrorMessage<br />
** fired if application has error message to send to the UI<br />
* on_ui_cpanel_before_close<br />
** fired before closing the cpanel to allow plugins to cleanup their data<br />
** parameters: idForDeviceWhichOpenedTheCpanel<br />
<br />
<br />
=== Example files for UI7 ===<br />
<br />
We use the HomeCare plugin for example. Below you can download the JSON and JavaScript files for both UI5 and UI7:<br />
<br />
[[File:HomeCare.zip]]</div>Andreimioshttp://wiki.mios.com/index.php/File:HomeCare.zipFile:HomeCare.zip2014-10-06T12:21:23Z<p>Andreimios: </p>
<hr />
<div></div>Andreimioshttp://wiki.mios.com/index.php/JavaScript_APIJavaScript API2014-10-06T08:54:42Z<p>Andreimios: </p>
<hr />
<div>== Usage ==<br />
<pre>"Tabs": [<br />
{<br />
"Label": {<br />
"lang_tag": "users",<br />
"text": "Users" <br />
},<br />
"Position": "0",<br />
"TabType": "javascript",<br />
"ScriptName": "I_HomeCare.js",<br />
"Function": "showUsers"<br />
}, </pre> <br />
To generate a tab using your JavaScript functions you need to specify this by setting ''TabType'' to '''''javascript'''''. Then, you need to specify the script file's name and which function in this file will be used to draw the tab's content. That function will have one argument, which is the device number.<br> <br />
<br />
==== &lt;functionName&gt; (deviceNumber) ====<br />
<br />
This is the tab rendering function. The [[#set_panel_html_.28html.29 | set_panel_html]] function must be called at the end.<br> <br />
<br />
'''Input:''' <br />
<br />
*deviceNumber (number)<br><br />
<br />
'''Output:''' <br />
<br />
*nothing<br />
<br />
<br><br />
<br />
== Variables ==<br />
<br />
==== jsonp.ud ====<br />
<br />
This is the user data. <br />
<br />
*'''Type''': object <br />
*'''Members''': <br />
**devices (array) <br />
**scenes (array) <br />
**users (array) <br />
**rooms (array) <br />
**eventList (array) <br />
**etc.<br />
<br />
<br> <br />
<br />
==== jsonp.ud.devices ====<br />
<br />
*'''Type''': array <br />
*'''Members''': <br />
**id (number) <br />
**device_type (string) <br />
**room (number) <br />
**name (string) <br />
**category_num (number) <br />
**etc.<br />
<br />
<br> <br />
<br />
==== jsonp.ud.scenes ====<br />
<br />
*'''Type''': array <br />
*'''Members''': <br />
**id (number) <br />
**name (string) <br />
**room (number) <br />
**Timer_ids (array) <br />
**Timer (object) <br />
**etc.<br />
<br />
<br> <br />
<br />
== Functions ==<br />
<br />
==== get_device_state (deviceId, serviceId, variable, dynamic) ====<br />
<br />
'''Input:''' <br />
<br />
*deviceId (number)<br />
*serviceId (string)<br />
*variable (string)<br />
*dynamic (number): if '''1''', the variable's value is taken from ''lu_status'', else, the variable's value is taken from ''user_data''. ''user_data'' is read at Luup startup, so for variables that change their value frequently (like Watts, Temperature, etc.) ''dynamic'' should be '''1'''.<br />
<br />
'''Output:''' <br />
<br />
*variable value (string or ''undefined'')<br />
<br />
<br><br />
<br />
==== set_device_state (deviceId, serviceId, variable, value, dynamic) ====<br />
<br />
'''Input:''' <br />
<br />
*deviceId (number)<br />
*serviceId (string)<br />
*variable (string)<br />
*value (string)<br />
*dynamic (number): if '''1''', the variable's value is saved to ''lu_status'' (the value is lost after Luup is restarted), else, the variable's value is saved to a copy of ''user_data''; the real user_data is updated when LuaUPnP is restarted.<br />
<br />
'''Output:''' <br />
<br />
*''true'' if the operation succeeded, ''false'' otherwise<br />
<br />
<br><br />
<br />
==== _console (str) ====<br />
<br />
'''Input:''' <br />
<br />
*str (string): text to be written in the console. You need to have FireBug installed in order to have a console.<br />
<br />
'''Output:''' <br />
<br />
*nothing<br />
<br />
<br><br />
<br />
==== set_panel_html (html) ====<br />
<br />
Used in the tab rendering functions. <br />
<br />
'''Input:''' <br />
<br />
*html (string): The html to be used for generating the tab content.<br />
<br />
'''Output:''' <br />
<br />
*nothing<br />
<br />
[[Category:Development]]<br />
<br />
= JavaScript API for UI7 =<br />
<br />
== Introduction ==<br />
<br />
One of the new features of UI7 is the Javascript API for writing plugins. This is a free programming interface which is robust, well documented and comes with a guarantee that it will be compatible with the following UI releases.<br />
<br />
'''''What is this “API” ?'''''<br />
<br />
Simply said: it is a layer between the UI and the plugin developer. This way, the developer can use the features available in the UI by interacting only with the API. By using the new features available in the API, the overall user experience can be visibly improved.<br />
<br />
'''''How does it work ?'''''<br />
<br />
The API comes in the form of a library which exposes to the developer the objects and methods/functions needed to implement functionality in their plugins.<br />
<br />
'''''How is this different from the previous way of writing plugins ?'''''<br />
<br />
The developers were writing Javascript code and they had full access to the core of the application. There were a couple of objects and functions written by the UI team which were easing the work for the developer.<br />
By using the new API, the developer can write code without interfering with the core of the application.<br />
<br />
'''''What is new ?'''''<br />
<br />
* The developer can write the plugin without interfering with any other code except the API. This means there are a great bundle of methods like setters and getters which help writing good code.<br />
* UI team can make any changes to the core of the application, but as long as the API stays the same, the plugins will work. This way, the application can be improved and the developer won’t have to fix the code in order for it to work. New versions of the UI can be launched and the plugins will be compatible.<br />
* Event handling - the application will notify the plugin (via the API) about the events that happen inside. Consider, for example, the addition of a new device to the unit. The developer will know, by simply listening to an event, that a device was added and so, (s)he will write the code in such a way that it will take into account the event. The user experience will be greatly improved.<br />
* Asynchronous getters and setters - because most of the actions that happen inside the UI is asynchronous, so are the API’s method written. Most of them have a signature like this: function getXXX(obj, onSuccess, onFailure), where ‘onSuccess’ and ‘onFailure’ are callback functions which are called based on the result of the call.<br />
* No more global variables to manipulate. Everything is handled through getters/setters via API.<br />
* An API reference documentation: every method and its parameters is carefully documented so that the developer would know what the function does, how to call it and what it will return.<br />
* A couple of guidelines will be given to help developers write better code in such a way that two different plugins won’t “harm” each other. The module pattern will be used as a design pattern in order to put a plugin code inside a namespace. Also, this module helps in writing code which is easier to read and use.<br />
* It will be easier for the developers to write the code by using a new feature in the UI which generates the skeleton for the plugin.<br />
<br />
'''''What is the API reference documentation ?'''''<br />
<br />
This is the part which makes the API usable. Every aspect of the API, no matter how trivial, will be stated explicitly. It contains:<br />
<br />
* a description of all the data structures it depends upon<br />
* a description of all the function signatures:<br />
** function names<br />
** function parameters (names and types)<br />
** return type of the function<br />
** if it throws any exceptions or not<br />
<br />
'''''Where is the list of functions which were replaced ?'''''<br />
<br />
In the API reference documentation the developer can find out if a function replaces an old one.<br />
<br />
'''''Why should a developer write plugins using the API when it can do some “reverse engineering” and directly access any object/functionality of the application ?'''''<br />
<br />
It is not mandatory to write the code for the plugin this way. Probably the plugin will work as long as changes are not made in the core of the application, but the API comes also with a guarantee that after application changes, the plugins will continue to work. The UI team and plugin developers have the same goal: to deliver the best experience to the user. This is where the API comes into place - an interface between the two.<br />
<br />
'''''Will the API be rewritten with each new UI release ?'''''<br />
<br />
No. It will be improved. The goal of the API is to provide a stable interface to the developer so that when changing the core of the application it won’t be necessary to rewrite the plugins.<br />
<br />
'''''Is this API going to change in the near future ?'''''<br />
<br />
It can be changed. There will be parts of it which are going to be marked as ‘deprecated’. This means that the parts will be candidates for being removed, or modified in a backward incompatible way. The developers will be advised on how are they to change their code in order to use the features which replace the deprecated parts.<br />
<br />
'''''Is the API complete ?'''''<br />
<br />
Almost. Most of the functionality is there, but developers are encouraged to request new features from the API which will be added in future releases.<br />
<br />
== Guidelines on writing Javascript code for plugins in UI7 ==<br />
<br />
* Use the module pattern to organize your code inside a namespace. Choose a well defined name for your namespace.<br />
* Generate an UUID for your plugin. This way you can use the events engine.<br />
* Use the provided API plugins to perform most of your stuff. If you can’t find an implemented method inside the API you can ASK for an implementation to it.<br />
* '''NEVER USE''' variables/functions which are not accessible through API ! They can be changed or removed at any time.<br />
* If you need to do a background job (ex: start a timer), use the events engine and register a ‘cleanup’ function in which you finish the job (clear the timer).<br />
* We encourage the use of try { … } catch { … } blocks everywhere in your functions so that errors don’t get propagated to the top of the application.<br />
* Start from the skeleton provided and expand it:<br />
<br />
<source lang="javascript"><br />
var MyPlugin = (function (api) {<br />
// example of unique identifier for this plugin...<br />
var uuid = 'B971F6C4-F315-4E2E-AD08-F029A9777517';<br />
<br />
var myModule = {};<br />
<br />
function doSomething() {<br />
// register to event ‘on_ui_cpanel_before_close’...<br />
api.registerEventHandler('on_ui_cpanel_before_close', myModule, ‘cleanUp’);<br />
// and do something... <br />
}<br />
<br />
function cleanUp() {<br />
// perform clean up...<br />
}<br />
<br />
myModule = {<br />
uuid: uuid,<br />
doSomething: doSomething,<br />
cleanUp: cleanUp<br />
};<br />
return myModule;<br />
})(api);<br />
</source><br />
<br />
Your plugin functions will be accessible via ''MyPlugin.doSomething()'' construction.<br />
When the user will leave the cpanel, your plugin will be noticed via event ''‘on_ui_cpanel_before_close’''; this way you can perform the necessary cleanup.<br />
<br />
== JavaScript API ==<br />
<br />
''Defined in'': api.js<br />
<br />
=== Class Summary ===<br />
<br />
----<br />
<br />
'''API(config, application, ui)''' <br />
<br />
- API class for plugins<br />
<br />
'''Parameters:'''<br />
<br />
* {object} config - holds configuration data<br />
* {object} application - application layer<br />
* {object} ui - interface<br />
<br />
=== Method Summary ===<br />
<br />
----<br />
<br />
==== {Object} cloneObject(obj) ====<br />
<br />
- Clones a given object<br />
<br />
- Replaces: cloneObject()<br />
<br />
'''Parameters:'''<br />
<br />
* {object} obj - object to be cloned<br />
<br />
'''Returns:'''<br />
<br />
* {Object}<br />
<br />
==== {string} getCpanelContent() ====<br />
<br />
- Retrieves cpanel content<br />
<br />
- Replaces: get_panel_html()<br />
<br />
'''Returns:'''<br />
<br />
* {string} HTML code set in cpanel<br />
<br />
==== {number} getCpanelDeviceId() ====<br />
<br />
- Returns device id for current opened cpanel or 0 if not found<br />
<br />
'''Returns:'''<br />
<br />
* {number} - device ID<br />
<br />
==== getCurrentHouseMode(onSuccess, onFailure, context) ====<br />
<br />
- Performs a data request to retrieve the current house mode<br />
<br />
'''Parameters:'''<br />
<br />
* {*} onSuccess Optional - function to be called if the call is successfull<br />
* {*} onFailure Optional - function to be called if the call fails<br />
* {object} context Optional - context in which to execute the functions of success and/or failure<br />
<br />
==== {number} getDeviceIndex(deviceId) ====<br />
<br />
- Retrieves device index for given device id<br />
<br />
- Replaces: get_device_index()<br />
<br />
'''Parameters:'''<br />
<br />
* {number} deviceId - id of the device<br />
<br />
'''Returns:'''<br />
<br />
* {number}<br />
<br />
==== {*} getDeviceObject(deviceId) ====<br />
<br />
- Retrieves device object given its id<br />
<br />
- Replaces: get_device_obj()<br />
<br />
'''Parameters:'''<br />
<br />
* {number} deviceId - id of the device<br />
<br />
'''Returns:'''<br />
<br />
* {number}<br />
<br />
===={object} getDeviceState(deviceId, service, variable, options)====<br />
<br />
- Retrieves device state for a device (it can be either read from user data or lu status, depending on the options set)<br />
<br />
'''Parameters:'''<br />
<br />
* {number} deviceId - id of the device<br />
* {string} service - name of the service<br />
* {string} variable - name of the variable<br />
* {object} options Optional - list of options like: 'dynamic': (true - lu_status will be used [default], false - user_data will be used)<br />
<br />
'''Returns:'''<br />
<br />
* {object} value for a given variable<br />
<br />
==== {Object|Boolean} getDeviceTemplate(deviceId) ====<br />
<br />
- Returns device template for a given device id<br />
<br />
'''Parameters:'''<br />
<br />
* {number} deviceId - id of the device<br />
<br />
'''Returns:'''<br />
<br />
* {Object|Boolean}<br />
<br />
==== {*} getDisplayedDeviceName(deviceId) ====<br />
<br />
- Retrieves displayed device name or 'unnamed device' if device doesn't have a name or undefined if device not found<br />
<br />
'''Parameters:'''<br />
<br />
* {number} deviceId - id of the device<br />
<br />
'''Returns:'''<br />
<br />
* {*} if device is found a string which contains the device name or 'Unnamed device' if device name is not set, or undefined if device wasn't found<br />
<br />
==== {*} getEventDefinition(deviceType) ====<br />
<br />
- Retrieves event list for a given device type<br />
<br />
- Replaces: get_event_definition() <br />
<br />
'''Parameters:'''<br />
<br />
* {string} deviceType - type of device<br />
<br />
'''Returns:'''<br />
<br />
* {*}<br />
<br />
==== {*} getListOfDevices() ====<br />
<br />
- Returns the list of devices from userdata<br />
<br />
'''Returns:'''<br />
<br />
* {*}<br />
<br />
==== getLuSdata(onSuccess, onFailure, context) ====<br />
<br />
- Performs a data request to retrieve lu_sdata<br />
<br />
'''Parameters:'''<br />
<br />
* {*} onSuccess Optional - function to be called if the call is successfull<br />
* {*} onFailure Optional - function to be called if the call fails<br />
* {object} context Optional - context in which to execute the functions of success and/or failure<br />
<br />
==== {*|Object} getRoomObject(roomId) ====<br />
<br />
- Returns room object given a room id<br />
<br />
- Replaces: get_room_by_id()<br />
<br />
'''Parameters:'''<br />
<br />
* {number} roomId - id of the room<br />
<br />
'''Returns:'''<br />
<br />
* {*|Object}<br />
<br />
==== {*} getUserData() ====<br />
<br />
- Retrieves userData or null if error<br />
<br />
- Replaces: jsonp.ud<br />
<br />
'''Returns:'''<br />
<br />
* {*} object containing userdata<br />
<br />
==== registerEventHandler(eventName, object, functionName) ====<br />
<br />
- Register an event handler.<br />
<br />
'''Parameters:'''<br />
<br />
* {string} eventName - name of the event to register to<br />
* {object} object - the object which registers to the event<br />
* {string} functionName - the name of the function to be executed if event triggers<br />
<br />
==== runUpnpCode(code, options, onSuccess, onFailure, context) ====<br />
<br />
- Runs given Upnp code<br />
<br />
'''Parameters:'''<br />
<br />
* {string} code - code to execute<br />
* {object} options Optional - optionally options to be supplied (will be documented later)<br />
* {*} onSuccess Optional - function to be called if the call is successfull<br />
* {*} onFailure Optional - function to be called if the call fails<br />
* {object} context Optional - context in which to execute the functions of success and/or failure<br />
<br />
==== setCpanelContent(html) ====<br />
<br />
- Sets content for the cpanel<br />
<br />
- Replaces: set_panel_html()<br />
<br />
'''Parameters:'''<br />
<br />
* {string} html - the new content of the cpanel<br />
<br />
==== setCurrentHouseMode(modeValue, onSuccess, onFailure, context) ====<br />
<br />
- Sets current house mode<br />
<br />
'''Parameters:'''<br />
<br />
* {number} modeValue - new value for the house mode<br />
* {*} onSuccess Optional - function to be called if the call is successfull<br />
* {*} onFailure Optional - function to be called if the call fails<br />
* {object} context Optional - context in which to execute the functions of success and/or failure<br />
<br />
==== setDeviceStateVariable(deviceId, service, variable, value, onSuccess, onFailure, context) ====<br />
<br />
- Sets state for a device variable using variableset request.<br />
<br />
- Replaces: set_device_state()<br />
<br />
'''Parameters:'''<br />
<br />
* {number} deviceId - id of the device<br />
* {string} service - name of the service<br />
* {string} variable - name of the variable<br />
* {*} value - new value for the variable<br />
* {*} onSuccess Optional - function to be called if the call is successfull<br />
* {*} onFailure Optional - function to be called if the call fails<br />
* {object} context Optional - context in which to execute the functions of success and/or failure<br />
<br />
<br />
=== Events ===<br />
<br />
----<br />
<br />
The list of available events can be obtained with the following command:<br />
<br />
'''api.getListOfSupportedEvents()'''<br />
<br />
* on_startup_showModalLoading<br />
** triggered before loading resources in the browser<br />
*on_startup_luStatusLoaded<br />
** triggered after luStatus was successfully parsed<br />
** parameter: luStatusObject<br />
* on_startup_show2gInterface<br />
** triggered after requesting account devices only if UI is not in ‘local mode’ and ‘slowConnection’ flag is set<br />
* on_ui_requireSave<br />
** triggered if user data was changed and save wasn’t issued<br />
* on_ui_userDataFirstLoaded<br />
** fired if user data was loaded for the first time<br />
* on_ui_staticDataAdded<br />
** fired if static_data was added to user data<br />
** parameter: staticDataObject<br />
* on_ui_staticDataChanged<br />
** fired if static_data was changed after parsing user data<br />
** parameter: changedStaticDataObject<br />
* on_ui_staticDataRemoved<br />
** fired if static_data was removed after parsing user data<br />
** parameter: idForRemovedStaticDataObject<br />
* on_ui_setupDeviceAdded<br />
** fired if new setup device (menu item) is added<br />
** parameter: setupDeviceObject<br />
* on_ui_setupDeviceChanged<br />
** fired if setup device (menu item) is changed<br />
** parameter: changedSetupDeviceObject<br />
* on_ui_setupDeviceRemoved<br />
** fired if setup device (menu item) is removed<br />
** parameter: idForRemovedSetupDeviceObject<br />
* on_ui_sectionAdded<br />
** triggered when new section is added<br />
** parameter: sectionObject<br />
* on_ui_sectionChanged<br />
** fired after section was changed<br />
** parameter: changedSectionObject<br />
* on_ui_sectionRemoved<br />
** fired after section was removed<br />
** parameter: idForRemovedSectionObject<br />
* on_ui_roomAdded<br />
** fired when new room was added to user data<br />
** parameter: roomObject<br />
* on_ui_roomChanged<br />
** fired after room was changed<br />
** parameter: changedRoomObject<br />
* on_ui_roomRemoved<br />
** fired after room was removed from user data<br />
** parameter: idForRemovedRoomObject<br />
* on_ui_deviceAdded<br />
** fired after device was added to user data<br />
** parameter: deviceObject<br />
*** wrapper object for<br />
**** device: this is the actual object representing the device<br />
**** deviceTemplate: object with the static data associated to this device type<br />
* on_ui_deviceChanged<br />
** fired after device was found changed in user data<br />
** parameter: changedDeviceObject<br />
*** wrapper object for<br />
**** device: this is the actual object representing the device<br />
**** deviceTemplate: object with the static data associated to this device type<br />
* on_ui_deviceRemoved<br />
** fired after device was found removed from user data<br />
** parameter: idForRemovedDeviceObject<br />
* on_ui_deviceJobsReceived<br />
** fired when jobs are found for a device in lu_status<br />
** parameter: deviceObjectFromLuStatus<br />
* on_ui_sceneAdded<br />
** fired after scene was added<br />
** parameter: sceneObject<br />
* on_ui_sceneChanged<br />
** fired after scene was changed<br />
** parameter: changedSceneObject<br />
* on_ui_sceneChanged<br />
** fired when scene is removed<br />
** parameter: idForRemovedSceneObject<br />
* on_ui_pluginAdded<br />
** triggered when plugin is added to user data<br />
** parameter: pluginObject<br />
* on_ui_pluginChanged<br />
** triggered when plugin is changed<br />
** parameter: changedPluginObject<br />
* on_ui_pluginRemoved<br />
** triggered when plugin is removed<br />
** parameter: idForRemovedPluginObject<br />
* on_ui_extraSubmenuItemAdded<br />
** triggered when extra submenu item is added<br />
** parameter: extraSubmenuItemObject<br />
*** wrapper for:<br />
**** submenuItem: object containing submenu item<br />
**** deviceType: string which contains the type of device for which the submenu item is added<br />
* on_ui_extraSubmenuItemChanged<br />
** triggered when extra submenu item is changed<br />
** parameter: changedExtraSubmenuItemObject<br />
*** wrapper for:<br />
**** oldObj: contains previous submenu item<br />
**** newObj: wrapper for:<br />
***** submenuItem: object containing submenu item<br />
***** deviceType: string which contains the type of device for which the submenu item is added<br />
* on_ui_extraSubmenuItemRemoved:<br />
** triggered when an extra submenu item is removed<br />
** parameter: idForRemovedExtraSubmenuItemObject<br />
* on_ui_cardAdded<br />
** triggered when card is added to user data<br />
** parameter: cardObject<br />
* on_ui_cardChanged<br />
** triggered when card is found changed in user data<br />
** parameter: changedCardObject<br />
* on_ui_cardRemoved<br />
** triggered when card is removed from user data<br />
** parameter: idForRemovedCardObject<br />
* on_ui_jobsUpdated<br />
** triggered when job is updated in lu_status<br />
** parameter: luStatusJobsObject<br />
* on_ui_deviceStatusChanged<br />
** triggered when device status is changed<br />
** parameter: deviceObjectFromLuStatus<br />
* on_ui_syncClock<br />
** triggered after lu_status is parsed<br />
** parameter: luStatusLocalTime<br />
* on_ui_initFinished<br />
** fired when init has finished (UI should be ready now)<br />
* on_ui_setUserAuthenticated<br />
** fired after login is successful<br />
* on_ui_saveFinished<br />
** fired after save is finished<br />
* on_ui_initNotLogged<br />
** triggered if user is not logged in<br />
* on_ui_alertsUpdated<br />
** fired after alert list was updated<br />
* on_ui_refreshDashboardCards<br />
** triggered when dashboard cards are refreshed<br />
* on_ui_engineAvailable<br />
** triggered if engine is not busy<br />
* on_ui_2GEnabled<br />
** triggered when parsing lu_status if 2G is enabled<br />
* on_ui_userDataSetTemperatureFormat<br />
** triggered after temperature format is set in user data<br />
** parameter: userDataObject<br />
* on_ui_userDataLoaded<br />
** triggered after user data parsing is completed<br />
* on_parseUserData<br />
** triggered when user data parsing is started<br />
* on_ui_accountUnitsLoaded<br />
** fired after account lis from MMS was successfully loaded<br />
* accountInformationLoaded<br />
** triggered after account information is loaded<br />
** parameter: accountInfoObject<br />
* on_ui_finishDrawingMenu<br />
** triggered after parsing of user data setup devices has finished<br />
* on_ui_deviceTypeChanged<br />
** triggered if device type for a device has changed<br />
** parameter: deviceObject<br />
*** wrapper object for<br />
**** device: this is the actual object representing the device<br />
**** deviceTemplate: object with the static data associated to this device type<br />
* on_ui_hideModalLoading<br />
** triggered each time a time consuming job finishes (so that UI can hide modal loading)<br />
* on_ui_showUserDataSaveFailure<br />
** triggered if user data save has failed<br />
* on_ui_showErrorMessage<br />
** fired if application has error message to send to the UI<br />
* on_ui_cpanel_before_close<br />
** fired before closing the cpanel to allow plugins to cleanup their data<br />
** parameters: idForDeviceWhichOpenedTheCpanel</div>Andreimioshttp://wiki.mios.com/index.php/JavaScript_APIJavaScript API2014-10-06T08:53:10Z<p>Andreimios: </p>
<hr />
<div>== Usage ==<br />
<pre>"Tabs": [<br />
{<br />
"Label": {<br />
"lang_tag": "users",<br />
"text": "Users" <br />
},<br />
"Position": "0",<br />
"TabType": "javascript",<br />
"ScriptName": "I_HomeCare.js",<br />
"Function": "showUsers"<br />
}, </pre> <br />
To generate a tab using your JavaScript functions you need to specify this by setting ''TabType'' to '''''javascript'''''. Then, you need to specify the script file's name and which function in this file will be used to draw the tab's content. That function will have one argument, which is the device number.<br> <br />
<br />
==== &lt;functionName&gt; (deviceNumber) ====<br />
<br />
This is the tab rendering function. The [[#set_panel_html_.28html.29 | set_panel_html]] function must be called at the end.<br> <br />
<br />
'''Input:''' <br />
<br />
*deviceNumber (number)<br><br />
<br />
'''Output:''' <br />
<br />
*nothing<br />
<br />
<br><br />
<br />
== Variables ==<br />
<br />
==== jsonp.ud ====<br />
<br />
This is the user data. <br />
<br />
*'''Type''': object <br />
*'''Members''': <br />
**devices (array) <br />
**scenes (array) <br />
**users (array) <br />
**rooms (array) <br />
**eventList (array) <br />
**etc.<br />
<br />
<br> <br />
<br />
==== jsonp.ud.devices ====<br />
<br />
*'''Type''': array <br />
*'''Members''': <br />
**id (number) <br />
**device_type (string) <br />
**room (number) <br />
**name (string) <br />
**category_num (number) <br />
**etc.<br />
<br />
<br> <br />
<br />
==== jsonp.ud.scenes ====<br />
<br />
*'''Type''': array <br />
*'''Members''': <br />
**id (number) <br />
**name (string) <br />
**room (number) <br />
**Timer_ids (array) <br />
**Timer (object) <br />
**etc.<br />
<br />
<br> <br />
<br />
== Functions ==<br />
<br />
==== get_device_state (deviceId, serviceId, variable, dynamic) ====<br />
<br />
'''Input:''' <br />
<br />
*deviceId (number)<br />
*serviceId (string)<br />
*variable (string)<br />
*dynamic (number): if '''1''', the variable's value is taken from ''lu_status'', else, the variable's value is taken from ''user_data''. ''user_data'' is read at Luup startup, so for variables that change their value frequently (like Watts, Temperature, etc.) ''dynamic'' should be '''1'''.<br />
<br />
'''Output:''' <br />
<br />
*variable value (string or ''undefined'')<br />
<br />
<br><br />
<br />
==== set_device_state (deviceId, serviceId, variable, value, dynamic) ====<br />
<br />
'''Input:''' <br />
<br />
*deviceId (number)<br />
*serviceId (string)<br />
*variable (string)<br />
*value (string)<br />
*dynamic (number): if '''1''', the variable's value is saved to ''lu_status'' (the value is lost after Luup is restarted), else, the variable's value is saved to a copy of ''user_data''; the real user_data is updated when LuaUPnP is restarted.<br />
<br />
'''Output:''' <br />
<br />
*''true'' if the operation succeeded, ''false'' otherwise<br />
<br />
<br><br />
<br />
==== _console (str) ====<br />
<br />
'''Input:''' <br />
<br />
*str (string): text to be written in the console. You need to have FireBug installed in order to have a console.<br />
<br />
'''Output:''' <br />
<br />
*nothing<br />
<br />
<br><br />
<br />
==== set_panel_html (html) ====<br />
<br />
Used in the tab rendering functions. <br />
<br />
'''Input:''' <br />
<br />
*html (string): The html to be used for generating the tab content.<br />
<br />
'''Output:''' <br />
<br />
*nothing<br />
<br />
[[Category:Development]]<br />
<br />
= JavaScript API for UI7 =<br />
<br />
== Introduction ==<br />
<br />
One of the new features of UI7 is the Javascript API for writing plugins. This is a free programming interface which is robust, well documented and comes with a guarantee that it will be compatible with the following UI releases.<br />
<br />
'''''What is this “API” ?'''''<br />
<br />
Simply said: it is a layer between the UI and the plugin developer. This way, the developer can use the features available in the UI by interacting only with the API. By using the new features available in the API, the overall user experience can be visibly improved.<br />
<br />
'''''How does it work ?'''''<br />
<br />
The API comes in the form of a library which exposes to the developer the objects and methods/functions needed to implement functionality in their plugins.<br />
<br />
'''''How is this different from the previous way of writing plugins ?'''''<br />
<br />
The developers were writing Javascript code and they had full access to the core of the application. There were a couple of objects and functions written by the UI team which were easing the work for the developer.<br />
By using the new API, the developer can write code without interfering with the core of the application.<br />
<br />
'''''What is new ?'''''<br />
<br />
* The developer can write the plugin without interfering with any other code except the API. This means there are a great bundle of methods like setters and getters which help writing good code.<br />
* UI team can make any changes to the core of the application, but as long as the API stays the same, the plugins will work. This way, the application can be improved and the developer won’t have to fix the code in order for it to work. New versions of the UI can be launched and the plugins will be compatible.<br />
* Event handling - the application will notify the plugin (via the API) about the events that happen inside. Consider, for example, the addition of a new device to the unit. The developer will know, by simply listening to an event, that a device was added and so, (s)he will write the code in such a way that it will take into account the event. The user experience will be greatly improved.<br />
* Asynchronous getters and setters - because most of the actions that happen inside the UI is asynchronous, so are the API’s method written. Most of them have a signature like this: function getXXX(obj, onSuccess, onFailure), where ‘onSuccess’ and ‘onFailure’ are callback functions which are called based on the result of the call.<br />
* No more global variables to manipulate. Everything is handled through getters/setters via API.<br />
* An API reference documentation: every method and its parameters is carefully documented so that the developer would know what the function does, how to call it and what it will return.<br />
* A couple of guidelines will be given to help developers write better code in such a way that two different plugins won’t “harm” each other. The module pattern will be used as a design pattern in order to put a plugin code inside a namespace. Also, this module helps in writing code which is easier to read and use.<br />
* It will be easier for the developers to write the code by using a new feature in the UI which generates the skeleton for the plugin.<br />
<br />
'''''What is the API reference documentation ?'''''<br />
<br />
This is the part which makes the API usable. Every aspect of the API, no matter how trivial, will be stated explicitly. It contains:<br />
<br />
* a description of all the data structures it depends upon<br />
* a description of all the function signatures:<br />
** function names<br />
** function parameters (names and types)<br />
** return type of the function<br />
** if it throws any exceptions or not<br />
<br />
'''''Where is the list of functions which were replaced ?'''''<br />
<br />
In the API reference documentation the developer can find out if a function replaces an old one.<br />
<br />
'''''Why should a developer write plugins using the API when it can do some “reverse engineering” and directly access any object/functionality of the application ?'''''<br />
<br />
It is not mandatory to write the code for the plugin this way. Probably the plugin will work as long as changes are not made in the core of the application, but the API comes also with a guarantee that after application changes, the plugins will continue to work. The UI team and plugin developers have the same goal: to deliver the best experience to the user. This is where the API comes into place - an interface between the two.<br />
<br />
'''''Will the API be rewritten with each new UI release ?'''''<br />
<br />
No. It will be improved. The goal of the API is to provide a stable interface to the developer so that when changing the core of the application it won’t be necessary to rewrite the plugins.<br />
<br />
'''''Is this API going to change in the near future ?'''''<br />
<br />
It can be changed. There will be parts of it which are going to be marked as ‘deprecated’. This means that the parts will be candidates for being removed, or modified in a backward incompatible way. The developers will be advised on how are they to change their code in order to use the features which replace the deprecated parts.<br />
<br />
'''''Is the API complete ?'''''<br />
<br />
Almost. Most of the functionality is there, but developers are encouraged to request new features from the API which will be added in future releases.<br />
<br />
== Guidelines on writing Javascript code for plugins in UI7 ==<br />
<br />
* Use the module pattern to organize your code inside a namespace. Choose a well defined name for your namespace.<br />
* Generate an UUID for your plugin. This way you can use the events engine.<br />
* Use the provided API plugins to perform most of your stuff. If you can’t find an implemented method inside the API you can ASK for an implementation to it.<br />
* '''NEVER USE''' variables/functions which are not accessible through API ! They can be changed or removed at any time.<br />
* If you need to do a background job (ex: start a timer), use the events engine and register a ‘cleanup’ function in which you finish the job (clear the timer).<br />
* We encourage the use of try { … } catch { … } blocks everywhere in your functions so that errors don’t get propagated to the top of the application.<br />
* Start from the skeleton provided and expand it:<br />
<br />
<source lang="javascript"><br />
var MyPlugin = (function (api) {<br />
// example of unique identifier for this plugin...<br />
var uuid = 'B971F6C4-F315-4E2E-AD08-F029A9777517';<br />
<br />
var myModule = {};<br />
<br />
function doSomething() {<br />
// register to event ‘on_ui_cpanel_before_close’...<br />
api.registerEventHandler('on_ui_cpanel_before_close', myModule, ‘cleanUp’);<br />
// and do something... <br />
}<br />
<br />
function cleanUp() {<br />
// perform clean up...<br />
}<br />
<br />
myModule = {<br />
uuid: uuid,<br />
doSomething: doSomething,<br />
cleanUp: cleanUp<br />
};<br />
return myModule;<br />
})(api);<br />
</source><br />
<br />
Your plugin functions will be accessible via ''MyPlugin.doSomething()'' construction.<br />
When the user will leave the cpanel, your plugin will be noticed via event ''‘on_ui_cpanel_before_close’''; this way you can perform the necessary cleanup.<br />
<br />
== JavaScript API ==<br />
<br />
''Defined in'': api.js<br />
<br />
=== Class Summary ===<br />
<br />
----<br />
<br />
'''API(config, application, ui)''' <br />
<br />
- API class for plugins<br />
<br />
'''Parameters:'''<br />
<br />
* {object} config - holds configuration data<br />
* {object} application - application layer<br />
* {object} ui - interface<br />
<br />
=== Method Summary ===<br />
<br />
----<br />
<br />
==== {Object} cloneObject(obj) ====<br />
<br />
- Clones a given object<br />
<br />
- Replaces: cloneObject()<br />
<br />
'''Parameters:'''<br />
<br />
* {object} obj - object to be cloned<br />
<br />
'''Returns:'''<br />
<br />
* {Object}<br />
<br />
==== {string} getCpanelContent() ====<br />
<br />
- Retrieves cpanel content<br />
<br />
- Replaces: get_panel_html()<br />
<br />
'''Returns:'''<br />
<br />
* {string} HTML code set in cpanel<br />
<br />
==== {number} getCpanelDeviceId() ====<br />
<br />
- Returns device id for current opened cpanel or 0 if not found<br />
<br />
'''Returns:'''<br />
<br />
* {number} - device ID<br />
<br />
==== getCurrentHouseMode(onSuccess, onFailure, context) ====<br />
<br />
- Performs a data request to retrieve the current house mode<br />
<br />
'''Parameters:'''<br />
<br />
* {*} onSuccess Optional - function to be called if the call is successfull<br />
* {*} onFailure Optional - function to be called if the call fails<br />
* {object} context Optional - context in which to execute the functions of success and/or failure<br />
<br />
==== {number} getDeviceIndex(deviceId) ====<br />
<br />
- Retrieves device index for given device id<br />
<br />
- Replaces: get_device_index()<br />
<br />
'''Parameters:'''<br />
<br />
* {number} deviceId - id of the device<br />
<br />
'''Returns:'''<br />
<br />
* {number}<br />
<br />
==== {*} getDeviceObject(deviceId) ====<br />
<br />
- Retrieves device object given its id<br />
<br />
- Replaces: get_device_obj()<br />
<br />
'''Parameters:'''<br />
<br />
* {number} deviceId - id of the device<br />
<br />
'''Returns:'''<br />
<br />
* {number}<br />
<br />
===={object} getDeviceState(deviceId, service, variable, options)====<br />
<br />
- Retrieves device state for a device (it can be either read from user data or lu status, depending on the options set)<br />
<br />
'''Parameters:'''<br />
<br />
* {number} deviceId - id of the device<br />
* {string} service - name of the service<br />
* {string} variable - name of the variable<br />
* {object} options Optional - list of options like: 'dynamic': (true - lu_status will be used [default], false - user_data will be used)<br />
<br />
'''Returns:'''<br />
<br />
* {object} value for a given variable<br />
<br />
==== {Object|Boolean} getDeviceTemplate(deviceId) ====<br />
<br />
- Returns device template for a given device id<br />
<br />
'''Parameters:'''<br />
<br />
* {number} deviceId - id of the device<br />
<br />
'''Returns:'''<br />
<br />
* {Object|Boolean}<br />
<br />
==== {*} getDisplayedDeviceName(deviceId) ====<br />
<br />
- Retrieves displayed device name or 'unnamed device' if device doesn't have a name or undefined if device not found<br />
<br />
'''Parameters:'''<br />
<br />
* {number} deviceId - id of the device<br />
<br />
'''Returns:'''<br />
<br />
* {*} if device is found a string which contains the device name or 'Unnamed device' if device name is not set, or undefined if device wasn't found<br />
<br />
==== {*} getEventDefinition(deviceType) ====<br />
<br />
- Retrieves event list for a given device type<br />
<br />
- Replaces: get_event_definition() <br />
<br />
'''Parameters:'''<br />
<br />
* {string} deviceType - type of device<br />
<br />
'''Returns:'''<br />
<br />
* {*}<br />
<br />
==== {*} getListOfDevices() ====<br />
<br />
- Returns the list of devices from userdata<br />
<br />
'''Returns:'''<br />
<br />
* {*}<br />
<br />
==== getLuSdata(onSuccess, onFailure, context) ====<br />
<br />
- Performs a data request to retrieve lu_sdata<br />
<br />
'''Parameters:'''<br />
<br />
* {*} onSuccess Optional - function to be called if the call is successfull<br />
* {*} onFailure Optional - function to be called if the call fails<br />
* {object} context Optional - context in which to execute the functions of success and/or failure<br />
<br />
==== {*|Object} getRoomObject(roomId) ====<br />
<br />
- Returns room object given a room id<br />
<br />
- Replaces: get_room_by_id()<br />
<br />
'''Parameters:'''<br />
<br />
* {number} roomId - id of the room<br />
<br />
'''Returns:'''<br />
<br />
* {*|Object}<br />
<br />
==== {*} getUserData() ====<br />
<br />
- Retrieves userData or null if error<br />
<br />
- Replaces: jsonp.ud<br />
<br />
'''Returns:'''<br />
<br />
* {*} object containing userdata<br />
<br />
==== registerEventHandler(eventName, object, functionName) ====<br />
<br />
- Register an event handler.<br />
<br />
'''Parameters:'''<br />
<br />
* {string} eventName - name of the event to register to<br />
* {object} object - the object which registers to the event<br />
* {string} functionName - the name of the function to be executed if event triggers<br />
<br />
==== runUpnpCode(code, options, onSuccess, onFailure, context) ====<br />
<br />
- Runs given Upnp code<br />
<br />
'''Parameters:'''<br />
<br />
* {string} code - code to execute<br />
* {object} options Optional - optionally options to be supplied (will be documented later)<br />
* {*} onSuccess Optional - function to be called if the call is successfull<br />
* {*} onFailure Optional - function to be called if the call fails<br />
* {object} context Optional - context in which to execute the functions of success and/or failure<br />
<br />
==== setCpanelContent(html) ====<br />
<br />
- Sets content for the cpanel<br />
<br />
- Replaces: set_panel_html()<br />
<br />
'''Parameters:'''<br />
<br />
* {string} html - the new content of the cpanel<br />
<br />
==== setCurrentHouseMode(modeValue, onSuccess, onFailure, context) ====<br />
<br />
- Sets current house mode<br />
<br />
'''Parameters:'''<br />
<br />
* {number} modeValue - new value for the house mode<br />
* {*} onSuccess Optional - function to be called if the call is successfull<br />
* {*} onFailure Optional - function to be called if the call fails<br />
* {object} context Optional - context in which to execute the functions of success and/or failure<br />
<br />
==== setDeviceStateVariable(deviceId, service, variable, value, onSuccess, onFailure, context) ====<br />
<br />
- Sets state for a device variable using variableset request.<br />
<br />
- Replaces: set_device_state()<br />
<br />
'''Parameters:'''<br />
<br />
* {number} deviceId - id of the device<br />
* {string} service - name of the service<br />
* {string} variable - name of the variable<br />
* {*} value - new value for the variable<br />
* {*} onSuccess Optional - function to be called if the call is successfull<br />
* {*} onFailure Optional - function to be called if the call fails<br />
* {object} context Optional - context in which to execute the functions of success and/or failure<br />
<br />
=== Events ===<br />
<br />
The list of available events can be obtained with the following command:<br />
<br />
'''api.getListOfSupportedEvents()'''<br />
<br />
* on_startup_showModalLoading<br />
** triggered before loading resources in the browser<br />
*on_startup_luStatusLoaded<br />
** triggered after luStatus was successfully parsed<br />
** parameter: luStatusObject<br />
* on_startup_show2gInterface<br />
** triggered after requesting account devices only if UI is not in ‘local mode’ and ‘slowConnection’ flag is set<br />
* on_ui_requireSave<br />
** triggered if user data was changed and save wasn’t issued<br />
* on_ui_userDataFirstLoaded<br />
** fired if user data was loaded for the first time<br />
* on_ui_staticDataAdded<br />
** fired if static_data was added to user data<br />
** parameter: staticDataObject<br />
* on_ui_staticDataChanged<br />
** fired if static_data was changed after parsing user data<br />
** parameter: changedStaticDataObject<br />
* on_ui_staticDataRemoved<br />
** fired if static_data was removed after parsing user data<br />
** parameter: idForRemovedStaticDataObject<br />
* on_ui_setupDeviceAdded<br />
** fired if new setup device (menu item) is added<br />
** parameter: setupDeviceObject<br />
* on_ui_setupDeviceChanged<br />
** fired if setup device (menu item) is changed<br />
** parameter: changedSetupDeviceObject<br />
* on_ui_setupDeviceRemoved<br />
** fired if setup device (menu item) is removed<br />
** parameter: idForRemovedSetupDeviceObject<br />
* on_ui_sectionAdded<br />
** triggered when new section is added<br />
** parameter: sectionObject<br />
* on_ui_sectionChanged<br />
** fired after section was changed<br />
** parameter: changedSectionObject<br />
* on_ui_sectionRemoved<br />
** fired after section was removed<br />
** parameter: idForRemovedSectionObject<br />
* on_ui_roomAdded<br />
** fired when new room was added to user data<br />
** parameter: roomObject<br />
* on_ui_roomChanged<br />
** fired after room was changed<br />
** parameter: changedRoomObject<br />
* on_ui_roomRemoved<br />
** fired after room was removed from user data<br />
** parameter: idForRemovedRoomObject<br />
* on_ui_deviceAdded<br />
** fired after device was added to user data<br />
** parameter: deviceObject<br />
*** wrapper object for<br />
**** device: this is the actual object representing the device<br />
**** deviceTemplate: object with the static data associated to this device type<br />
* on_ui_deviceChanged<br />
** fired after device was found changed in user data<br />
** parameter: changedDeviceObject<br />
*** wrapper object for<br />
**** device: this is the actual object representing the device<br />
**** deviceTemplate: object with the static data associated to this device type<br />
* on_ui_deviceRemoved<br />
** fired after device was found removed from user data<br />
** parameter: idForRemovedDeviceObject<br />
* on_ui_deviceJobsReceived<br />
** fired when jobs are found for a device in lu_status<br />
** parameter: deviceObjectFromLuStatus<br />
* on_ui_sceneAdded<br />
** fired after scene was added<br />
** parameter: sceneObject<br />
* on_ui_sceneChanged<br />
** fired after scene was changed<br />
** parameter: changedSceneObject<br />
* on_ui_sceneChanged<br />
** fired when scene is removed<br />
** parameter: idForRemovedSceneObject<br />
* on_ui_pluginAdded<br />
** triggered when plugin is added to user data<br />
** parameter: pluginObject<br />
* on_ui_pluginChanged<br />
** triggered when plugin is changed<br />
** parameter: changedPluginObject<br />
* on_ui_pluginRemoved<br />
** triggered when plugin is removed<br />
** parameter: idForRemovedPluginObject<br />
* on_ui_extraSubmenuItemAdded<br />
** triggered when extra submenu item is added<br />
** parameter: extraSubmenuItemObject<br />
*** wrapper for:<br />
**** submenuItem: object containing submenu item<br />
**** deviceType: string which contains the type of device for which the submenu item is added<br />
* on_ui_extraSubmenuItemChanged<br />
** triggered when extra submenu item is changed<br />
** parameter: changedExtraSubmenuItemObject<br />
*** wrapper for:<br />
**** oldObj: contains previous submenu item<br />
**** newObj: wrapper for:<br />
***** submenuItem: object containing submenu item<br />
***** deviceType: string which contains the type of device for which the submenu item is added<br />
* on_ui_extraSubmenuItemRemoved:<br />
** triggered when an extra submenu item is removed<br />
** parameter: idForRemovedExtraSubmenuItemObject<br />
* on_ui_cardAdded<br />
** triggered when card is added to user data<br />
** parameter: cardObject<br />
* on_ui_cardChanged<br />
** triggered when card is found changed in user data<br />
** parameter: changedCardObject<br />
* on_ui_cardRemoved<br />
** triggered when card is removed from user data<br />
** parameter: idForRemovedCardObject<br />
* on_ui_jobsUpdated<br />
** triggered when job is updated in lu_status<br />
** parameter: luStatusJobsObject<br />
* on_ui_deviceStatusChanged<br />
** triggered when device status is changed<br />
** parameter: deviceObjectFromLuStatus<br />
* on_ui_syncClock<br />
** triggered after lu_status is parsed<br />
** parameter: luStatusLocalTime<br />
* on_ui_initFinished<br />
** fired when init has finished (UI should be ready now)<br />
* on_ui_setUserAuthenticated<br />
** fired after login is successful<br />
* on_ui_saveFinished<br />
** fired after save is finished<br />
* on_ui_initNotLogged<br />
** triggered if user is not logged in<br />
* on_ui_alertsUpdated<br />
** fired after alert list was updated<br />
* on_ui_refreshDashboardCards<br />
** triggered when dashboard cards are refreshed<br />
* on_ui_engineAvailable<br />
** triggered if engine is not busy<br />
* on_ui_2GEnabled<br />
** triggered when parsing lu_status if 2G is enabled<br />
* on_ui_userDataSetTemperatureFormat<br />
** triggered after temperature format is set in user data<br />
** parameter: userDataObject<br />
* on_ui_userDataLoaded<br />
** triggered after user data parsing is completed<br />
* on_parseUserData<br />
** triggered when user data parsing is started<br />
* on_ui_accountUnitsLoaded<br />
** fired after account lis from MMS was successfully loaded<br />
* accountInformationLoaded<br />
** triggered after account information is loaded<br />
** parameter: accountInfoObject<br />
* on_ui_finishDrawingMenu<br />
** triggered after parsing of user data setup devices has finished<br />
* on_ui_deviceTypeChanged<br />
** triggered if device type for a device has changed<br />
** parameter: deviceObject<br />
*** wrapper object for<br />
**** device: this is the actual object representing the device<br />
**** deviceTemplate: object with the static data associated to this device type<br />
* on_ui_hideModalLoading<br />
** triggered each time a time consuming job finishes (so that UI can hide modal loading)<br />
* on_ui_showUserDataSaveFailure<br />
** triggered if user data save has failed<br />
* on_ui_showErrorMessage<br />
** fired if application has error message to send to the UI<br />
* on_ui_cpanel_before_close<br />
** fired before closing the cpanel to allow plugins to cleanup their data<br />
** parameters: idForDeviceWhichOpenedTheCpanel</div>Andreimioshttp://wiki.mios.com/index.php/JavaScript_APIJavaScript API2014-10-06T08:42:09Z<p>Andreimios: </p>
<hr />
<div>== Usage ==<br />
<pre>"Tabs": [<br />
{<br />
"Label": {<br />
"lang_tag": "users",<br />
"text": "Users" <br />
},<br />
"Position": "0",<br />
"TabType": "javascript",<br />
"ScriptName": "I_HomeCare.js",<br />
"Function": "showUsers"<br />
}, </pre> <br />
To generate a tab using your JavaScript functions you need to specify this by setting ''TabType'' to '''''javascript'''''. Then, you need to specify the script file's name and which function in this file will be used to draw the tab's content. That function will have one argument, which is the device number.<br> <br />
<br />
==== &lt;functionName&gt; (deviceNumber) ====<br />
<br />
This is the tab rendering function. The [[#set_panel_html_.28html.29 | set_panel_html]] function must be called at the end.<br> <br />
<br />
'''Input:''' <br />
<br />
*deviceNumber (number)<br><br />
<br />
'''Output:''' <br />
<br />
*nothing<br />
<br />
<br><br />
<br />
== Variables ==<br />
<br />
==== jsonp.ud ====<br />
<br />
This is the user data. <br />
<br />
*'''Type''': object <br />
*'''Members''': <br />
**devices (array) <br />
**scenes (array) <br />
**users (array) <br />
**rooms (array) <br />
**eventList (array) <br />
**etc.<br />
<br />
<br> <br />
<br />
==== jsonp.ud.devices ====<br />
<br />
*'''Type''': array <br />
*'''Members''': <br />
**id (number) <br />
**device_type (string) <br />
**room (number) <br />
**name (string) <br />
**category_num (number) <br />
**etc.<br />
<br />
<br> <br />
<br />
==== jsonp.ud.scenes ====<br />
<br />
*'''Type''': array <br />
*'''Members''': <br />
**id (number) <br />
**name (string) <br />
**room (number) <br />
**Timer_ids (array) <br />
**Timer (object) <br />
**etc.<br />
<br />
<br> <br />
<br />
== Functions ==<br />
<br />
==== get_device_state (deviceId, serviceId, variable, dynamic) ====<br />
<br />
'''Input:''' <br />
<br />
*deviceId (number)<br />
*serviceId (string)<br />
*variable (string)<br />
*dynamic (number): if '''1''', the variable's value is taken from ''lu_status'', else, the variable's value is taken from ''user_data''. ''user_data'' is read at Luup startup, so for variables that change their value frequently (like Watts, Temperature, etc.) ''dynamic'' should be '''1'''.<br />
<br />
'''Output:''' <br />
<br />
*variable value (string or ''undefined'')<br />
<br />
<br><br />
<br />
==== set_device_state (deviceId, serviceId, variable, value, dynamic) ====<br />
<br />
'''Input:''' <br />
<br />
*deviceId (number)<br />
*serviceId (string)<br />
*variable (string)<br />
*value (string)<br />
*dynamic (number): if '''1''', the variable's value is saved to ''lu_status'' (the value is lost after Luup is restarted), else, the variable's value is saved to a copy of ''user_data''; the real user_data is updated when LuaUPnP is restarted.<br />
<br />
'''Output:''' <br />
<br />
*''true'' if the operation succeeded, ''false'' otherwise<br />
<br />
<br><br />
<br />
==== _console (str) ====<br />
<br />
'''Input:''' <br />
<br />
*str (string): text to be written in the console. You need to have FireBug installed in order to have a console.<br />
<br />
'''Output:''' <br />
<br />
*nothing<br />
<br />
<br><br />
<br />
==== set_panel_html (html) ====<br />
<br />
Used in the tab rendering functions. <br />
<br />
'''Input:''' <br />
<br />
*html (string): The html to be used for generating the tab content.<br />
<br />
'''Output:''' <br />
<br />
*nothing<br />
<br />
[[Category:Development]]<br />
<br />
= JavaScript API for UI7 =<br />
<br />
== Introduction ==<br />
<br />
One of the new features of UI7 is the Javascript API for writing plugins. This is a free programming interface which is robust, well documented and comes with a guarantee that it will be compatible with the following UI releases.<br />
<br />
'''''What is this “API” ?'''''<br />
<br />
Simply said: it is a layer between the UI and the plugin developer. This way, the developer can use the features available in the UI by interacting only with the API. By using the new features available in the API, the overall user experience can be visibly improved.<br />
<br />
'''''How does it work ?'''''<br />
<br />
The API comes in the form of a library which exposes to the developer the objects and methods/functions needed to implement functionality in their plugins.<br />
<br />
'''''How is this different from the previous way of writing plugins ?'''''<br />
<br />
The developers were writing Javascript code and they had full access to the core of the application. There were a couple of objects and functions written by the UI team which were easing the work for the developer.<br />
By using the new API, the developer can write code without interfering with the core of the application.<br />
<br />
'''''What is new ?'''''<br />
<br />
* The developer can write the plugin without interfering with any other code except the API. This means there are a great bundle of methods like setters and getters which help writing good code.<br />
* UI team can make any changes to the core of the application, but as long as the API stays the same, the plugins will work. This way, the application can be improved and the developer won’t have to fix the code in order for it to work. New versions of the UI can be launched and the plugins will be compatible.<br />
* Event handling - the application will notify the plugin (via the API) about the events that happen inside. Consider, for example, the addition of a new device to the unit. The developer will know, by simply listening to an event, that a device was added and so, (s)he will write the code in such a way that it will take into account the event. The user experience will be greatly improved.<br />
* Asynchronous getters and setters - because most of the actions that happen inside the UI is asynchronous, so are the API’s method written. Most of them have a signature like this: function getXXX(obj, onSuccess, onFailure), where ‘onSuccess’ and ‘onFailure’ are callback functions which are called based on the result of the call.<br />
* No more global variables to manipulate. Everything is handled through getters/setters via API.<br />
* An API reference documentation: every method and its parameters is carefully documented so that the developer would know what the function does, how to call it and what it will return.<br />
* A couple of guidelines will be given to help developers write better code in such a way that two different plugins won’t “harm” each other. The module pattern will be used as a design pattern in order to put a plugin code inside a namespace. Also, this module helps in writing code which is easier to read and use.<br />
* It will be easier for the developers to write the code by using a new feature in the UI which generates the skeleton for the plugin.<br />
<br />
'''''What is the API reference documentation ?'''''<br />
<br />
This is the part which makes the API usable. Every aspect of the API, no matter how trivial, will be stated explicitly. It contains:<br />
<br />
* a description of all the data structures it depends upon<br />
* a description of all the function signatures:<br />
** function names<br />
** function parameters (names and types)<br />
** return type of the function<br />
** if it throws any exceptions or not<br />
<br />
'''''Where is the list of functions which were replaced ?'''''<br />
<br />
In the API reference documentation the developer can find out if a function replaces an old one.<br />
<br />
'''''Why should a developer write plugins using the API when it can do some “reverse engineering” and directly access any object/functionality of the application ?'''''<br />
<br />
It is not mandatory to write the code for the plugin this way. Probably the plugin will work as long as changes are not made in the core of the application, but the API comes also with a guarantee that after application changes, the plugins will continue to work. The UI team and plugin developers have the same goal: to deliver the best experience to the user. This is where the API comes into place - an interface between the two.<br />
<br />
'''''Will the API be rewritten with each new UI release ?'''''<br />
<br />
No. It will be improved. The goal of the API is to provide a stable interface to the developer so that when changing the core of the application it won’t be necessary to rewrite the plugins.<br />
<br />
'''''Is this API going to change in the near future ?'''''<br />
<br />
It can be changed. There will be parts of it which are going to be marked as ‘deprecated’. This means that the parts will be candidates for being removed, or modified in a backward incompatible way. The developers will be advised on how are they to change their code in order to use the features which replace the deprecated parts.<br />
<br />
'''''Is the API complete ?'''''<br />
<br />
Almost. Most of the functionality is there, but developers are encouraged to request new features from the API which will be added in future releases.<br />
<br />
== Guidelines on writing Javascript code for plugins in UI7 ==<br />
<br />
* Use the module pattern to organize your code inside a namespace. Choose a well defined name for your namespace.<br />
* Generate an UUID for your plugin. This way you can use the events engine.<br />
* Use the provided API plugins to perform most of your stuff. If you can’t find an implemented method inside the API you can ASK for an implementation to it.<br />
* '''NEVER USE''' variables/functions which are not accessible through API ! They can be changed or removed at any time.<br />
* If you need to do a background job (ex: start a timer), use the events engine and register a ‘cleanup’ function in which you finish the job (clear the timer).<br />
* We encourage the use of try { … } catch { … } blocks everywhere in your functions so that errors don’t get propagated to the top of the application.<br />
* Start from the skeleton provided and expand it:<br />
<br />
<source lang="javascript"><br />
var MyPlugin = (function (api) {<br />
// example of unique identifier for this plugin...<br />
var uuid = 'B971F6C4-F315-4E2E-AD08-F029A9777517';<br />
<br />
var myModule = {};<br />
<br />
function doSomething() {<br />
// register to event ‘on_ui_cpanel_before_close’...<br />
api.registerEventHandler('on_ui_cpanel_before_close', myModule, ‘cleanUp’);<br />
// and do something... <br />
}<br />
<br />
function cleanUp() {<br />
// perform clean up...<br />
}<br />
<br />
myModule = {<br />
uuid: uuid,<br />
doSomething: doSomething,<br />
cleanUp: cleanUp<br />
};<br />
return myModule;<br />
})(api);<br />
</source><br />
<br />
Your plugin functions will be accessible via ''MyPlugin.doSomething()'' construction.<br />
When the user will leave the cpanel, your plugin will be noticed via event ''‘on_ui_cpanel_before_close’''; this way you can perform the necessary cleanup.<br />
<br />
== JavaScript API ==<br />
<br />
''Defined in'': api.js<br />
<br />
=== Class Summary ===<br />
<br />
----<br />
<br />
'''API(config, application, ui)''' <br />
<br />
- API class for plugins<br />
<br />
'''Parameters:'''<br />
<br />
* {object} config - holds configuration data<br />
* {object} application - application layer<br />
* {object} ui - interface<br />
<br />
=== Method Summary ===<br />
<br />
----<br />
<br />
==== {Object} cloneObject(obj) ====<br />
<br />
- Clones a given object<br />
<br />
- Replaces: cloneObject()<br />
<br />
'''Parameters:'''<br />
<br />
* {object} obj - object to be cloned<br />
<br />
'''Returns:'''<br />
<br />
* {Object}<br />
<br />
==== {string} getCpanelContent() ====<br />
<br />
- Retrieves cpanel content<br />
<br />
- Replaces: get_panel_html()<br />
<br />
'''Returns:'''<br />
<br />
* {string} HTML code set in cpanel<br />
<br />
==== {number} getCpanelDeviceId() ====<br />
<br />
- Returns device id for current opened cpanel or 0 if not found<br />
<br />
'''Returns:'''<br />
<br />
* {number} - device ID<br />
<br />
==== getCurrentHouseMode(onSuccess, onFailure, context) ====<br />
<br />
- Performs a data request to retrieve the current house mode<br />
<br />
'''Parameters:'''<br />
<br />
* {*} onSuccess Optional - function to be called if the call is successfull<br />
* {*} onFailure Optional - function to be called if the call fails<br />
* {object} context Optional - context in which to execute the functions of success and/or failure<br />
<br />
==== {number} getDeviceIndex(deviceId) ====<br />
<br />
- Retrieves device index for given device id<br />
<br />
- Replaces: get_device_index()<br />
<br />
'''Parameters:'''<br />
<br />
* {number} deviceId - id of the device<br />
<br />
'''Returns:'''<br />
<br />
* {number}<br />
<br />
==== {*} getDeviceObject(deviceId) ====<br />
<br />
- Retrieves device object given its id<br />
<br />
- Replaces: get_device_obj()<br />
<br />
'''Parameters:'''<br />
<br />
* {number} deviceId - id of the device<br />
<br />
'''Returns:'''<br />
<br />
* {number}<br />
<br />
===={object} getDeviceState(deviceId, service, variable, options)====<br />
<br />
- Retrieves device state for a device (it can be either read from user data or lu status, depending on the options set)<br />
<br />
'''Parameters:'''<br />
<br />
* {number} deviceId - id of the device<br />
* {string} service - name of the service<br />
* {string} variable - name of the variable<br />
* {object} options Optional - list of options like: 'dynamic': (true - lu_status will be used [default], false - user_data will be used)<br />
<br />
'''Returns:'''<br />
<br />
* {object} value for a given variable<br />
<br />
==== {Object|Boolean} getDeviceTemplate(deviceId) ====<br />
<br />
- Returns device template for a given device id<br />
<br />
'''Parameters:'''<br />
<br />
* {number} deviceId - id of the device<br />
<br />
'''Returns:'''<br />
<br />
* {Object|Boolean}<br />
<br />
==== {*} getDisplayedDeviceName(deviceId) ====<br />
<br />
- Retrieves displayed device name or 'unnamed device' if device doesn't have a name or undefined if device not found<br />
<br />
'''Parameters:'''<br />
<br />
* {number} deviceId - id of the device<br />
<br />
'''Returns:'''<br />
<br />
* {*} if device is found a string which contains the device name or 'Unnamed device' if device name is not set, or undefined if device wasn't found<br />
<br />
==== {*} getEventDefinition(deviceType) ====<br />
<br />
- Retrieves event list for a given device type<br />
<br />
- Replaces: get_event_definition() <br />
<br />
'''Parameters:'''<br />
<br />
* {string} deviceType - type of device<br />
<br />
'''Returns:'''<br />
<br />
* {*}<br />
<br />
==== {*} getListOfDevices() ====<br />
<br />
- Returns the list of devices from userdata<br />
<br />
'''Returns:'''<br />
<br />
* {*}<br />
<br />
==== getLuSdata(onSuccess, onFailure, context) ====<br />
<br />
- Performs a data request to retrieve lu_sdata<br />
<br />
'''Parameters:'''<br />
<br />
* {*} onSuccess Optional - function to be called if the call is successfull<br />
* {*} onFailure Optional - function to be called if the call fails<br />
* {object} context Optional - context in which to execute the functions of success and/or failure<br />
<br />
==== {*|Object} getRoomObject(roomId) ====<br />
<br />
- Returns room object given a room id<br />
<br />
- Replaces: get_room_by_id()<br />
<br />
'''Parameters:'''<br />
<br />
* {number} roomId - id of the room<br />
<br />
'''Returns:'''<br />
<br />
* {*|Object}<br />
<br />
==== {*} getUserData() ====<br />
<br />
- Retrieves userData or null if error<br />
<br />
- Replaces: jsonp.ud<br />
<br />
'''Returns:'''<br />
<br />
* {*} object containing userdata<br />
<br />
==== registerEventHandler(eventName, object, functionName) ====<br />
<br />
- Register an event handler.<br />
<br />
'''Parameters:'''<br />
<br />
* {string} eventName - name of the event to register to<br />
* {object} object - the object which registers to the event<br />
* {string} functionName - the name of the function to be executed if event triggers<br />
<br />
==== runUpnpCode(code, options, onSuccess, onFailure, context) ====<br />
<br />
- Runs given Upnp code<br />
<br />
'''Parameters:'''<br />
<br />
* {string} code - code to execute<br />
* {object} options Optional - optionally options to be supplied (will be documented later)<br />
* {*} onSuccess Optional - function to be called if the call is successfull<br />
* {*} onFailure Optional - function to be called if the call fails<br />
* {object} context Optional - context in which to execute the functions of success and/or failure<br />
<br />
==== setCpanelContent(html) ====<br />
<br />
- Sets content for the cpanel<br />
<br />
- Replaces: set_panel_html()<br />
<br />
'''Parameters:'''<br />
<br />
* {string} html - the new content of the cpanel<br />
<br />
==== setCurrentHouseMode(modeValue, onSuccess, onFailure, context) ====<br />
<br />
- Sets current house mode<br />
<br />
'''Parameters:'''<br />
<br />
* {number} modeValue - new value for the house mode<br />
* {*} onSuccess Optional - function to be called if the call is successfull<br />
* {*} onFailure Optional - function to be called if the call fails<br />
* {object} context Optional - context in which to execute the functions of success and/or failure<br />
<br />
==== setDeviceStateVariable(deviceId, service, variable, value, onSuccess, onFailure, context) ====<br />
<br />
- Sets state for a device variable using variableset request.<br />
<br />
- Replaces: set_device_state()<br />
<br />
'''Parameters:'''<br />
<br />
* {number} deviceId - id of the device<br />
* {string} service - name of the service<br />
* {string} variable - name of the variable<br />
* {*} value - new value for the variable<br />
* {*} onSuccess Optional - function to be called if the call is successfull<br />
* {*} onFailure Optional - function to be called if the call fails<br />
* {object} context Optional - context in which to execute the functions of success and/or failure</div>Andreimioshttp://wiki.mios.com/index.php/JavaScript_APIJavaScript API2014-10-06T08:41:41Z<p>Andreimios: </p>
<hr />
<div>== Usage ==<br />
<pre>"Tabs": [<br />
{<br />
"Label": {<br />
"lang_tag": "users",<br />
"text": "Users" <br />
},<br />
"Position": "0",<br />
"TabType": "javascript",<br />
"ScriptName": "I_HomeCare.js",<br />
"Function": "showUsers"<br />
}, </pre> <br />
To generate a tab using your JavaScript functions you need to specify this by setting ''TabType'' to '''''javascript'''''. Then, you need to specify the script file's name and which function in this file will be used to draw the tab's content. That function will have one argument, which is the device number.<br> <br />
<br />
==== &lt;functionName&gt; (deviceNumber) ====<br />
<br />
This is the tab rendering function. The [[#set_panel_html_.28html.29 | set_panel_html]] function must be called at the end.<br> <br />
<br />
'''Input:''' <br />
<br />
*deviceNumber (number)<br><br />
<br />
'''Output:''' <br />
<br />
*nothing<br />
<br />
<br><br />
<br />
== Variables ==<br />
<br />
==== jsonp.ud ====<br />
<br />
This is the user data. <br />
<br />
*'''Type''': object <br />
*'''Members''': <br />
**devices (array) <br />
**scenes (array) <br />
**users (array) <br />
**rooms (array) <br />
**eventList (array) <br />
**etc.<br />
<br />
<br> <br />
<br />
==== jsonp.ud.devices ====<br />
<br />
*'''Type''': array <br />
*'''Members''': <br />
**id (number) <br />
**device_type (string) <br />
**room (number) <br />
**name (string) <br />
**category_num (number) <br />
**etc.<br />
<br />
<br> <br />
<br />
==== jsonp.ud.scenes ====<br />
<br />
*'''Type''': array <br />
*'''Members''': <br />
**id (number) <br />
**name (string) <br />
**room (number) <br />
**Timer_ids (array) <br />
**Timer (object) <br />
**etc.<br />
<br />
<br> <br />
<br />
== Functions ==<br />
<br />
==== get_device_state (deviceId, serviceId, variable, dynamic) ====<br />
<br />
'''Input:''' <br />
<br />
*deviceId (number)<br />
*serviceId (string)<br />
*variable (string)<br />
*dynamic (number): if '''1''', the variable's value is taken from ''lu_status'', else, the variable's value is taken from ''user_data''. ''user_data'' is read at Luup startup, so for variables that change their value frequently (like Watts, Temperature, etc.) ''dynamic'' should be '''1'''.<br />
<br />
'''Output:''' <br />
<br />
*variable value (string or ''undefined'')<br />
<br />
<br><br />
<br />
==== set_device_state (deviceId, serviceId, variable, value, dynamic) ====<br />
<br />
'''Input:''' <br />
<br />
*deviceId (number)<br />
*serviceId (string)<br />
*variable (string)<br />
*value (string)<br />
*dynamic (number): if '''1''', the variable's value is saved to ''lu_status'' (the value is lost after Luup is restarted), else, the variable's value is saved to a copy of ''user_data''; the real user_data is updated when LuaUPnP is restarted.<br />
<br />
'''Output:''' <br />
<br />
*''true'' if the operation succeeded, ''false'' otherwise<br />
<br />
<br><br />
<br />
==== _console (str) ====<br />
<br />
'''Input:''' <br />
<br />
*str (string): text to be written in the console. You need to have FireBug installed in order to have a console.<br />
<br />
'''Output:''' <br />
<br />
*nothing<br />
<br />
<br><br />
<br />
==== set_panel_html (html) ====<br />
<br />
Used in the tab rendering functions. <br />
<br />
'''Input:''' <br />
<br />
*html (string): The html to be used for generating the tab content.<br />
<br />
'''Output:''' <br />
<br />
*nothing<br />
<br />
[[Category:Development]]<br />
<br />
= JavaScript API for UI7 =<br />
<br />
== Introduction ==<br />
<br />
One of the new features of UI7 is the Javascript API for writing plugins. This is a free programming interface which is robust, well documented and comes with a guarantee that it will be compatible with the following UI releases.<br />
<br />
'''''What is this “API” ?'''''<br />
<br />
Simply said: it is a layer between the UI and the plugin developer. This way, the developer can use the features available in the UI by interacting only with the API. By using the new features available in the API, the overall user experience can be visibly improved.<br />
<br />
'''''How does it work ?'''''<br />
<br />
The API comes in the form of a library which exposes to the developer the objects and methods/functions needed to implement functionality in their plugins.<br />
<br />
'''''How is this different from the previous way of writing plugins ?'''''<br />
<br />
The developers were writing Javascript code and they had full access to the core of the application. There were a couple of objects and functions written by the UI team which were easing the work for the developer.<br />
By using the new API, the developer can write code without interfering with the core of the application.<br />
<br />
'''''What is new ?'''''<br />
<br />
* The developer can write the plugin without interfering with any other code except the API. This means there are a great bundle of methods like setters and getters which help writing good code.<br />
* UI team can make any changes to the core of the application, but as long as the API stays the same, the plugins will work. This way, the application can be improved and the developer won’t have to fix the code in order for it to work. New versions of the UI can be launched and the plugins will be compatible.<br />
* Event handling - the application will notify the plugin (via the API) about the events that happen inside. Consider, for example, the addition of a new device to the unit. The developer will know, by simply listening to an event, that a device was added and so, (s)he will write the code in such a way that it will take into account the event. The user experience will be greatly improved.<br />
* Asynchronous getters and setters - because most of the actions that happen inside the UI is asynchronous, so are the API’s method written. Most of them have a signature like this: function getXXX(obj, onSuccess, onFailure), where ‘onSuccess’ and ‘onFailure’ are callback functions which are called based on the result of the call.<br />
* No more global variables to manipulate. Everything is handled through getters/setters via API.<br />
* An API reference documentation: every method and its parameters is carefully documented so that the developer would know what the function does, how to call it and what it will return.<br />
* A couple of guidelines will be given to help developers write better code in such a way that two different plugins won’t “harm” each other. The module pattern will be used as a design pattern in order to put a plugin code inside a namespace. Also, this module helps in writing code which is easier to read and use.<br />
* It will be easier for the developers to write the code by using a new feature in the UI which generates the skeleton for the plugin.<br />
<br />
'''''What is the API reference documentation ?'''''<br />
<br />
This is the part which makes the API usable. Every aspect of the API, no matter how trivial, will be stated explicitly. It contains:<br />
<br />
* a description of all the data structures it depends upon<br />
* a description of all the function signatures:<br />
** function names<br />
** function parameters (names and types)<br />
** return type of the function<br />
** if it throws any exceptions or not<br />
<br />
'''''Where is the list of functions which were replaced ?'''''<br />
<br />
In the API reference documentation the developer can find out if a function replaces an old one.<br />
<br />
'''''Why should a developer write plugins using the API when it can do some “reverse engineering” and directly access any object/functionality of the application ?'''''<br />
<br />
It is not mandatory to write the code for the plugin this way. Probably the plugin will work as long as changes are not made in the core of the application, but the API comes also with a guarantee that after application changes, the plugins will continue to work. The UI team and plugin developers have the same goal: to deliver the best experience to the user. This is where the API comes into place - an interface between the two.<br />
<br />
'''''Will the API be rewritten with each new UI release ?'''''<br />
<br />
No. It will be improved. The goal of the API is to provide a stable interface to the developer so that when changing the core of the application it won’t be necessary to rewrite the plugins.<br />
<br />
'''''Is this API going to change in the near future ?'''''<br />
<br />
It can be changed. There will be parts of it which are going to be marked as ‘deprecated’. This means that the parts will be candidates for being removed, or modified in a backward incompatible way. The developers will be advised on how are they to change their code in order to use the features which replace the deprecated parts.<br />
<br />
'''''Is the API complete ?'''''<br />
<br />
Almost. Most of the functionality is there, but developers are encouraged to request new features from the API which will be added in future releases.<br />
<br />
== Guidelines on writing Javascript code for plugins in UI7 ==<br />
<br />
* Use the module pattern to organize your code inside a namespace. Choose a well defined name for your namespace.<br />
* Generate an UUID for your plugin. This way you can use the events engine.<br />
* Use the provided API plugins to perform most of your stuff. If you can’t find an implemented method inside the API you can ASK for an implementation to it.<br />
* '''NEVER USE''' variables/functions which are not accessible through API ! They can be changed or removed at any time.<br />
* If you need to do a background job (ex: start a timer), use the events engine and register a ‘cleanup’ function in which you finish the job (clear the timer).<br />
* We encourage the use of try { … } catch { … } blocks everywhere in your functions so that errors don’t get propagated to the top of the application.<br />
* Start from the skeleton provided and expand it:<br />
<br />
<source lang="javascript"><br />
var MyPlugin = (function (api) {<br />
// example of unique identifier for this plugin...<br />
var uuid = 'B971F6C4-F315-4E2E-AD08-F029A9777517';<br />
<br />
var myModule = {};<br />
<br />
function doSomething() {<br />
// register to event ‘on_ui_cpanel_before_close’...<br />
api.registerEventHandler('on_ui_cpanel_before_close', myModule, ‘cleanUp’);<br />
// and do something... <br />
}<br />
<br />
function cleanUp() {<br />
// perform clean up...<br />
}<br />
<br />
myModule = {<br />
uuid: uuid,<br />
doSomething: doSomething,<br />
cleanUp: cleanUp<br />
};<br />
return myModule;<br />
})(api);<br />
</source><br />
<br />
Your plugin functions will be accessible via ''MyPlugin.doSomething()'' construction.<br />
When the user will leave the cpanel, your plugin will be noticed via event ''‘on_ui_cpanel_before_close’''; this way you can perform the necessary cleanup.<br />
<br />
== JavaScript API ==<br />
<br />
''Defined in'': api.js<br />
<br />
=== Class Summary ===<br />
<br />
----<br />
<br />
'''API(config, application, ui)''' <br />
<br />
- API class for plugins<br />
<br />
'''Parameters:'''<br />
<br />
* {object} config - holds configuration data<br />
* {object} application - application layer<br />
* {object} ui - interface<br />
<br />
=== Method Summary ===<br />
<br />
----<br />
<br />
==== {Object} cloneObject(obj) ====<br />
<br />
- Clones a given object<br />
<br />
- Replaces: cloneObject()<br />
<br />
'''Parameters:'''<br />
<br />
* {object} obj - object to be cloned<br />
<br />
'''Returns:'''<br />
<br />
* {Object}<br />
<br />
==== {string} getCpanelContent() ====<br />
<br />
- Retrieves cpanel content<br />
<br />
- Replaces: get_panel_html()<br />
<br />
'''Returns:'''<br />
<br />
* {string} HTML code set in cpanel<br />
<br />
==== {number} getCpanelDeviceId() ====<br />
<br />
- Returns device id for current opened cpanel or 0 if not found<br />
<br />
'''Returns:'''<br />
<br />
* {number} - device ID<br />
<br />
==== getCurrentHouseMode(onSuccess, onFailure, context) ====<br />
<br />
- Performs a data request to retrieve the current house mode<br />
<br />
'''Parameters:'''<br />
<br />
* {*} onSuccess Optional - function to be called if the call is successfull<br />
* {*} onFailure Optional - function to be called if the call fails<br />
* {object} context Optional - context in which to execute the functions of success and/or failure<br />
<br />
==== {number} getDeviceIndex(deviceId) ====<br />
<br />
- Retrieves device index for given device id<br />
<br />
- Replaces: get_device_index()<br />
<br />
'''Parameters:'''<br />
<br />
* {number} deviceId - id of the device<br />
<br />
'''Returns:'''<br />
<br />
* {number}<br />
<br />
==== {*} getDeviceObject(deviceId) ====<br />
<br />
- Retrieves device object given its id<br />
<br />
- Replaces: get_device_obj()<br />
<br />
'''Parameters:'''<br />
<br />
* {number} deviceId - id of the device<br />
<br />
'''Returns:'''<br />
<br />
* {number}<br />
<br />
===={object} getDeviceState(deviceId, service, variable, options)====<br />
<br />
- Retrieves device state for a device (it can be either read from user data or lu status, depending on the options set)<br />
<br />
'''Parameters:'''<br />
<br />
* {number} deviceId - id of the device<br />
* {string} service - name of the service<br />
* {string} variable - name of the variable<br />
* {object} options Optional - list of options like: 'dynamic': (true - lu_status will be used [default], false - user_data will be used)<br />
<br />
'''Returns:'''<br />
<br />
* {object} value for a given variable<br />
<br />
==== {Object|Boolean} getDeviceTemplate(deviceId) ====<br />
<br />
- Returns device template for a given device id<br />
<br />
'''Parameters:'''<br />
<br />
* {number} deviceId - id of the device<br />
<br />
'''Returns:'''<br />
<br />
* {Object|Boolean}<br />
<br />
==== {*} getDisplayedDeviceName(deviceId) ====<br />
<br />
- Retrieves displayed device name or 'unnamed device' if device doesn't have a name or undefined if device not found<br />
<br />
'''Parameters:'''<br />
<br />
* {number} deviceId - id of the device<br />
<br />
'''Returns:'''<br />
<br />
* {*} if device is found a string which contains the device name or 'Unnamed device' if device name is not set, or undefined if device wasn't found<br />
<br />
==== {*} getEventDefinition(deviceType) ====<br />
<br />
- Retrieves event list for a given device type<br />
<br />
- Replaces: get_event_definition() <br />
<br />
'''Parameters:'''<br />
<br />
* {string} deviceType - type of device<br />
<br />
'''Returns:'''<br />
<br />
* {*}<br />
<br />
==== {*} getListOfDevices() ====<br />
<br />
- Returns the list of devices from userdata<br />
<br />
'''Returns:'''<br />
<br />
* {*}<br />
<br />
==== getLuSdata(onSuccess, onFailure, context) ====<br />
<br />
- Performs a data request to retrieve lu_sdata<br />
<br />
'''Parameters:'''<br />
<br />
* {*} onSuccess Optional - function to be called if the call is successfull<br />
* {*} onFailure Optional - function to be called if the call fails<br />
* {object} context Optional - context in which to execute the functions of success and/or failure<br />
<br />
==== {*|Object} getRoomObject(roomId) ====<br />
<br />
- Returns room object given a room id<br />
<br />
- Replaces: get_room_by_id()<br />
<br />
'''Parameters:'''<br />
<br />
* {number} roomId - id of the room<br />
<br />
'''Returns:'''<br />
<br />
* {*|Object}<br />
<br />
==== {*} getUserData() ====<br />
<br />
- Retrieves userData or null if error<br />
<br />
- Replaces: jsonp.ud<br />
<br />
'''Returns:'''<br />
<br />
* {*} object containing userdata<br />
<br />
==== registerEventHandler(eventName, object, functionName) ====<br />
<br />
- Register an event handler.<br />
<br />
'''Parameters:'''<br />
<br />
* {string} eventName - name of the event to register to<br />
* {object} object - the object which registers to the event<br />
* {string} functionName - the name of the function to be executed if event triggers<br />
<br />
==== runUpnpCode(code, options, onSuccess, onFailure, context) ====<br />
<br />
- Runs given Upnp code<br />
<br />
'''Parameters:'''<br />
<br />
* {string} code - code to execute<br />
* {object} options Optional - optionally options to be supplied (will be documented later)<br />
* {*} onSuccess Optional - function to be called if the call is successfull<br />
* {*} onFailure Optional - function to be called if the call fails<br />
* {object} context Optional - context in which to execute the functions of success and/or failure<br />
<br />
==== setCpanelContent(html) ====<br />
<br />
- Sets content for the cpanel<br />
<br />
- Replaces: set_panel_html()<br />
<br />
'''Parameters:'''<br />
<br />
* {string} html - the new content of the cpanel<br />
<br />
==== setCurrentHouseMode(modeValue, onSuccess, onFailure, context) ====<br />
<br />
- Sets current house mode<br />
<br />
'''Parameters:'''<br />
<br />
* {number} modeValue - new value for the house mode<br />
* {*} onSuccess Optional - function to be called if the call is successfull<br />
* {*} onFailure Optional - function to be called if the call fails<br />
* {object} context Optional - context in which to execute the functions of success and/or failure<br />
<br />
==== setDeviceStateVariable(deviceId, service, variable, value, onSuccess, onFailure, context) ====<br />
<br />
- Sets state for a device variable using variableset request.<br />
<br />
- Replaces: set_device_state()<br />
<br />
'''Parameters:'''<br />
<br />
* {number} deviceId - id of the device<br />
* {string} service - name of the service<br />
* {string} variable - name of the variable<br />
* {*} value - new value for the variable<br />
* {*} onSuccess Optional - function to be called if the call is successfull<br />
* {*} onFailure Optional - function to be called if the call fails<br />
* {object} context Optional - context in which to execute the functions of success and/or failure<br />
<br />
=== Events ===<br />
<br />
The list of available events can be obtained with the following command:<br />
<br />
'''api.getListOfSupportedEvents()'''</div>Andreimioshttp://wiki.mios.com/index.php/AlertsAlerts2014-10-02T14:13:31Z<p>Andreimios: </p>
<hr />
<div>== Introduction ==<br />
<br />
3rd party developers can now use the alert system in plugins. They can generate different alert types with or without user notification. Alert messages generated by a device can be seen in '''"Logs"''' tab for that device.<br />
<br />
[[File:logs_button.png|image|none|caption]]<br />
<br />
Let's take as example the HomeCare plugin. Users should be notify when a sensor has not been tripped for a specified amount of time. Here is how "Alerts" page for HomeCare plugin looks like:<br />
<br />
[[File:homecare_notification.png|image|none|caption]]<br />
<br />
<br />
As you can see the '''source''' of this notification is our HomeCare plugin, '''type''' for it is "user created trigger" and '''desctiption''' is the one we added in plugin.<br />
<br />
And here is the detailed message for this notification:<br />
<br />
[[File:homecare_notification_alert.png|image|none|caption]]<br />
<br />
== Alert HTTP Request ==<br />
<br />
http://IP:3480/data_request?id=add_alert&device=DEVICE_ID&type=3&source=3&description=ALERT_DESCRIPTION&users=USERS_LIST<br />
<br />
* DEVICE_ID - device # that generates the alert;<br />
* ALERT_TYPE - should be 3, DO NOT CHANGE;<br />
* ALERT_SOURCE - should be 3, DO NOT CHANGE;<br />
* ALERT_DESCRIPTION - URL encoded message used as description for the alert;<br />
* USERS_LIST - a list with user ID separated by commas that should be notify[left blank if no user notification is required].</div>Andreimioshttp://wiki.mios.com/index.php/AlertsAlerts2014-10-02T14:10:22Z<p>Andreimios: </p>
<hr />
<div>== Introduction ==<br />
<br />
3rd party developers can now use the alert system in plugins. They can generate different alert types with or without user notification. Alert messages generated by a device can be seen in '''"Logs"''' tab for that device.<br />
<br />
[[File:logs_button.png|image|none|caption]]<br />
<br />
Let's take as example the HomeCare plugin. Users should be notify when a sensor has not been tripped for a specified amount of time. Here is how "Alerts" page for HomeCare plugin looks like:<br />
<br />
[[File:homecare_notification.png|image|none|caption]]<br />
<br />
<br />
As you can see the '''source''' of this notification is our HomeCare plugin, '''type''' for it is "user created trigger" and '''desctiption''' is the one we added in plugin.<br />
<br />
And here is the detailed message for this notification:<br />
<br />
[[File:homecare_notification_alert.png|image|none|caption]]<br />
<br />
== Alert HTTP Request ==<br />
<br />
http://IP:3480/data_request?id=add_alert&device=DEVICE_ID&type=3&source=3&description=ALERT_DESCRIPTION&users=USERS_LIST<br />
<br />
* DEVICE_ID - device # that generates the alert;<br />
* ALERT_TYPE - "user created trigger" alert;<br />
* ALERT_SOURCE - trigger event type message in detailed description;<br />
* ALERT_DESCRIPTION - URL encoded message used as description for the alert;<br />
* USERS_LIST - a list with user ID separated by commas that should be notify[left blank if no user notification is required].</div>Andreimioshttp://wiki.mios.com/index.php/AlertsAlerts2014-10-02T13:44:30Z<p>Andreimios: </p>
<hr />
<div>== Introduction ==<br />
<br />
3rd party developers can now use the alert system in plugins. They can generate different alert types with or without user notification. Alert messages generated by a device can be seen in '''"Logs"''' tab for that device.<br />
<br />
[[File:logs_button.png|image|none|caption]]<br />
<br />
Let's take as example the HomeCare plugin. Users should be notify when a sensor has not been tripped for a specified amount of time. Here is how "Alerts" page for HomeCare plugin looks like:<br />
<br />
[[File:homecare_notification.png|image|none|caption]]<br />
<br />
As you can see the '''source''' of this notification is our HomeCare plugin, '''type''' for it is "user created trigger" and '''desctiption''' is the one we added in plugin.<br />
<br />
And here is the detailed message for this notification:<br />
<br />
[[File:homecare_notification_alert.png|image|none|caption]]<br />
<br />
== Alert Request ==</div>Andreimioshttp://wiki.mios.com/index.php/AlertsAlerts2014-10-02T13:37:17Z<p>Andreimios: Created page with "= Introduction = 3rd party developers can now use the alert system in plugins. They can generate different alert types with or without user notification. Alert messages gener..."</p>
<hr />
<div>= Introduction =<br />
<br />
3rd party developers can now use the alert system in plugins. They can generate different alert types with or without user notification. Alert messages generated by a device can be seen in '''"Logs"''' tab for that device.<br />
<br />
[[File:logs_button.png|image|none|caption]]<br />
<br />
Let's take as example the HomeCare plugin. Users should be notify when a sensor has not been tripped for a specified amount of time. Here is how "Alerts" page for HomeCare plugin looks like:<br />
<br />
[[File:homecare_notification.png|image|none|caption]]<br />
<br />
And here is the notification message:<br />
<br />
[[File:homecare_notification_alert.png|image|none|caption]]</div>Andreimioshttp://wiki.mios.com/index.php/File:Homecare_notification_alert.pngFile:Homecare notification alert.png2014-10-02T13:36:45Z<p>Andreimios: </p>
<hr />
<div></div>Andreimioshttp://wiki.mios.com/index.php/File:Homecare_notification.pngFile:Homecare notification.png2014-10-02T13:34:01Z<p>Andreimios: </p>
<hr />
<div></div>Andreimioshttp://wiki.mios.com/index.php/File:Logs_button.pngFile:Logs button.png2014-10-02T13:31:30Z<p>Andreimios: </p>
<hr />
<div></div>Andreimioshttp://wiki.mios.com/index.php/Extra_Submenu_ItemsExtra Submenu Items2014-10-01T10:22:33Z<p>Andreimios: </p>
<hr />
<div>== Inrodution ==<br />
A number of extra submenu items can be created for each device type by using the definition supplied in plugin .json file.<br />
<br />
These items will be created under ‘Apps’ menu item.<br />
<br />
They can be used to execute user defined functions which display content on the right part of the Web interface (the same way the other submenu items do).<br />
<br />
== How To ==<br />
<br />
==== In your plugin .json file, insert the following construction after ‘eventList2’: ====<br />
<br />
<source lang="javascript"><br />
<br />
"submenuItems": [<br />
{<br />
"id": "1",<br />
"Label": {<br />
"lang_tag": "my_plugin_first_submenu",<br />
"text": "My first submenu"<br />
},<br />
"ScriptName": "my_plugin.js",<br />
"Function": "MY_PLUGIN.first_submenu",<br />
"Parameters": {<br />
"name": "John Doe",<br />
"age": "84"<br />
}<br />
},<br />
{<br />
"id": "2",<br />
"Label": {<br />
"lang_tag": "my_plugin_second_submenu",<br />
"text": "My second submenu"<br />
},<br />
"Invisible": "1",<br />
"ScriptName": "my_plugin.js",<br />
"Function": "MY_PLUGIN.second_submenu",<br />
"Parameters": {}<br />
}<br />
]<br />
<br />
</source><br />
<br />
This construction defines two submenu items. <br />
<br />
* '''id''': integer, must be unique<br />
* '''Label''': a JSON object containing two keys:<br />
** '''lang_tag''': string used by localized UIs<br />
** '''text''': string which represents the text that is going to be displayed if localization fails<br />
* '''Function''': string specifying the function to be called when clicking on this submenu item<br />
* '''Parameters''': a JSON object containing the parameters which are to be called with the function<br />
* '''ScriptName''': string specifying the .js file which must be loaded in order to find the function<br />
* '''Invisible''': (optional) - integer, if set to 1, the submenu item will be hidden and can be programmatically displayed<br />
<br />
==== Create or edit your ‘my_plugin.js’ file and add the following lines: ====<br />
<br />
<source lang="javascript"><br />
var MY_PLUGIN = (function() {<br />
return {<br />
first_submenu: function(obj) {<br />
try {<br />
// get the parent element...<br />
var $parent = $('#' + View.containerForExtraSubmenuItem());<br />
<br />
// create a new DOM element...<br />
var $c = $('<p></p>');<br />
$c.html('I am '+obj['name']+' ! Give me $' +obj['ammount']+ ' !');<br />
<br />
// and append it to the parent...<br />
$c.appendTo($parent);<br />
} catch (e) {<br />
Utils.logError('Error in first_submenu(): ' + e);<br />
}<br />
}<br />
};<br />
})();<br />
</source><br />
<br />
'''Code explained''': it is executed after clicking on the submenu item defined. It creates a DOM element which displays a message. That DOM element is appended to a container where all DOM manipulation from the plugin will reside.<br />
<br />
==== After the plugin is installed and a LU Reload is performed, click on ‘Apps’ -> ‘My first submenu’ and the page will look something like this: ====<br />
<br />
[[File:submenu.jpg|image|none|caption]]<br />
<br />
<br />
The function supplied was executed and the content is displayed on the right side of the page.<br />
<br />
Note the absence of ‘My second submenu’ from the list (because was marked with property ‘Invisible’).</div>Andreimioshttp://wiki.mios.com/index.php/Extra_Submenu_ItemsExtra Submenu Items2014-10-01T10:19:28Z<p>Andreimios: Created page with "== Inrodution == A number of extra submenu items can be created for each device type by using the definition supplied in plugin .json file. These items will be created under ..."</p>
<hr />
<div>== Inrodution ==<br />
A number of extra submenu items can be created for each device type by using the definition supplied in plugin .json file.<br />
<br />
These items will be created under ‘Apps’ menu item.<br />
<br />
They can be used to execute user defined functions which display content on the right part of the Web interface (the same way the other submenu items do).<br />
<br />
== How To ==<br />
<br />
==== In your plugin .json file, insert the following construction after ‘eventList2’: ====<br />
<br />
<source lang="javascript"><br />
<br />
"submenuItems": [<br />
{<br />
"id": "1",<br />
"Label": {<br />
"lang_tag": "my_plugin_first_submenu",<br />
"text": "My first submenu"<br />
},<br />
"ScriptName": "my_plugin.js",<br />
"Function": "MY_PLUGIN.first_submenu",<br />
"Parameters": {<br />
"name": "John Doe",<br />
"age": "84"<br />
}<br />
},<br />
{<br />
"id": "2",<br />
"Label": {<br />
"lang_tag": "my_plugin_second_submenu",<br />
"text": "My second submenu"<br />
},<br />
"Invisible": "1",<br />
"ScriptName": "my_plugin.js",<br />
"Function": "MY_PLUGIN.second_submenu",<br />
"Parameters": {}<br />
}<br />
]<br />
<br />
</source><br />
<br />
This construction defines two submenu items. <br />
<br />
* id: integer, must be unique<br />
* Label: a JSON object containing two keys:<br />
** lang_tag: string used by localized UIs<br />
** text: string which represents the text that is going to be displayed if localization fails<br />
* Function: string specifying the function to be called when clicking on this submenu item<br />
* Parameters: a JSON object containing the parameters which are to be called with the function<br />
* ScriptName: string specifying the .js file which must be loaded in order to find the function<br />
* Invisible: (optional) - integer, if set to 1, the submenu item will be hidden and can be programmatically displayed<br />
<br />
==== Create or edit your ‘my_plugin.js’ file and add the following lines: ====<br />
<br />
<source lang="javascript"><br />
var MY_PLUGIN = (function() {<br />
return {<br />
first_submenu: function(obj) {<br />
try {<br />
// get the parent element...<br />
var $parent = $('#' + View.containerForExtraSubmenuItem());<br />
<br />
// create a new DOM element...<br />
var $c = $('<p></p>');<br />
$c.html('I am '+obj['name']+' ! Give me $' +obj['ammount']+ ' !');<br />
<br />
// and append it to the parent...<br />
$c.appendTo($parent);<br />
} catch (e) {<br />
Utils.logError('Error in first_submenu(): ' + e);<br />
}<br />
}<br />
};<br />
})();<br />
</source><br />
<br />
'''Code explained''': it is executed after clicking on the submenu item defined. It creates a DOM element which displays a message. That DOM element is appended to a container where all DOM manipulation from the plugin will reside.<br />
<br />
==== After the plugin is installed and a LU Reload is performed, click on ‘Apps’ -> ‘My first submenu’ and the page will look something like this: ====<br />
<br />
[[File:submenu.jpg|image|none|caption]]<br />
<br />
<br />
The function supplied was executed and the content is displayed on the right side of the page.<br />
<br />
Note the absence of ‘My second submenu’ from the list (because was marked with property ‘Invisible’).</div>Andreimioshttp://wiki.mios.com/index.php/File:Submenu.jpgFile:Submenu.jpg2014-10-01T10:15:04Z<p>Andreimios: </p>
<hr />
<div></div>Andreimioshttp://wiki.mios.com/index.php/JavaScript_APIJavaScript API2014-10-01T08:51:13Z<p>Andreimios: </p>
<hr />
<div>== Usage ==<br />
<pre>"Tabs": [<br />
{<br />
"Label": {<br />
"lang_tag": "users",<br />
"text": "Users" <br />
},<br />
"Position": "0",<br />
"TabType": "javascript",<br />
"ScriptName": "I_HomeCare.js",<br />
"Function": "showUsers"<br />
}, </pre> <br />
To generate a tab using your JavaScript functions you need to specify this by setting ''TabType'' to '''''javascript'''''. Then, you need to specify the script file's name and which function in this file will be used to draw the tab's content. That function will have one argument, which is the device number.<br> <br />
<br />
==== &lt;functionName&gt; (deviceNumber) ====<br />
<br />
This is the tab rendering function. The [[#set_panel_html_.28html.29 | set_panel_html]] function must be called at the end.<br> <br />
<br />
'''Input:''' <br />
<br />
*deviceNumber (number)<br><br />
<br />
'''Output:''' <br />
<br />
*nothing<br />
<br />
<br><br />
<br />
== Variables ==<br />
<br />
==== jsonp.ud ====<br />
<br />
This is the user data. <br />
<br />
*'''Type''': object <br />
*'''Members''': <br />
**devices (array) <br />
**scenes (array) <br />
**users (array) <br />
**rooms (array) <br />
**eventList (array) <br />
**etc.<br />
<br />
<br> <br />
<br />
==== jsonp.ud.devices ====<br />
<br />
*'''Type''': array <br />
*'''Members''': <br />
**id (number) <br />
**device_type (string) <br />
**room (number) <br />
**name (string) <br />
**category_num (number) <br />
**etc.<br />
<br />
<br> <br />
<br />
==== jsonp.ud.scenes ====<br />
<br />
*'''Type''': array <br />
*'''Members''': <br />
**id (number) <br />
**name (string) <br />
**room (number) <br />
**Timer_ids (array) <br />
**Timer (object) <br />
**etc.<br />
<br />
<br> <br />
<br />
== Functions ==<br />
<br />
==== get_device_state (deviceId, serviceId, variable, dynamic) ====<br />
<br />
'''Input:''' <br />
<br />
*deviceId (number)<br />
*serviceId (string)<br />
*variable (string)<br />
*dynamic (number): if '''1''', the variable's value is taken from ''lu_status'', else, the variable's value is taken from ''user_data''. ''user_data'' is read at Luup startup, so for variables that change their value frequently (like Watts, Temperature, etc.) ''dynamic'' should be '''1'''.<br />
<br />
'''Output:''' <br />
<br />
*variable value (string or ''undefined'')<br />
<br />
<br><br />
<br />
==== set_device_state (deviceId, serviceId, variable, value, dynamic) ====<br />
<br />
'''Input:''' <br />
<br />
*deviceId (number)<br />
*serviceId (string)<br />
*variable (string)<br />
*value (string)<br />
*dynamic (number): if '''1''', the variable's value is saved to ''lu_status'' (the value is lost after Luup is restarted), else, the variable's value is saved to a copy of ''user_data''; the real user_data is updated when LuaUPnP is restarted.<br />
<br />
'''Output:''' <br />
<br />
*''true'' if the operation succeeded, ''false'' otherwise<br />
<br />
<br><br />
<br />
==== _console (str) ====<br />
<br />
'''Input:''' <br />
<br />
*str (string): text to be written in the console. You need to have FireBug installed in order to have a console.<br />
<br />
'''Output:''' <br />
<br />
*nothing<br />
<br />
<br><br />
<br />
==== set_panel_html (html) ====<br />
<br />
Used in the tab rendering functions. <br />
<br />
'''Input:''' <br />
<br />
*html (string): The html to be used for generating the tab content.<br />
<br />
'''Output:''' <br />
<br />
*nothing<br />
<br />
[[Category:Development]]<br />
<br />
= JavaScript API for UI7 =<br />
<br />
== Introduction ==<br />
<br />
One of the new features of UI7 is the Javascript API for writing plugins. This is a free programming interface which is robust, well documented and comes with a guarantee that it will be compatible with the following UI releases.<br />
<br />
'''''What is this “API” ?'''''<br />
<br />
Simply said: it is a layer between the UI and the plugin developer. This way, the developer can use the features available in the UI by interacting only with the API. By using the new features available in the API, the overall user experience can be visibly improved.<br />
<br />
'''''How does it work ?'''''<br />
<br />
The API comes in the form of a library which exposes to the developer the objects and methods/functions needed to implement functionality in their plugins.<br />
<br />
'''''How is this different from the previous way of writing plugins ?'''''<br />
<br />
The developers were writing Javascript code and they had full access to the core of the application. There were a couple of objects and functions written by the UI team which were easing the work for the developer.<br />
By using the new API, the developer can write code without interfering with the core of the application.<br />
<br />
'''''What is new ?'''''<br />
<br />
* The developer can write the plugin without interfering with any other code except the API. This means there are a great bundle of methods like setters and getters which help writing good code.<br />
* UI team can make any changes to the core of the application, but as long as the API stays the same, the plugins will work. This way, the application can be improved and the developer won’t have to fix the code in order for it to work. New versions of the UI can be launched and the plugins will be compatible.<br />
* Event handling - the application will notify the plugin (via the API) about the events that happen inside. Consider, for example, the addition of a new device to the unit. The developer will know, by simply listening to an event, that a device was added and so, (s)he will write the code in such a way that it will take into account the event. The user experience will be greatly improved.<br />
* Asynchronous getters and setters - because most of the actions that happen inside the UI is asynchronous, so are the API’s method written. Most of them have a signature like this: function getXXX(obj, onSuccess, onFailure), where ‘onSuccess’ and ‘onFailure’ are callback functions which are called based on the result of the call.<br />
* No more global variables to manipulate. Everything is handled through getters/setters via API.<br />
* An API reference documentation: every method and its parameters is carefully documented so that the developer would know what the function does, how to call it and what it will return.<br />
* A couple of guidelines will be given to help developers write better code in such a way that two different plugins won’t “harm” each other. The module pattern will be used as a design pattern in order to put a plugin code inside a namespace. Also, this module helps in writing code which is easier to read and use.<br />
* It will be easier for the developers to write the code by using a new feature in the UI which generates the skeleton for the plugin.<br />
<br />
'''''What is the API reference documentation ?'''''<br />
<br />
This is the part which makes the API usable. Every aspect of the API, no matter how trivial, will be stated explicitly. It contains:<br />
<br />
* a description of all the data structures it depends upon<br />
* a description of all the function signatures:<br />
** function names<br />
** function parameters (names and types)<br />
** return type of the function<br />
** if it throws any exceptions or not<br />
<br />
'''''Where is the list of functions which were replaced ?'''''<br />
<br />
In the API reference documentation the developer can find out if a function replaces an old one.<br />
<br />
'''''Why should a developer write plugins using the API when it can do some “reverse engineering” and directly access any object/functionality of the application ?'''''<br />
<br />
It is not mandatory to write the code for the plugin this way. Probably the plugin will work as long as changes are not made in the core of the application, but the API comes also with a guarantee that after application changes, the plugins will continue to work. The UI team and plugin developers have the same goal: to deliver the best experience to the user. This is where the API comes into place - an interface between the two.<br />
<br />
'''''Will the API be rewritten with each new UI release ?'''''<br />
<br />
No. It will be improved. The goal of the API is to provide a stable interface to the developer so that when changing the core of the application it won’t be necessary to rewrite the plugins.<br />
<br />
'''''Is this API going to change in the near future ?'''''<br />
<br />
It can be changed. There will be parts of it which are going to be marked as ‘deprecated’. This means that the parts will be candidates for being removed, or modified in a backward incompatible way. The developers will be advised on how are they to change their code in order to use the features which replace the deprecated parts.<br />
<br />
'''''Is the API complete ?'''''<br />
<br />
Almost. Most of the functionality is there, but developers are encouraged to request new features from the API which will be added in future releases.<br />
<br />
== Guidelines on writing Javascript code for plugins in UI7 ==<br />
<br />
* Use the module pattern to organize your code inside a namespace. Choose a well defined name for your namespace.<br />
* Generate an UUID for your plugin. This way you can use the events engine.<br />
* Use the provided API plugins to perform most of your stuff. If you can’t find an implemented method inside the API you can ASK for an implementation to it.<br />
* '''NEVER USE''' variables/functions which are not accessible through API ! They can be changed or removed at any time.<br />
* If you need to do a background job (ex: start a timer), use the events engine and register a ‘cleanup’ function in which you finish the job (clear the timer).<br />
* We encourage the use of try { … } catch { … } blocks everywhere in your functions so that errors don’t get propagated to the top of the application.<br />
* Start from the skeleton provided and expand it:<br />
<br />
<source lang="javascript"><br />
var MyPlugin = (function (api) {<br />
// example of unique identifier for this plugin...<br />
var uuid = 'B971F6C4-F315-4E2E-AD08-F029A9777517';<br />
<br />
var myModule = {};<br />
<br />
function doSomething() {<br />
// register to event ‘on_ui_cpanel_before_close’...<br />
api.registerEventHandler('on_ui_cpanel_before_close', myModule, ‘cleanUp’);<br />
// and do something... <br />
}<br />
<br />
function cleanUp() {<br />
// perform clean up...<br />
}<br />
<br />
myModule = {<br />
uuid: uuid,<br />
doSomething: doSomething,<br />
cleanUp: cleanUp<br />
};<br />
return myModule;<br />
})(api);<br />
</source><br />
<br />
Your plugin functions will be accessible via ''MyPlugin.doSomething()'' construction.<br />
When the user will leave the cpanel, your plugin will be noticed via event ''‘on_ui_cpanel_before_close’''; this way you can perform the necessary cleanup.<br />
<br />
== JavaScript API ==<br />
<br />
''Defined in'': api.js<br />
<br />
=== Class Summary ===<br />
<br />
----<br />
<br />
'''API(config, application, ui)''' <br />
<br />
- API class for plugins<br />
<br />
'''Parameters:'''<br />
<br />
* {object} config - holds configuration data<br />
* {object} application - application layer<br />
* {object} ui - interface<br />
<br />
=== Method Summary ===<br />
<br />
----<br />
<br />
==== {Object} cloneObject(obj) ====<br />
<br />
- Clones a given object<br />
<br />
- Replaces: cloneObject()<br />
<br />
'''Parameters:'''<br />
<br />
* {object} obj - object to be cloned<br />
<br />
'''Returns:'''<br />
<br />
* {Object}<br />
<br />
==== {string} getCpanelContent() ====<br />
<br />
- Retrieves cpanel content<br />
<br />
- Replaces: get_panel_html()<br />
<br />
'''Returns:'''<br />
<br />
* {string} HTML code set in cpanel<br />
<br />
==== {number} getCpanelDeviceId() ====<br />
<br />
- Returns device id for current opened cpanel or 0 if not found<br />
<br />
'''Returns:'''<br />
<br />
* {number} - device ID<br />
<br />
==== getCurrentHouseMode(onSuccess, onFailure, context) ====<br />
<br />
- Performs a data request to retrieve the current house mode<br />
<br />
'''Parameters:'''<br />
<br />
* {*} onSuccess Optional - function to be called if the call is successfull<br />
* {*} onFailure Optional - function to be called if the call fails<br />
* {object} context Optional - context in which to execute the functions of success and/or failure<br />
<br />
==== {number} getDeviceIndex(deviceId) ====<br />
<br />
- Retrieves device index for given device id<br />
<br />
- Replaces: get_device_index()<br />
<br />
'''Parameters:'''<br />
<br />
* {number} deviceId - id of the device<br />
<br />
'''Returns:'''<br />
<br />
* {number}<br />
<br />
==== {*} getDeviceObject(deviceId) ====<br />
<br />
- Retrieves device object given its id<br />
<br />
- Replaces: get_device_obj()<br />
<br />
'''Parameters:'''<br />
<br />
* {number} deviceId - id of the device<br />
<br />
'''Returns:'''<br />
<br />
* {number}<br />
<br />
===={object} getDeviceState(deviceId, service, variable, options)====<br />
<br />
- Retrieves device state for a device (it can be either read from user data or lu status, depending on the options set)<br />
<br />
'''Parameters:'''<br />
<br />
* {number} deviceId - id of the device<br />
* {string} service - name of the service<br />
* {string} variable - name of the variable<br />
* {object} options Optional - list of options like: 'dynamic': (true - lu_status will be used [default], false - user_data will be used)<br />
<br />
'''Returns:'''<br />
<br />
* {object} value for a given variable<br />
<br />
==== {Object|Boolean} getDeviceTemplate(deviceId) ====<br />
<br />
- Returns device template for a given device id<br />
<br />
'''Parameters:'''<br />
<br />
* {number} deviceId - id of the device<br />
<br />
'''Returns:'''<br />
<br />
* {Object|Boolean}<br />
<br />
==== {*} getDisplayedDeviceName(deviceId) ====<br />
<br />
- Retrieves displayed device name or 'unnamed device' if device doesn't have a name or undefined if device not found<br />
<br />
'''Parameters:'''<br />
<br />
* {number} deviceId - id of the device<br />
<br />
'''Returns:'''<br />
<br />
* {*} if device is found a string which contains the device name or 'Unnamed device' if device name is not set, or undefined if device wasn't found<br />
<br />
==== {*} getEventDefinition(deviceType) ====<br />
<br />
- Retrieves event list for a given device type<br />
<br />
- Replaces: get_event_definition() <br />
<br />
'''Parameters:'''<br />
<br />
* {string} deviceType - type of device<br />
<br />
'''Returns:'''<br />
<br />
* {*}<br />
<br />
==== {*} getListOfDevices() ====<br />
<br />
- Returns the list of devices from userdata<br />
<br />
'''Returns:'''<br />
<br />
* {*}<br />
<br />
==== getLuSdata(onSuccess, onFailure, context) ====<br />
<br />
- Performs a data request to retrieve lu_sdata<br />
<br />
'''Parameters:'''<br />
<br />
* {*} onSuccess Optional - function to be called if the call is successfull<br />
* {*} onFailure Optional - function to be called if the call fails<br />
* {object} context Optional - context in which to execute the functions of success and/or failure<br />
<br />
==== {*|Object} getRoomObject(roomId) ====<br />
<br />
- Returns room object given a room id<br />
<br />
- Replaces: get_room_by_id()<br />
<br />
'''Parameters:'''<br />
<br />
* {number} roomId - id of the room<br />
<br />
'''Returns:'''<br />
<br />
* {*|Object}<br />
<br />
==== {*} getUserData() ====<br />
<br />
- Retrieves userData or null if error<br />
<br />
- Replaces: jsonp.ud<br />
<br />
'''Returns:'''<br />
<br />
* {*} object containing userdata<br />
<br />
==== registerEventHandler(eventName, object, functionName) ====<br />
<br />
- Register an event handler.<br />
<br />
'''Parameters:'''<br />
<br />
* {string} eventName - name of the event to register to<br />
* {object} object - the object which registers to the event<br />
* {string} functionName - the name of the function to be executed if event triggers<br />
<br />
==== runUpnpCode(code, options, onSuccess, onFailure, context) ====<br />
<br />
- Runs given Upnp code<br />
<br />
'''Parameters:'''<br />
<br />
* {string} code - code to execute<br />
* {object} options Optional - optionally options to be supplied (will be documented later)<br />
* {*} onSuccess Optional - function to be called if the call is successfull<br />
* {*} onFailure Optional - function to be called if the call fails<br />
* {object} context Optional - context in which to execute the functions of success and/or failure<br />
<br />
==== setCpanelContent(html) ====<br />
<br />
- Sets content for the cpanel<br />
<br />
- Replaces: set_panel_html()<br />
<br />
'''Parameters:'''<br />
<br />
* {string} html - the new content of the cpanel<br />
<br />
==== setCurrentHouseMode(modeValue, onSuccess, onFailure, context) ====<br />
<br />
- Sets current house mode<br />
<br />
'''Parameters:'''<br />
<br />
* {number} modeValue - new value for the house mode<br />
* {*} onSuccess Optional - function to be called if the call is successfull<br />
* {*} onFailure Optional - function to be called if the call fails<br />
* {object} context Optional - context in which to execute the functions of success and/or failure<br />
<br />
==== setDeviceStateVariable(deviceId, service, variable, value, onSuccess, onFailure, context) ====<br />
<br />
- Sets state for a device variable using variableset request.<br />
<br />
- Replaces: set_device_state()<br />
<br />
'''Parameters:'''<br />
<br />
* {number} deviceId - id of the device<br />
* {string} service - name of the service<br />
* {string} variable - name of the variable<br />
* {*} value - new value for the variable<br />
* {*} onSuccess Optional - function to be called if the call is successfull<br />
* {*} onFailure Optional - function to be called if the call fails<br />
* {object} context Optional - context in which to execute the functions of success and/or failure</div>Andreimioshttp://wiki.mios.com/index.php/File:TopNavigationTab.jpgFile:TopNavigationTab.jpg2014-09-30T15:54:05Z<p>Andreimios: </p>
<hr />
<div></div>Andreimioshttp://wiki.mios.com/index.php/Luup_plugins:_Static_JSON_fileLuup plugins: Static JSON file2014-09-30T15:53:47Z<p>Andreimios: </p>
<hr />
<div>[[Category:Development]]<br />
<br />
Starting in UI4, Luup plugins can specify a ''static JSON'' file. This file describes how the plugin appears in the web interface.<br />
<br />
=What the static JSON file controls=<br />
<br />
* The icon used by the plugin in the dashboard.<br />
* The text that displays in the one-to-two-row status message in the dashboard.<br />
* Whether the icon changes depending on the value of a variable in the device (for example, a binary light's icon changes from lit to unlit).<br />
* The tabs that appear in the device's detail dialog (when you click the wrench/spanner).<br />
* The content of these tabs.<br />
* The triggers or events that are available for the device in the "Triggers" or "Events" tag of a scene.<br />
<br />
=Referencing the static JSON file from the Device XML file=<br />
<br />
The device XML file (customarly '''D_PluginName.xml''') contains a reference to the static JSON file, in the '''staticJson''' element. Place the element as a child of the '''device''' element:<br />
<br />
<pre><nowiki><br />
<?xml version="1.0"?><br />
<root xmlns="urn:schemas-upnp-org:device-1-0"><br />
<specVersion><!-- ... --></specVersion><br />
<device><br />
<deviceType>urn:schemas-futzle-com:device:holidayvirtualswitch:1</deviceType><br />
<staticJson>D_HolidayVirtualSwitch1.json</staticJson><br />
<!-- ... --><br />
</nowiki></pre><br />
<br />
Capitalization is important, as with all XML.<br />
<br />
The static JSON file is customarily called '''D_PluginName.json'''.<br />
<br />
=The static JSON file=<br />
<br />
The static JSON file is a single JSON object (associative array).<br />
<br />
==Root keys==<br />
<br />
These keys have been seen at the top level in static JSON files in the wild:<br />
<br />
; flashicon<br />
: The device's icon, as a string. Despite the name, the icon is no longer related to Adobe Flash in UI4 or UI5. See [[Luup plugin icons]].<br />
; imgIconBody<br />
: Ignored in UI5.<br />
; imgIconDimmable<br />
: Ignored in UI5.<br />
; imgIconTurnable<br />
: Ignored in UI5.<br />
; imgIconMin<br />
: Ignored in UI5.<br />
; imgIconMax<br />
: Ignored in UI5.<br />
; halloIconsDir<br />
: Ignored in UI5.<br />
; inScene<br />
: When included and set equal to one, it enables any buttons, etc located on the "dashboard box", so they can be selected in the scene editor for use in scenes, rather than being grayed out.<br />
; DisplayStatus<br />
: A JSON object (associative array). For devices where the icon changes based on a variable's value, describes which variable, and the range of values that produce different icon images. See [[Luup plugin icons]].<br />
; state_icons<br />
: A JSON array. For devices where the icon changes based on a variable's value, describes which icon files exist. See [[Luup plugin icons]]. Used only in firmware 1.5.401 or later.<br />
; doc_url<br />
: A JSON object (associative array). In UI5, the only item in this object which is used is doc_page. It controls which page in docs5.mios.com is brought up when you click on the help ('''?''') icon in the device control panel.<br />
; Tabs<br />
: A JSON array. Describes the tabs in the detail dialog, and what subset of the first tab appears in the dashboard. See [[Luup plugin tabs]].<br />
; DeviceType<br />
: A JSON string. Must match the '''deviceType''' element in the corresponding device XML ('''D_PluginName.xml''') file.<br />
; eventList<br />
: A JSON object (associative array). Describes the events that this plugin can produce. Events are triggers that can fire off actions in scenes. This key is required for UI4, and obsoleted in UI5. For UI5, use the eventList2 tag, which has a different format. For compatibility with both UI4 and UI5 you need the same information in both keys. See [[UI4 UI5 Migration]] for more information.<br />
; eventList2<br />
: see eventList, above.<br />
; sceneList<br />
: A JSON object (associative array). Describes the actions that this plugin can perform (for instance, as the action in a scene). This key is not required and is ignored in UI5, however it is needed for UI4 compatibility. See [[UI4 UI5 Migration]] for more information about its format.<br />
= UI7 Updates =<br />
<br />
* '''default_icon'''<br />
: replace the old "flashicon" from UI5. See [[Luup plugin icons]]<br />
* '''state_icons'''<br />
: state_icons mechanism has changed in UI7. Please see [[Luup plugin icons]]<br />
* '''TopNavigationTab''' = '''top_navigation_tab'''<br />
<br />
In device cpanel, tabs can be placed either in the top part or in the bottom. By default they are put in the bottom part. You can mark your tabs with a special flag so that they can be placed in top navigation bar of the cpanel.<br />
If two or more tabs are marked with ‘'''TabType=”flash”'''’, only the first one found will be placed in top navigation bar. If you want all of them to be placed there, you have to add ‘'''top_navigation_tab'''’ to each one.<br />
Let’s assume you have a plugin named ‘MyPlugin’ and you want to put a button in the top navigation bar, which, when clicked, will display a message in the cpanel.<br />
<br />
* Add the following lines to the .json device file (D_MyPlugin.json), in the Tabs section:<br />
<source lang="javascript"><br />
{<br />
"Label": {<br />
"lang_tag": "About",<br />
"text": "About"<br />
},<br />
"TopNavigationTab": "1",<br />
"Position": "4",<br />
"TabType": "javascript",<br />
"ScriptName": "J_MyPlugin.js",<br />
"Function": "MyPlugin.about"<br />
}<br />
</source><br />
<br />
Notice the property ‘'''TopNavigationTab'''’ set to the value of ‘1’. This is the line that specifies where to place the tab in cpanel. If you set a value different than 1, the tab will be placed in the bottom part of the cpanel, so always use ‘1’ if you want the tab in the top bar. You can also use ‘'''top_navigation_tab'''’.<br />
<br />
* Add the following lines of code to your .js file (J_MyPlugin.js):<br />
<br />
<source lang="javascript"><br />
var MyPlugin = (function(api){<br />
return {<br />
about: function() {<br />
try { <br />
var html = '<div>This is all about me !</div>';<br />
api.setCpanelContent(html);<br />
} catch (e) {<br />
Utils.logError('Error in MyPlugin.about(): ' + e);<br />
}<br />
}<br />
};<br />
})(api);<br />
</source><br />
<br />
* Perform a lu reload, enter device cpanel and click on ‘About’ button (which is in the top navigation bar of the cpanel) and the result will be something like this:<br />
<br />
[[File:TopNavigationTab.jpg|image|left]]</div>Andreimioshttp://wiki.mios.com/index.php/Luup_plugin_tabsLuup plugin tabs2014-09-30T15:38:47Z<p>Andreimios: </p>
<hr />
<div><br> The '''Tabs''' key in the [[Luup plugins: Static JSON file|static JSON file]] performs two duties in the UI4 HTML interface: <br />
<br />
*It controls how the device appears in the dashboard. <br />
*It controls how each tab appears in the the device's detailed dialog.<br />
<br />
The value of the '''Tabs''' key is a JSON array. Each array element is a JSON object (associative array). <br />
<br />
= Required tab fields =<br />
<br />
These fields must be present in each JSON object in the tab list: <br />
<br />
;'''Label''' <br />
:A JSON object containing two keys: '''lang_tag''' (a string) is not displayed in the HTML interface but may be used by localized UIs; '''text''' (a string) is displayed in the tab's handle at the top of the dialog. <br />
;'''Position''' <br />
:A string which contains a number matching the relative position of this tab in relation to the other tabs. The leftmost tab has value "0", the next tab "1", and so on. <br />
;'''TabType''' <br />
:A string which describes how the content of the tab is to be generated. The value may be one of '''javascript''' or '''flash'''. These are described in the following sections.<br />
<br />
== TabType javascript ==<br />
<br />
The '''javascript''' tab type executes client-side JavaScript, producing an HTML fragment which forms the body of the tab. These additional keys are required in the tab JSON object: <br />
<br />
;'''ScriptName''' <br />
:The name of the JavaScript file. Conventionally, plugin JavaScript files are named '''J_PluginName.js'''. <br />
;'''Function''' <br />
:The function inside the JavaScript file which will be called to produce the HTML.<br />
<br />
The JavaScript code has access to most Luup variables through the [[JavaScript API]]. <br />
<br />
== TabType flash ==<br />
<br />
The '''flash''' tab type creates a tab body with a simple page-description language. Each component of the page is placed into the body at the position specified. You can't place a '''Control''' on the dashboard unless you place it in a '''ControlGroup''', which in turn must be placed in a '''SceneGroup''': <br />
<br />
;'''UI5 SceneGroup'''<br />
<br />
''SceneGroup'' is a new type of container, similar to a ControlGroup, but with some key differences: it is customizable (by setting its position and dimensions) and it defines the behavior of the buttons assigned to the same state variable. If two buttons in the same SceneGroup are assigned to the same variable, only one of them can be activated in the scene editor (radio buttons behavior). If two buttons assigned to the same variable are in different SceneGroups, both can be activated at the same time in the scene editor (checkboxes behavior). <br />
<br />
It has the following tags: <br />
<br />
*'''id''': A numeric value (positive integer numbers). <br />
*'''top''': The offset from the device header. It uses the same units as ''x'' and ''y''. <br />
*'''left''': The offset from the device icon. It uses the same units as ''x'' and ''y''. <br />
*'''x''', '''y''': the dimensions of the SceneGroup. e.g If I have two horizontally aligned buttons in the SceneGroup, ''x'' will be ''2'' and ''y'' will be ''1''.<br />
<br />
A ''SceneGroup'' can contain one or more ''ControlGroups''. <br />
<br />
;'''ControlGroup''' <br />
:Required only if the first tab is also used to display elements on the dashboard. See ''Dashboard appearance'' below. <br />
;'''Control''' <br />
:An array of JSON objects, each representing a control on the tab. The Control Types are described further below. Each control object in the array can also contain: <br />
:'''ControlGroup''' - a reference to the control's control group <br />
:'''top''' - does what? <br />
:'''left''' - does what?<br />
<br />
== Control Types ==<br />
<br />
The '''Control''' array contains JSON objects (associative arrays), one per item in the tab body. An item is either a static text label, a variable, an input field, or a button or slider. This is handled by setting the '''ControlType''' key on the object. <br />
<br />
=== ControlType label ===<br />
<br />
With '''ControlType''' set to '''label''', a fixed label is placed at the specified coordinates. The following additional keys must also be provided: <br />
<br />
;'''Label''' <br />
:A JSON object with two keys: '''lang_tag''' is not displayed but can be used by localizing interfaces to translate the label text. '''text''' is displayed as the content of the label. In UI5 on the "Dashboard", the text is rendered by passing it in the "Title" attribute of a Div statement, so it can only be plain text, (as opposed to say HTML). However in the tabs, it is placed in a Div statement so HTML, such as a URL link, can be rendered. <br />
;'''Display''' <br />
:A JSON object with four keys: '''Top''', '''Left''', '''Width''', '''Height''' (all strings containing numbers). This controls where the label is placed in the tab.<br />
<br />
=== ControlType variable ===<br />
<br />
With '''ControlType''' set to '''variable''', the contents of a Luup variable are displayed at the specified coordinates. The following additional keys must also be provided: <br />
<br />
;'''Display''' <br />
:A JSON object with six keys: '''Top''', '''Left''', '''Width''', '''Height''' (all strings containing numbers, controlling where the variable's value is placed in the tab), '''Service''' (a string containing the Service Id of the variable to be displayed), and '''Variable''' (a string containing the name of the variable to be displayed).<br />
<br />
=== ControlType input ===<br />
<br />
With '''ControlType''' set to '''input''', a text box for the user to type a string is placed in the tab. The following additional keys must also be provided: <br />
<br />
;'''ID''' <br />
:A string which other controls (buttons) will use to refer to the string that the user has typed into this field. <br />
;'''Display''' <br />
:A JSON object with four keys: '''Top''', '''Left''', '''Width''', '''Height''' (all strings containing numbers). This controls where the text box is placed in the tab.<br />
<br />
=== ControlType button ===<br />
<br />
With '''ControlType''' set to '''button''', a clickable button is placed at the specified coordinates. The button will appear selected (depressed) or unselected based on the value of a variable, permitting sets of buttons to act as radio buttons. The following additional keys must also be provided: <br />
<br />
;'''Label''' <br />
:A JSON object with two keys: '''lang_tag''' is not displayed but can be used by localizing interfaces to translate the label text. '''text''' is displayed as the text inside the button. <br />
;'''Display''' <br />
:A JSON object with up to seven keys: '''Top''', '''Left''', '''Width''', '''Height''' (all strings containing numbers, controlling where the button is placed in the tab), '''Service''' (a string containing the Service Id of a variable), and '''Variable''' (a string containing the name of a variable), and (optionally) '''Value''' (a string, "1" if omitted). The specified variable's value controls whether the button appears selected (if the variable matches '''Value''') or not selected (if the variable doesn't match). <br />
;'''Command''' <br />
:A JSON object with three keys: '''Service''' (a string containing the service Id of an action that this device can perform), '''Action''' (a string containing the name of the action), and '''Parameters''' (a JSON array of JSON objects, forming the parameters to pass to the action). Each parameter object has a key '''Name''' for the parameter name, and either a key '''Value''' (for a fixed parameter value) or a key '''ID''' matching an input control on the page (for a user-entered parameter value).<br />
<br />
=== ControlType slider ===<br />
<br />
With '''ControlType''' set to '''slider''', a draggable slider is placed at the specified coordinates. The following additional keys must also be provided: <br />
<br />
;'''Display''' <br />
:A JSON object with nine keys: '''Top''', '''Left''', '''Width''', '''Height''' (all strings containing numbers, controlling where the button is placed in the tab), '''Service''' (a string containing the Service Id of a variable), and '''Variable''' (a string containing the name of a variable), '''MinValue''' and '''MaxValue''' (both strings containing numbers, controlling what range of values the slider takes) and '''ID''' (a string, used in the '''Command''' to refer to the position the user has dragged the slider to). The specified variable's value is used to display the slider's current position. <br />
;'''Command''' <br />
:A JSON object with three keys: '''Service''' (a string containing the service Id of an action that this device can perform), '''Action''' (a string containing the name of the action), and '''Parameters''' (a JSON array of JSON objects, forming the parameters to pass to the action). Each parameter object has a key '''Name''' for the parameter name, and either a key '''Value''' (for a fixed parameter value) or a key '''ID''' matching the slider's ID (for a value matching what the user has dragged the slider to). <br />
;'''ControlHeader''' <br />
:Optional. If present, must have string value "1". When set, the slider's label and value are displayed. Otherwise only the slider is shown. (TODO: This is from reverse-engineering the JavaScript code. Test this.)<br />
<br />
=== ControlType slider_vertical ===<br />
<br />
:Used in: D_Heater1.json, D_HVAC_ZoneThermostat1.json<br />
<br />
=== ControlType checkbox ===<br />
<br />
:As of UI5 firmware 1.5.622, checkboxes are only half-baked and not usable in "flash" style tabs. If you need check-boxes, radio buttons, pop-up menus, etc. in your tab, you need to create a Javascript tab.<br />
<br />
=== ControlType image ===<br />
<br />
:Used in: D_DigitalSecurityCamera1.json<br />
<br />
=== ControlType image_player ===<br />
<br />
:Used in: D_DigitalSecurityCamera1.json<br />
<br />
=== ControlType js_button ===<br />
<br />
:Used in: D_DigitalSecurityCamera1.json<br />
<br />
= Dashboard appearance =<br />
<br />
The first array element in the '''Tabs''' field is special. If it is of type '''flash''' then a subset of the controls on the tab can be chosen to display on the UI4 dashboard.<br />
<br />
== Control Groups ==<br />
<br />
The dashboard box for a device has room for two rows of information and controls. These are called ''Control Groups''.<br />
<br />
The tab object must contain the key '''ControlGroup''', which specifies how the dashboard's two available rows of information are to be handled. '''ControlGroup''' is a JSON array containing JSON objects (associative arrays). Each object has the following keys:<br />
<br />
;'''id''' <br />
:A string containing a number, "1" for the first object, "2" for the second, and so on. <br />
;'''isSingle''' <br />
:UI4: If this key is present and contains the value "1", then this control group is combined with other control groups that have '''isSingle''' similarly set onto the same row. For an example of this, see the On/Off buttons of the Binary Switch and Dimmable Switch static JSON files. <br />
:UI5: Since controls cannot be grouped in drop-down lists anymore, this tag has a different role in UI5. When isSingle is "1", the buttons in the ControlGroup will have a background (e.g. the BinaryLight buttons). If isSingle is missing, the buttons won't have a background. That is the button shape is not shown; only the button text will show. <br />
;'''type''' <br />
:If this key is present and contains the value "info", then the controls displayed on this row are not clickable. If this key is absent, buttons may be used in the control group.<br />
<br />
== Making a control appear on the dashboard ==<br />
<br />
All control types (label, variable, button, input, slider) can appear in the dashboard. However, by default, controls in the first tab's detail view do not appear in the dashboard. To make a control's text appear in the dashboard, add a '''ControlGroup''' to the control's JSON object. The value is a string containing a number, matching the '''id''' of one of the Tab's overall '''ControlGroup''' key. The dashboard will concatenate all of a control group's controls in the order they are presented in the '''Control''' array, and display them in a single row of text. <br />
<br />
== Keeping controls together ==<br />
<br />
Some controls may not make sense if presented individually (for instance, an input for an alarm PIN and a "disarm" button). To keep these controls together, add a '''ControlPair''' key to all of the controls that have to appear together. Use the same value (a number in a string) for all of them. <br />
<br />
[[Category:Development]]<br />
<br />
= UI7 Updates =<br />
<br />
=== ControlType multi_state_button === <br />
This is a new type of control in UI7 and works as a “toggle” button. It is used for On/Off, Armed/Disarmed etc buttons.<br />
<br />
As an example, here is the definition from the .json file of the Door/Window sensor needed to create this kind of control:<br />
<source lang="javascript"><br />
{<br />
"ControlGroup": "1",<br />
"ControlType": "multi_state_button",<br />
"top": "0",<br />
"left": "1",<br />
"states": [<br />
{<br />
"Label": {<br />
"lang_tag": "ui7_cmd_arm",<br />
"text": "Arm"<br />
},<br />
"ControlGroup": "1",<br />
"Display": {<br />
"Service": "urn:micasaverde-com:serviceId:SecuritySensor1",<br />
"Variable": "Armed",<br />
"Value": "1"<br />
},<br />
"Command": {<br />
“Service": "urn:micasaverde-com:serviceId:SecuritySensor1",<br />
"Action": "SetArmed",<br />
"Parameters": [<br />
{<br />
"Name": "newArmedValue",<br />
"Value": "1"<br />
}<br />
]<br />
},<br />
"ControlCode": "arm"<br />
},<br />
{<br />
"Label": {<br />
"lang_tag": "ui7_cmd_bypass",<br />
"text": "Bypass"<br />
},<br />
"ControlGroup": "1",<br />
"Display": {<br />
"Service": "urn:micasaverde-com:serviceId:SecuritySensor1",<br />
"Variable": "Armed",<br />
"Value": "0"<br />
},<br />
"Command": {<br />
"Service": "urn:micasaverde-com:serviceId:SecuritySensor1",<br />
"Action": "SetArmed",<br />
"Parameters": [<br />
{<br />
"Name": "newArmedValue",<br />
"Value": "0"<br />
}<br />
]<br />
},<br />
"ControlCode": "bypass"<br />
}<br />
]<br />
}<br />
</source><br />
<br />
* '''ControlGroup''' - an integer - has the same behaviour as in previous UIs <br />
* '''ControlType''' - a string which must be set to ‘multi_state_button’<br />
* '''top''' - an integer specifying the row from the control group where the control will be placed<br />
* '''left''' - an integer which specifies which column will the control be placed in<br />
* '''states''' - an array of objects, each object representing a different state for the button; each object has the following properties:<br />
** '''Lable''' - a JSON object with two keys:<br />
*** '''lang_tag''' - a string used for localization<br />
*** '''text''' - the string displayed if localization fails<br />
** '''Display''' - a JSON object with the following keys:<br />
*** '''Service''' - a string containing the service id<br />
*** '''Variable''' - a string containing the name of the variable<br />
*** '''Value''' - a number which represents the value of the state in which the control must be in order for this state to be displayed/marked as selected<br />
** '''Command''' - a JSON object with the following properties:<br />
*** '''Service''' - a string with the service id of the action which this state will perform<br />
*** '''Action''' - a string representing the name of the action to be executed<br />
** '''Parameters''' - an array of JSON objects holding the parameters to pass to the action<br />
* '''ControlCode''' - a string containing the control code of this control (it is recommended to be unique for each device type)<br />
<br />
As you can see, the multi_state_button is a merge resulted from two controls of type button.<br />
<br />
[[File:MotionSensor.jpg|image|left]]</div>Andreimioshttp://wiki.mios.com/index.php/Luup_plugin_tabsLuup plugin tabs2014-09-30T15:38:09Z<p>Andreimios: </p>
<hr />
<div><br> The '''Tabs''' key in the [[Luup plugins: Static JSON file|static JSON file]] performs two duties in the UI4 HTML interface: <br />
<br />
*It controls how the device appears in the dashboard. <br />
*It controls how each tab appears in the the device's detailed dialog.<br />
<br />
The value of the '''Tabs''' key is a JSON array. Each array element is a JSON object (associative array). <br />
<br />
= Required tab fields =<br />
<br />
These fields must be present in each JSON object in the tab list: <br />
<br />
;'''Label''' <br />
:A JSON object containing two keys: '''lang_tag''' (a string) is not displayed in the HTML interface but may be used by localized UIs; '''text''' (a string) is displayed in the tab's handle at the top of the dialog. <br />
;'''Position''' <br />
:A string which contains a number matching the relative position of this tab in relation to the other tabs. The leftmost tab has value "0", the next tab "1", and so on. <br />
;'''TabType''' <br />
:A string which describes how the content of the tab is to be generated. The value may be one of '''javascript''' or '''flash'''. These are described in the following sections.<br />
<br />
== TabType javascript ==<br />
<br />
The '''javascript''' tab type executes client-side JavaScript, producing an HTML fragment which forms the body of the tab. These additional keys are required in the tab JSON object: <br />
<br />
;'''ScriptName''' <br />
:The name of the JavaScript file. Conventionally, plugin JavaScript files are named '''J_PluginName.js'''. <br />
;'''Function''' <br />
:The function inside the JavaScript file which will be called to produce the HTML.<br />
<br />
The JavaScript code has access to most Luup variables through the [[JavaScript API]]. <br />
<br />
== TabType flash ==<br />
<br />
The '''flash''' tab type creates a tab body with a simple page-description language. Each component of the page is placed into the body at the position specified. You can't place a '''Control''' on the dashboard unless you place it in a '''ControlGroup''', which in turn must be placed in a '''SceneGroup''': <br />
<br />
;'''UI5 SceneGroup'''<br />
<br />
''SceneGroup'' is a new type of container, similar to a ControlGroup, but with some key differences: it is customizable (by setting its position and dimensions) and it defines the behavior of the buttons assigned to the same state variable. If two buttons in the same SceneGroup are assigned to the same variable, only one of them can be activated in the scene editor (radio buttons behavior). If two buttons assigned to the same variable are in different SceneGroups, both can be activated at the same time in the scene editor (checkboxes behavior). <br />
<br />
It has the following tags: <br />
<br />
*'''id''': A numeric value (positive integer numbers). <br />
*'''top''': The offset from the device header. It uses the same units as ''x'' and ''y''. <br />
*'''left''': The offset from the device icon. It uses the same units as ''x'' and ''y''. <br />
*'''x''', '''y''': the dimensions of the SceneGroup. e.g If I have two horizontally aligned buttons in the SceneGroup, ''x'' will be ''2'' and ''y'' will be ''1''.<br />
<br />
A ''SceneGroup'' can contain one or more ''ControlGroups''. <br />
<br />
;'''ControlGroup''' <br />
:Required only if the first tab is also used to display elements on the dashboard. See ''Dashboard appearance'' below. <br />
;'''Control''' <br />
:An array of JSON objects, each representing a control on the tab. The Control Types are described further below. Each control object in the array can also contain: <br />
:'''ControlGroup''' - a reference to the control's control group <br />
:'''top''' - does what? <br />
:'''left''' - does what?<br />
<br />
== Control Types ==<br />
<br />
The '''Control''' array contains JSON objects (associative arrays), one per item in the tab body. An item is either a static text label, a variable, an input field, or a button or slider. This is handled by setting the '''ControlType''' key on the object. <br />
<br />
=== ControlType label ===<br />
<br />
With '''ControlType''' set to '''label''', a fixed label is placed at the specified coordinates. The following additional keys must also be provided: <br />
<br />
;'''Label''' <br />
:A JSON object with two keys: '''lang_tag''' is not displayed but can be used by localizing interfaces to translate the label text. '''text''' is displayed as the content of the label. In UI5 on the "Dashboard", the text is rendered by passing it in the "Title" attribute of a Div statement, so it can only be plain text, (as opposed to say HTML). However in the tabs, it is placed in a Div statement so HTML, such as a URL link, can be rendered. <br />
;'''Display''' <br />
:A JSON object with four keys: '''Top''', '''Left''', '''Width''', '''Height''' (all strings containing numbers). This controls where the label is placed in the tab.<br />
<br />
=== ControlType variable ===<br />
<br />
With '''ControlType''' set to '''variable''', the contents of a Luup variable are displayed at the specified coordinates. The following additional keys must also be provided: <br />
<br />
;'''Display''' <br />
:A JSON object with six keys: '''Top''', '''Left''', '''Width''', '''Height''' (all strings containing numbers, controlling where the variable's value is placed in the tab), '''Service''' (a string containing the Service Id of the variable to be displayed), and '''Variable''' (a string containing the name of the variable to be displayed).<br />
<br />
=== ControlType input ===<br />
<br />
With '''ControlType''' set to '''input''', a text box for the user to type a string is placed in the tab. The following additional keys must also be provided: <br />
<br />
;'''ID''' <br />
:A string which other controls (buttons) will use to refer to the string that the user has typed into this field. <br />
;'''Display''' <br />
:A JSON object with four keys: '''Top''', '''Left''', '''Width''', '''Height''' (all strings containing numbers). This controls where the text box is placed in the tab.<br />
<br />
=== ControlType button ===<br />
<br />
With '''ControlType''' set to '''button''', a clickable button is placed at the specified coordinates. The button will appear selected (depressed) or unselected based on the value of a variable, permitting sets of buttons to act as radio buttons. The following additional keys must also be provided: <br />
<br />
;'''Label''' <br />
:A JSON object with two keys: '''lang_tag''' is not displayed but can be used by localizing interfaces to translate the label text. '''text''' is displayed as the text inside the button. <br />
;'''Display''' <br />
:A JSON object with up to seven keys: '''Top''', '''Left''', '''Width''', '''Height''' (all strings containing numbers, controlling where the button is placed in the tab), '''Service''' (a string containing the Service Id of a variable), and '''Variable''' (a string containing the name of a variable), and (optionally) '''Value''' (a string, "1" if omitted). The specified variable's value controls whether the button appears selected (if the variable matches '''Value''') or not selected (if the variable doesn't match). <br />
;'''Command''' <br />
:A JSON object with three keys: '''Service''' (a string containing the service Id of an action that this device can perform), '''Action''' (a string containing the name of the action), and '''Parameters''' (a JSON array of JSON objects, forming the parameters to pass to the action). Each parameter object has a key '''Name''' for the parameter name, and either a key '''Value''' (for a fixed parameter value) or a key '''ID''' matching an input control on the page (for a user-entered parameter value).<br />
<br />
=== ControlType slider ===<br />
<br />
With '''ControlType''' set to '''slider''', a draggable slider is placed at the specified coordinates. The following additional keys must also be provided: <br />
<br />
;'''Display''' <br />
:A JSON object with nine keys: '''Top''', '''Left''', '''Width''', '''Height''' (all strings containing numbers, controlling where the button is placed in the tab), '''Service''' (a string containing the Service Id of a variable), and '''Variable''' (a string containing the name of a variable), '''MinValue''' and '''MaxValue''' (both strings containing numbers, controlling what range of values the slider takes) and '''ID''' (a string, used in the '''Command''' to refer to the position the user has dragged the slider to). The specified variable's value is used to display the slider's current position. <br />
;'''Command''' <br />
:A JSON object with three keys: '''Service''' (a string containing the service Id of an action that this device can perform), '''Action''' (a string containing the name of the action), and '''Parameters''' (a JSON array of JSON objects, forming the parameters to pass to the action). Each parameter object has a key '''Name''' for the parameter name, and either a key '''Value''' (for a fixed parameter value) or a key '''ID''' matching the slider's ID (for a value matching what the user has dragged the slider to). <br />
;'''ControlHeader''' <br />
:Optional. If present, must have string value "1". When set, the slider's label and value are displayed. Otherwise only the slider is shown. (TODO: This is from reverse-engineering the JavaScript code. Test this.)<br />
<br />
=== ControlType slider_vertical ===<br />
<br />
:Used in: D_Heater1.json, D_HVAC_ZoneThermostat1.json<br />
<br />
=== ControlType checkbox ===<br />
<br />
:As of UI5 firmware 1.5.622, checkboxes are only half-baked and not usable in "flash" style tabs. If you need check-boxes, radio buttons, pop-up menus, etc. in your tab, you need to create a Javascript tab.<br />
<br />
=== ControlType image ===<br />
<br />
:Used in: D_DigitalSecurityCamera1.json<br />
<br />
=== ControlType image_player ===<br />
<br />
:Used in: D_DigitalSecurityCamera1.json<br />
<br />
=== ControlType js_button ===<br />
<br />
:Used in: D_DigitalSecurityCamera1.json<br />
<br />
= Dashboard appearance =<br />
<br />
The first array element in the '''Tabs''' field is special. If it is of type '''flash''' then a subset of the controls on the tab can be chosen to display on the UI4 dashboard.<br />
<br />
== Control Groups ==<br />
<br />
The dashboard box for a device has room for two rows of information and controls. These are called ''Control Groups''.<br />
<br />
The tab object must contain the key '''ControlGroup''', which specifies how the dashboard's two available rows of information are to be handled. '''ControlGroup''' is a JSON array containing JSON objects (associative arrays). Each object has the following keys:<br />
<br />
;'''id''' <br />
:A string containing a number, "1" for the first object, "2" for the second, and so on. <br />
;'''isSingle''' <br />
:UI4: If this key is present and contains the value "1", then this control group is combined with other control groups that have '''isSingle''' similarly set onto the same row. For an example of this, see the On/Off buttons of the Binary Switch and Dimmable Switch static JSON files. <br />
:UI5: Since controls cannot be grouped in drop-down lists anymore, this tag has a different role in UI5. When isSingle is "1", the buttons in the ControlGroup will have a background (e.g. the BinaryLight buttons). If isSingle is missing, the buttons won't have a background. That is the button shape is not shown; only the button text will show. <br />
;'''type''' <br />
:If this key is present and contains the value "info", then the controls displayed on this row are not clickable. If this key is absent, buttons may be used in the control group.<br />
<br />
== Making a control appear on the dashboard ==<br />
<br />
All control types (label, variable, button, input, slider) can appear in the dashboard. However, by default, controls in the first tab's detail view do not appear in the dashboard. To make a control's text appear in the dashboard, add a '''ControlGroup''' to the control's JSON object. The value is a string containing a number, matching the '''id''' of one of the Tab's overall '''ControlGroup''' key. The dashboard will concatenate all of a control group's controls in the order they are presented in the '''Control''' array, and display them in a single row of text. <br />
<br />
== Keeping controls together ==<br />
<br />
Some controls may not make sense if presented individually (for instance, an input for an alarm PIN and a "disarm" button). To keep these controls together, add a '''ControlPair''' key to all of the controls that have to appear together. Use the same value (a number in a string) for all of them. <br />
<br />
[[Category:Development]]<br />
<br />
= UI7 Updates =<br />
<br />
=== ControlType multi_state_button === <br />
This is a new type of control in UI7 and works as a “toggle” button. It is used for On/Off, Armed/Disarmed etc buttons.<br />
<br />
As an example, here is the definition from the .json file of the Door/Window sensor needed to create this kind of control:<br />
<source lang="javascript"><br />
{<br />
"ControlGroup": "1",<br />
"ControlType": "multi_state_button",<br />
"top": "0",<br />
"left": "1",<br />
"states": [<br />
{<br />
"Label": {<br />
"lang_tag": "ui7_cmd_arm",<br />
"text": "Arm"<br />
},<br />
"ControlGroup": "1",<br />
"Display": {<br />
"Service": "urn:micasaverde-com:serviceId:SecuritySensor1",<br />
"Variable": "Armed",<br />
"Value": "1"<br />
},<br />
"Command": {<br />
“Service": "urn:micasaverde-com:serviceId:SecuritySensor1",<br />
"Action": "SetArmed",<br />
"Parameters": [<br />
{<br />
"Name": "newArmedValue",<br />
"Value": "1"<br />
}<br />
]<br />
},<br />
"ControlCode": "arm"<br />
},<br />
{<br />
"Label": {<br />
"lang_tag": "ui7_cmd_bypass",<br />
"text": "Bypass"<br />
},<br />
"ControlGroup": "1",<br />
"Display": {<br />
"Service": "urn:micasaverde-com:serviceId:SecuritySensor1",<br />
"Variable": "Armed",<br />
"Value": "0"<br />
},<br />
"Command": {<br />
"Service": "urn:micasaverde-com:serviceId:SecuritySensor1",<br />
"Action": "SetArmed",<br />
"Parameters": [<br />
{<br />
"Name": "newArmedValue",<br />
"Value": "0"<br />
}<br />
]<br />
},<br />
"ControlCode": "bypass"<br />
}<br />
]<br />
}<br />
</source><br />
<br />
* '''ControlGroup''' - an integer - has the same behaviour as in previous UIs <br />
* '''ControlType''' - a string which must be set to ‘multi_state_button’<br />
* '''top''' - an integer specifying the row from the control group where the control will be placed<br />
* '''left''' - an integer which specifies which column will the control be placed in<br />
* '''states''' - an array of objects, each object representing a different state for the button; each object has the following properties:<br />
** '''Lable''' - a JSON object with two keys:<br />
*** '''lang_tag''' - a string used for localization<br />
*** '''text''' - the string displayed if localization fails<br />
** '''Display''' - a JSON object with the following keys:<br />
*** '''Service''' - a string containing the service id<br />
*** '''Variable''' - a string containing the name of the variable<br />
*** '''Value''' - a number which represents the value of the state in which the control must be in order for this state to be displayed/marked as selected<br />
** '''Command''' - a JSON object with the following properties:<br />
*** '''Service''' - a string with the service id of the action which this state will perform<br />
*** '''Action''' - a string representing the name of the action to be executed<br />
** '''Parameters''' - an array of JSON objects holding the parameters to pass to the action<br />
* '''ControlCode''' - a string containing the control code of this control (it is recommended to be unique for each device type)<br />
<br />
As you can see, the multi_state_button is a merge resulted from two controls of type button.<br />
<br />
[[File:MotionSensor.jpg|thumb|left]]</div>Andreimioshttp://wiki.mios.com/index.php/File:MotionSensor.jpgFile:MotionSensor.jpg2014-09-30T15:37:43Z<p>Andreimios: </p>
<hr />
<div></div>Andreimioshttp://wiki.mios.com/index.php/Luup_plugin_iconsLuup plugin icons2014-09-30T15:01:44Z<p>Andreimios: </p>
<hr />
<div>[[Category:Development]]<br />
<br />
The [[Luup plugins: Static JSON file|Luup plugin static JSON file]] describes the icon that appears in the dashboard of the UI4 web interface.<br />
<br />
=Icon format=<br />
<br />
All of Vera's icons are 42x42 pixel PNGs with transparency. Icons of other sizes will be resized to 42x42.<br />
<br />
=Configuration=<br />
<br />
The top-level key '''flashicon''' contains a string. This string is the name of an image file. The filename is either a relative path or a URL starting with "http".<br />
<br />
==Relative paths==<br />
<br />
If the filename is a relative path, it is relative to the directory '''/www/cmh/skins/default''' on the Vera. If the filename ends in the string ".swf", this extension is changed to ".png". (This is presumably a holdover from UI3, which was flash-based. In UI4, there is no reason to maintain this ruse, so just use the ".png" extension.)<br />
<br />
Files installed in the "icons" directory are:<br />
* Binary_Light.png<br />
* Binary_Light_0.png<br />
* Binary_Light_100.png<br />
* Dimmable_Light.png<br />
* Dimmable_Light_0.png<br />
* Dimmable_Light_100.png<br />
* Dimmable_Light_25.png<br />
* Dimmable_Light_50.png<br />
* Dimmable_Light_75.png<br />
* Door_Lock.png<br />
* Door_Lock_0.png<br />
* Door_Lock_100.png<br />
* Generic_IO.png<br />
* Humidity_Sensor.png<br />
* IR_Transmitter.png<br />
* Insteon.png<br />
* Ip_Camera.png<br />
* Light_Sensor.png<br />
* Motion_Sensor.png<br />
* Motion_Sensor_0.png<br />
* Motion_Sensor_100.png<br />
* Power_Meter.png<br />
* Scenes.png<br />
* Temperature_Sensor.png<br />
* Thermostat.png<br />
* USB_UIRT.png<br />
* Window_Covering.png<br />
* Zwave.png<br />
* advanced.png<br />
* default.png<br />
* default_device.png<br />
* default_panel.png<br />
* default_plugins.png<br />
* device.png<br />
* devices.png<br />
* energy.png<br />
* findvera.png<br />
* generic_icon.png<br />
* generic_sensor.png<br />
* intro.png<br />
* location.png<br />
* music_audio.png<br />
* plugins.png<br />
* users.png<br />
<br />
== URLs ==<br />
<br />
If the filename is a URL, it refers to a remote file on a web server.<br />
<br />
=Constant icons=<br />
<br />
For an icon that remains the same all the time, the '''flashicon''' key is all you need to provide. Ensure that the static JSON file does not contain a '''DisplayStatus''' key, and you are done.<br />
<br />
= Variable icons =<br />
<br />
For an icon that varies based on the value of a variable, place a '''DisplayStatus''' key at the top level of the static JSON file. Its value is a JSON object (associative array) with four keys: <br />
<br />
;Service <br />
:The Service ID of the variable that controls the icon. This can be found in the matching device XML file, under the '''serviceId''' element. <br />
;Variable <br />
:The variable name of the variable that controls the icon. <br />
;MinValue <br />
:The value that this variable has when it is considered "off" or at "0%". This can even be a string, if the variable is a string that takes two values. <br />
;MaxValue <br />
:The value that this variable has when it is considered "on" or at "100%". This can even be a string, if the variable is a string that takes two values.<br />
<br />
Example for a binary switch: <br />
<pre> "DisplayStatus": {<br />
"Service": "urn:upnp-org:serviceId:SwitchPower1",<br />
"Variable": "Status",<br />
"MinValue": "0",<br />
"MaxValue": "1"<br />
}<br />
</pre> <br />
Example for a variable which takes on a range of values. <br />
<pre> "DisplayStatus": {<br />
"Service": "urn:upnp-org:serviceId:Dimming1",<br />
"Variable": "LoadLevelStatus",<br />
"MinValue": "0",<br />
"MaxValue": "100" <br />
}<br />
</pre> <br />
The filename in '''flashicon''' undergoes a special transformation for variable icons. The extension ".png" is changed to "_0.png", "_25.png", "_50.png", "_75.png" or "_100.png" depending on the value of the service variable, linearly scaled from its range of 0:(MaxValue-MinValue) to 0:100. Values round up; 1-25 produces the "_25" image; 26-50 produces the "_50" image, and so on. For images which are not found (for instance, if the web server returns '''404 Not Found''') the default image is used. <br />
<br />
Consequently, at least three images, and as many as six, should be present for variable-icon plugins. For example, if '''flashicon''' contains '''<nowiki>http://example.com/image.png</nowiki>''', the web server must be able to serve: <br />
<br />
*'''<nowiki>http://example.com/image.png</nowiki>''' (for when the plugin is loading in the Luup engine) <br />
*'''<nowiki>http://example.com/image_0.png</nowiki>''' <br />
*'''<nowiki>http://example.com/image_100.png</nowiki>'''<br />
<br />
and it should be able to serve (if the variable is a sliding scale): <br />
<br />
*'''<nowiki>http://example.com/image_25.png</nowiki>''' <br />
*'''<nowiki>http://example.com/image_50.png</nowiki>''' <br />
*'''<nowiki>http://example.com/image_75.png</nowiki>'''<br />
<br />
== state_icons ==<br />
<br />
From firmware 1.5.401 onwards, you must also tell the Static JSON file which icon files exist, with the '''state_icons''' key at the top level. The corresponding value is a JSON array of strings, the file names which should be displayed in the UI. This key was added to prevent the plethora of 404 errors that would appear in the JavaScript console. <br />
<br />
Currently each device can have a maximum of 5 icons. The formula for choosing the icon is this:<br />
<br />
<source lang="javascript"><br />
var status = Variable / (MaxValue - MinValue);<br />
var val = ceil( status * 4 );<br />
var icon = baseIconName + "_" + (isNaN( val * 25 ) ? 0 : (val * 25)) + ".png";<br />
</source><br />
<br />
<br />
e.g. For the dimmable light, the formula would look like this:<br />
<br />
<source lang="javascript"><br />
var status = LoadLevelStatus / (100 - 0);<br />
var val = ceil( status * 4 );<br />
var icon = "Dimmable_Light" + "_" + (isNaN( val * 25 ) ? 0 : (val * 25)) + ".png";</source><br />
<br />
The resulting intervals and icons are:<br />
{| class="wikitable"<br />
! LoadLevelStatus<br />
! Icon<br />
|-<br />
| 0<br />
| Dimmable_Light_0.png<br />
|-<br />
| 1 - 25<br />
| Dimmable_Light_25.png<br />
|-<br />
| 26 - 50<br />
| Dimmable_Light_50.png<br />
|-<br />
| 51 - 75<br />
| Dimmable_Light_75.png<br />
|-<br />
| 76 - 100<br />
| Dimmable_Light_100.png<br />
|}<br />
<br />
== Cheating to get finer-grained variable icons ==<br />
<br />
The JavaScript code that inserts the strings "_0" to "_100" into the image filename does not check that the raw variable value is in the range '''MinValue''' to '''MaxValue'''. By deliberately choosing a '''MaxValue''' less than the highest value that a variable can take, you can make the JavaScript load images with "_125", "_150", etc., effectively providing any number of images. '''MinValue''' is similarly handled, though the results are odd with negative variables or MinValue not equal to zero: the string inserted into the filename is "_-25", "-50", etc. <br />
<br />
That this trick works is probably accidental, and its behaviour probably should not be relied on.<br />
= UI7 Icons=<br />
<br />
To avoid adding extra code to treat plugin icons, all plugin developers should take into consideration the following:<br />
<br />
*'''<nowiki>"default_icon"</nowiki>'''<br />
"'''flashicon'''" - we don't use it any more, instead we will have "default_icon" as in the above example, which can be either the url from a image uploaded somewhere on the web or a image stored locally in skins/default/img/devices/device_sates/ . Please be sure if you choose the last method to not upload images with names identical to any of the existing device state icon files. Image resolution should be 50px x 50px.<br />
*'''<nowiki>"state_icons"</nowiki>'''<br />
If the device created by the plugin has states and we need to display them we will use this object. "img" is the state image, same as above, it's a url to a image uploaded on the web or the name of a image stored locally in skins/default/img/devices/device_sates/. "conditions" is an array of objects from which we build logical expressions and evaluate them to decide what icon to be used for what state. In the example above if in lu_status for a given binary light with "subcategory_num" = 0 ( this means indoor binary light , because we also have devices for outdoor use like the Jasco 45604) we find service : "urn:upnp-org:serviceId:SwitchPower1", variable : "Status" and the value from this pair is equal ("operator") to the "value" (0) in the conditions object then we show the "binary_light_off.png" in the UI (light is off). A good example of usage for "subcategory_num" can be seen in the json definition of the motion sensor D_MotionSensor1.json - which serves as template for a number of types of sensors but I am not sure if this will be the case for plugins("subcategory_num" is not mandatory). As I said "conditions" is an array of objects, this means that if we want to display a certain icon based on more than 1 condition we can do so by adding to it more objects defining different conditions.<br />
<br />
Example: <br />
<br />
<source lang="javascript"><br />
{<br />
"default_icon": "binary_light_default.png",<br />
"state_icons": [<br />
{<br />
"img": "binary_light_off.png",<br />
"conditions": [<br />
{<br />
"service": "urn:upnp-org:serviceId:SwitchPower1",<br />
"variable": "Status",<br />
"operator": "==",<br />
"value": 0,<br />
"subcategory_num": 0<br />
}<br />
]<br />
},<br />
{<br />
"img": "binary_light_on.png",<br />
"conditions": [<br />
{<br />
"service": "urn:upnp-org:serviceId:SwitchPower1",<br />
"variable": "Status",<br />
"operator": "==",<br />
"value": 1,<br />
"subcategory_num": 0<br />
}<br />
]<br />
}<br />
],<br />
...<br />
}<br />
</source></div>Andreimioshttp://wiki.mios.com/index.php/Luup_plugin_tabsLuup plugin tabs2014-09-30T14:54:25Z<p>Andreimios: </p>
<hr />
<div><br> The '''Tabs''' key in the [[Luup plugins: Static JSON file|static JSON file]] performs two duties in the UI4 HTML interface: <br />
<br />
*It controls how the device appears in the dashboard. <br />
*It controls how each tab appears in the the device's detailed dialog.<br />
<br />
The value of the '''Tabs''' key is a JSON array. Each array element is a JSON object (associative array). <br />
<br />
= Required tab fields =<br />
<br />
These fields must be present in each JSON object in the tab list: <br />
<br />
;'''Label''' <br />
:A JSON object containing two keys: '''lang_tag''' (a string) is not displayed in the HTML interface but may be used by localized UIs; '''text''' (a string) is displayed in the tab's handle at the top of the dialog. <br />
;'''Position''' <br />
:A string which contains a number matching the relative position of this tab in relation to the other tabs. The leftmost tab has value "0", the next tab "1", and so on. <br />
;'''TabType''' <br />
:A string which describes how the content of the tab is to be generated. The value may be one of '''javascript''' or '''flash'''. These are described in the following sections.<br />
<br />
== TabType javascript ==<br />
<br />
The '''javascript''' tab type executes client-side JavaScript, producing an HTML fragment which forms the body of the tab. These additional keys are required in the tab JSON object: <br />
<br />
;'''ScriptName''' <br />
:The name of the JavaScript file. Conventionally, plugin JavaScript files are named '''J_PluginName.js'''. <br />
;'''Function''' <br />
:The function inside the JavaScript file which will be called to produce the HTML.<br />
<br />
The JavaScript code has access to most Luup variables through the [[JavaScript API]]. <br />
<br />
== TabType flash ==<br />
<br />
The '''flash''' tab type creates a tab body with a simple page-description language. Each component of the page is placed into the body at the position specified. You can't place a '''Control''' on the dashboard unless you place it in a '''ControlGroup''', which in turn must be placed in a '''SceneGroup''': <br />
<br />
;'''UI5 SceneGroup'''<br />
<br />
''SceneGroup'' is a new type of container, similar to a ControlGroup, but with some key differences: it is customizable (by setting its position and dimensions) and it defines the behavior of the buttons assigned to the same state variable. If two buttons in the same SceneGroup are assigned to the same variable, only one of them can be activated in the scene editor (radio buttons behavior). If two buttons assigned to the same variable are in different SceneGroups, both can be activated at the same time in the scene editor (checkboxes behavior). <br />
<br />
It has the following tags: <br />
<br />
*'''id''': A numeric value (positive integer numbers). <br />
*'''top''': The offset from the device header. It uses the same units as ''x'' and ''y''. <br />
*'''left''': The offset from the device icon. It uses the same units as ''x'' and ''y''. <br />
*'''x''', '''y''': the dimensions of the SceneGroup. e.g If I have two horizontally aligned buttons in the SceneGroup, ''x'' will be ''2'' and ''y'' will be ''1''.<br />
<br />
A ''SceneGroup'' can contain one or more ''ControlGroups''. <br />
<br />
;'''ControlGroup''' <br />
:Required only if the first tab is also used to display elements on the dashboard. See ''Dashboard appearance'' below. <br />
;'''Control''' <br />
:An array of JSON objects, each representing a control on the tab. The Control Types are described further below. Each control object in the array can also contain: <br />
:'''ControlGroup''' - a reference to the control's control group <br />
:'''top''' - does what? <br />
:'''left''' - does what?<br />
<br />
== Control Types ==<br />
<br />
The '''Control''' array contains JSON objects (associative arrays), one per item in the tab body. An item is either a static text label, a variable, an input field, or a button or slider. This is handled by setting the '''ControlType''' key on the object. <br />
<br />
=== ControlType label ===<br />
<br />
With '''ControlType''' set to '''label''', a fixed label is placed at the specified coordinates. The following additional keys must also be provided: <br />
<br />
;'''Label''' <br />
:A JSON object with two keys: '''lang_tag''' is not displayed but can be used by localizing interfaces to translate the label text. '''text''' is displayed as the content of the label. In UI5 on the "Dashboard", the text is rendered by passing it in the "Title" attribute of a Div statement, so it can only be plain text, (as opposed to say HTML). However in the tabs, it is placed in a Div statement so HTML, such as a URL link, can be rendered. <br />
;'''Display''' <br />
:A JSON object with four keys: '''Top''', '''Left''', '''Width''', '''Height''' (all strings containing numbers). This controls where the label is placed in the tab.<br />
<br />
=== ControlType variable ===<br />
<br />
With '''ControlType''' set to '''variable''', the contents of a Luup variable are displayed at the specified coordinates. The following additional keys must also be provided: <br />
<br />
;'''Display''' <br />
:A JSON object with six keys: '''Top''', '''Left''', '''Width''', '''Height''' (all strings containing numbers, controlling where the variable's value is placed in the tab), '''Service''' (a string containing the Service Id of the variable to be displayed), and '''Variable''' (a string containing the name of the variable to be displayed).<br />
<br />
=== ControlType input ===<br />
<br />
With '''ControlType''' set to '''input''', a text box for the user to type a string is placed in the tab. The following additional keys must also be provided: <br />
<br />
;'''ID''' <br />
:A string which other controls (buttons) will use to refer to the string that the user has typed into this field. <br />
;'''Display''' <br />
:A JSON object with four keys: '''Top''', '''Left''', '''Width''', '''Height''' (all strings containing numbers). This controls where the text box is placed in the tab.<br />
<br />
=== ControlType button ===<br />
<br />
With '''ControlType''' set to '''button''', a clickable button is placed at the specified coordinates. The button will appear selected (depressed) or unselected based on the value of a variable, permitting sets of buttons to act as radio buttons. The following additional keys must also be provided: <br />
<br />
;'''Label''' <br />
:A JSON object with two keys: '''lang_tag''' is not displayed but can be used by localizing interfaces to translate the label text. '''text''' is displayed as the text inside the button. <br />
;'''Display''' <br />
:A JSON object with up to seven keys: '''Top''', '''Left''', '''Width''', '''Height''' (all strings containing numbers, controlling where the button is placed in the tab), '''Service''' (a string containing the Service Id of a variable), and '''Variable''' (a string containing the name of a variable), and (optionally) '''Value''' (a string, "1" if omitted). The specified variable's value controls whether the button appears selected (if the variable matches '''Value''') or not selected (if the variable doesn't match). <br />
;'''Command''' <br />
:A JSON object with three keys: '''Service''' (a string containing the service Id of an action that this device can perform), '''Action''' (a string containing the name of the action), and '''Parameters''' (a JSON array of JSON objects, forming the parameters to pass to the action). Each parameter object has a key '''Name''' for the parameter name, and either a key '''Value''' (for a fixed parameter value) or a key '''ID''' matching an input control on the page (for a user-entered parameter value).<br />
<br />
=== ControlType slider ===<br />
<br />
With '''ControlType''' set to '''slider''', a draggable slider is placed at the specified coordinates. The following additional keys must also be provided: <br />
<br />
;'''Display''' <br />
:A JSON object with nine keys: '''Top''', '''Left''', '''Width''', '''Height''' (all strings containing numbers, controlling where the button is placed in the tab), '''Service''' (a string containing the Service Id of a variable), and '''Variable''' (a string containing the name of a variable), '''MinValue''' and '''MaxValue''' (both strings containing numbers, controlling what range of values the slider takes) and '''ID''' (a string, used in the '''Command''' to refer to the position the user has dragged the slider to). The specified variable's value is used to display the slider's current position. <br />
;'''Command''' <br />
:A JSON object with three keys: '''Service''' (a string containing the service Id of an action that this device can perform), '''Action''' (a string containing the name of the action), and '''Parameters''' (a JSON array of JSON objects, forming the parameters to pass to the action). Each parameter object has a key '''Name''' for the parameter name, and either a key '''Value''' (for a fixed parameter value) or a key '''ID''' matching the slider's ID (for a value matching what the user has dragged the slider to). <br />
;'''ControlHeader''' <br />
:Optional. If present, must have string value "1". When set, the slider's label and value are displayed. Otherwise only the slider is shown. (TODO: This is from reverse-engineering the JavaScript code. Test this.)<br />
<br />
=== ControlType slider_vertical ===<br />
<br />
:Used in: D_Heater1.json, D_HVAC_ZoneThermostat1.json<br />
<br />
=== ControlType checkbox ===<br />
<br />
:As of UI5 firmware 1.5.622, checkboxes are only half-baked and not usable in "flash" style tabs. If you need check-boxes, radio buttons, pop-up menus, etc. in your tab, you need to create a Javascript tab.<br />
<br />
=== ControlType image ===<br />
<br />
:Used in: D_DigitalSecurityCamera1.json<br />
<br />
=== ControlType image_player ===<br />
<br />
:Used in: D_DigitalSecurityCamera1.json<br />
<br />
=== ControlType js_button ===<br />
<br />
:Used in: D_DigitalSecurityCamera1.json<br />
<br />
= Dashboard appearance =<br />
<br />
The first array element in the '''Tabs''' field is special. If it is of type '''flash''' then a subset of the controls on the tab can be chosen to display on the UI4 dashboard.<br />
<br />
== Control Groups ==<br />
<br />
The dashboard box for a device has room for two rows of information and controls. These are called ''Control Groups''.<br />
<br />
The tab object must contain the key '''ControlGroup''', which specifies how the dashboard's two available rows of information are to be handled. '''ControlGroup''' is a JSON array containing JSON objects (associative arrays). Each object has the following keys:<br />
<br />
;'''id''' <br />
:A string containing a number, "1" for the first object, "2" for the second, and so on. <br />
;'''isSingle''' <br />
:UI4: If this key is present and contains the value "1", then this control group is combined with other control groups that have '''isSingle''' similarly set onto the same row. For an example of this, see the On/Off buttons of the Binary Switch and Dimmable Switch static JSON files. <br />
:UI5: Since controls cannot be grouped in drop-down lists anymore, this tag has a different role in UI5. When isSingle is "1", the buttons in the ControlGroup will have a background (e.g. the BinaryLight buttons). If isSingle is missing, the buttons won't have a background. That is the button shape is not shown; only the button text will show. <br />
;'''type''' <br />
:If this key is present and contains the value "info", then the controls displayed on this row are not clickable. If this key is absent, buttons may be used in the control group.<br />
<br />
== Making a control appear on the dashboard ==<br />
<br />
All control types (label, variable, button, input, slider) can appear in the dashboard. However, by default, controls in the first tab's detail view do not appear in the dashboard. To make a control's text appear in the dashboard, add a '''ControlGroup''' to the control's JSON object. The value is a string containing a number, matching the '''id''' of one of the Tab's overall '''ControlGroup''' key. The dashboard will concatenate all of a control group's controls in the order they are presented in the '''Control''' array, and display them in a single row of text. <br />
<br />
== Keeping controls together ==<br />
<br />
Some controls may not make sense if presented individually (for instance, an input for an alarm PIN and a "disarm" button). To keep these controls together, add a '''ControlPair''' key to all of the controls that have to appear together. Use the same value (a number in a string) for all of them. <br />
<br />
[[Category:Development]]<br />
<br />
= UI7 Updates =<br />
<br />
;'''TopNavigationTab''' = '''top_navigation_tab'''<br />
: used to place a tab either in the top part or in the bottom of Cpannel. See [[Cpanel Top Navigation Tab]].<br />
;'''"ControlType": "multi_state_button"'''<br />
: This is a new type of control in UI7 and works as a “toggle” button. It is used for On/Off, Armed/Disarmed etc buttons. See [[ControlType multi_state_button]]<br />
;'''default_icon'''<br />
: replace the old "flashicon" from UI5. See [[Luup plugin icons]]<br />
;'''state_icons'''<br />
: state_icons mechanism has changed in UI7. Please see [[Luup plugin icons]]</div>Andreimioshttp://wiki.mios.com/index.php/House_ModesHouse Modes2014-09-02T09:22:44Z<p>Andreimios: </p>
<hr />
<div><br />
==“Mode” top level attribute==<br />
<br />
{| class="wikitable"<br />
|-<br />
! Mode value<br />
! House Mode<br />
|-<br />
|1<br />
|Home<br />
|-<br />
|2<br />
|Away<br />
|-<br />
|3<br />
|Night<br />
|-<br />
|4<br />
|Vacation<br />
|-<br />
|}<br />
<br />
<br />
=== Get “Mode” variable value ===<br />
http://IP/data_request?id=variableget&Variable=Mode<br />
=== Set “Mode” variable value ===<br />
- luup.call_action("urn:micasaverde-com:serviceId:HomeAutomationGateway1","SetHouseMode", {Mode = value}, 0)<br><br />
- http://IP/port_3480/data_request?id=lu_action&serviceId=urn:micasaverde-com:serviceId:HomeAutomationGateway1&action=SetHouseMode&Mode=value<br />
{| style="border: 1px solid #000; border-collapse: collapse"<br />
! style="border: 1px solid #000; width: 150px" rowspan="2" | Action<br />
! style="border: 1px solid #000" colspan="2" | Arguments<br />
! style="border: 1px solid #000" rowspan="2" | Description<br />
|-<br />
! style="border: 1px solid #000; width: 130px" | Name<br />
! style="border: 1px solid #000; width: 140px" | Type or Related Variable<br />
|-<br />
| style="border: 1px solid #000" rowspan="1" | SetHouseMode<br />
| style="border: 1px solid #000" | Mode<br />
| style="border: 1px solid #000" | ui1<br />
| style="border: 1px solid #000" rowspan="1" | Change House Mode<br />
|}<br />
<br />
<br />
== “ModeSetting” top level attribute – default/custom setting for each mode ==<br />
<br />
'''Default values:'''<br><br />
- “!1:DC;2:DC*;3:DC*;4:DC* ” - user didn't configured preset modes yet; info message on dashboard is displayed;<br><br />
- “1:DC;2:DC*;3:DC*;4:DC*” - user visited the preset mode page or configured the modes; info message on dashboard is not displayed;<br><br />
'''Legend :''' <br><br />
- “DC*” - corresponding mode have the default values;<br><br />
- “C*” - corresponding mode have custom values;<br><br />
<br />
''Get ModeSetting value'' : http://IP:3480/data_request?id=variableget&Variable=ModeSetting<br><br />
''Set ModeSetting value'' : http://IP:3480/data_request?id=variableset&Variable=ModeSetting&Value=value<br><br />
<br />
<br />
== “ModeSetting” device state variable ==<br />
<br />
<br />
=== “Choose sensors to arm ” section - all the devices with category 4 ( DEVICE_CATEGORY_SECURITY_SENSOR) ===<br />
- if this variable is blank or doesn't exist it means the device isn't configured yet. Once the device is configured, the variable will be set;<br><br />
- if “A” is present it means that the sensor is “Armed”;<br><br />
- if no value is present it means that the sensor is “Disarmed/Bypassed”. <br><br />
<br />
Example :<br> <br />
“1:;2:A;3:A;4:A”<br><br />
- in “Home” mode the sensor is Disarmed/Bypassed;<br><br />
- in “Away/Night/Vacation” modes the sensor is Armed; <br><br />
<br />
<br />
=== “What to do if an armed sensor trips ? ” section - DEVICE_CATEGORY_SIREN & DEVICE_CATEGORY_SIREN ===<br />
<br />
The syntax used here is the same as for sensors<br />
<br />
<br />
=== “Who should be notified ?” section - look at the top level mode settings tag, like this: “1:D;2:DC*;3:DC*;4:DC*” ===<br />
<br />
- if the “C” is present, it means “yes” <br><br />
- if the “*” is present, it means that all users will be notify. By default, all users are “yes” in all modes except “Home”. <br><br />
- if notification for an individual user is changed, then the “*” is changed to a comma separated list of the PK_Users that are set to “yes”. For example, if the PK_User=1818 is turned to “yes” for mode “Away/2” : “1:D;2:DC,1818;3:DC*;4:DC*”. If PK_User 1819 is added with “yes” also, then it will look like this: “1:D;2:DC,1818,1819;3:DC*;4:DC*”and so on; <br><br />
<br />
<br />
=== “What to do when this mode is selected ?” section ===<br />
<br />
<br />
==== DEVICE_CATEGORY_HVAC ====<br />
<br />
No change = nothing; <br><br />
“Off” = O; <br><br />
“Heat” = H; <br><br />
“Cool” = C; <br><br />
“Auto” = A; v<br />
“,VALUE” = temperature; <br><br />
Example : <br><br />
“1:;2:H,72;3:C,73;4:A,74” - “no change” for mode #1, and the other three are heat, cool, auto.<br />
<br />
==== DEVICE_CATEGORY_DOOR_LOCK ====<br />
<br />
No Change = nothing;<br><br />
“Lock” = L;<br><br />
“Unlock” = U.<br><br />
Example : “1:;2:L;3:U;4:” - “no change” for mode #1 and #4, #2 - “Lock” and #3 - “Unlocked”<br />
<br />
<br />
==== DEVICE_CATEGORY_SWITCH & DEVICE_CATEGORY_DIMMABLE_LIGHT ====<br />
<br />
No Change = nothing;<br><br />
“On” = N;<br><br />
“Off” = F.<br><br />
Example : “1:;2:N;3:F;4:” - “no change” for mode #1 and #4, #2 - “On” and #3 - “Off”<br />
<br />
<br />
== Default modes ==<br />
<br />
DEVICE_CATEGORY_SECURITY_SENSOR (4)<br><br />
: DEVICE_SUBCATEGORY_GLASS (6) 1:A;2:A;3:A;4:A<br><br />
: DEVICE_SUBCATEGORY_SMOKE (4) 1:A;2:A;3:A;4:A<br><br />
: DEVICE_SUBCATEGORY_CO (5) 1:A;2:A;3:A;4:A<br><br />
: DEVICE_SUBCATEGORY_DOOR (1) 1:;2:A;3:A;4:A<br><br />
: Other 1:;2:A;3:;4:A<br><br />
DEVICE_CATEGORY_SIREN (24) 1:;2:A;3:A;4:A<br><br />
DEVICE_CATEGORY_CAMERA (6) 1:;2:A;3:A;4:A<br><br />
DEVICE_CATEGORY_HVAC (5) 1:;2:;3:;4:<br><br />
DEVICE_CATEGORY_DOOR_LOCK (7) 1:;2:;3:;4:<br><br />
DEVICE_CATEGORY_SWITCH (3) 1:;2:;3:;4:<br><br />
DEVICE_CATEGORY_DIMMABLE_LIGHT (2) 1:;2:;3:;4:<br></div>Andreimioshttp://wiki.mios.com/index.php/House_ModesHouse Modes2014-09-02T09:20:28Z<p>Andreimios: </p>
<hr />
<div><br />
==1. “Mode” top level attribute==<br />
<br />
{| class="wikitable"<br />
|-<br />
! Mode value<br />
! House Mode<br />
|-<br />
|1<br />
|Home<br />
|-<br />
|2<br />
|Away<br />
|-<br />
|3<br />
|Night<br />
|-<br />
|4<br />
|Vacation<br />
|-<br />
|}<br />
<br />
<br />
=== 1.1 Get “Mode” variable value ===<br />
http://IP/data_request?id=variableget&Variable=Mode<br />
=== 1.2 Set “Mode” variable value ===<br />
- luup.call_action("urn:micasaverde-com:serviceId:HomeAutomationGateway1","SetHouseMode", {Mode = value}, 0)<br><br />
- http://IP/port_3480/data_request?id=lu_action&serviceId=urn:micasaverde-com:serviceId:HomeAutomationGateway1&action=SetHouseMode&Mode=value<br />
{| style="border: 1px solid #000; border-collapse: collapse"<br />
! style="border: 1px solid #000; width: 150px" rowspan="2" | Action<br />
! style="border: 1px solid #000" colspan="2" | Arguments<br />
! style="border: 1px solid #000" rowspan="2" | Description<br />
|-<br />
! style="border: 1px solid #000; width: 130px" | Name<br />
! style="border: 1px solid #000; width: 140px" | Type or Related Variable<br />
|-<br />
| style="border: 1px solid #000" rowspan="1" | SetHouseMode<br />
| style="border: 1px solid #000" | Mode<br />
| style="border: 1px solid #000" | ui1<br />
| style="border: 1px solid #000" rowspan="1" | Change House Mode<br />
|}<br />
<br />
<br />
== 2. “ModeSetting” top level attribute – default/custom setting for each mode ==<br />
<br />
'''Default values:'''<br><br />
- “!1:DC;2:DC*;3:DC*;4:DC* ” - user didn't configured preset modes yet; info message on dashboard is displayed;<br><br />
- “1:DC;2:DC*;3:DC*;4:DC*” - user visited the preset mode page or configured the modes; info message on dashboard is not displayed;<br><br />
'''Legend :''' <br><br />
- “DC*” - corresponding mode have the default values;<br><br />
- “C*” - corresponding mode have custom values;<br><br />
<br />
''Get ModeSetting value'' : http://IP:3480/data_request?id=variableget&Variable=ModeSetting<br><br />
''Set ModeSetting value'' : http://IP:3480/data_request?id=variableset&Variable=ModeSetting&Value=value<br><br />
<br />
<br />
== 3. “ModeSetting” device state variable ==<br />
<br />
<br />
=== 3.1 “Choose sensors to arm ” section - all the devices with category 4 ( DEVICE_CATEGORY_SECURITY_SENSOR) ===<br />
- if this variable is blank or doesn't exist it means the device isn't configured yet. Once the device is configured, the variable will be set;<br><br />
- if “A” is present it means that the sensor is “Armed”;<br><br />
- if no value is present it means that the sensor is “Disarmed/Bypassed”. <br><br />
<br />
Example :<br> <br />
“1:;2:A;3:A;4:A”<br><br />
- in “Home” mode the sensor is Disarmed/Bypassed;<br><br />
- in “Away/Night/Vacation” modes the sensor is Armed; <br><br />
<br />
<br />
=== 3.2 “What to do if an armed sensor trips ? ” section - DEVICE_CATEGORY_SIREN & DEVICE_CATEGORY_SIREN ===<br />
<br />
The syntax used here is the same as for sensors<br />
<br />
<br />
=== 3.3 “Who should be notified ?” section - look at the top level mode settings tag, like this: “1:D;2:DC*;3:DC*;4:DC*” ===<br />
<br />
- if the “C” is present, it means “yes” <br><br />
- if the “*” is present, it means that all users will be notify. By default, all users are “yes” in all modes except “Home”. <br><br />
- if notification for an individual user is changed, then the “*” is changed to a comma separated list of the PK_Users that are set to “yes”. For example, if the PK_User=1818 is turned to “yes” for mode “Away/2” : “1:D;2:DC,1818;3:DC*;4:DC*”. If PK_User 1819 is added with “yes” also, then it will look like this: “1:D;2:DC,1818,1819;3:DC*;4:DC*”and so on; <br><br />
<br />
<br />
=== 3.4 “What to do when this mode is selected ?” section ===<br />
<br />
<br />
==== 3.4.1 DEVICE_CATEGORY_HVAC ====<br />
<br />
No change = nothing; <br><br />
“Off” = O; <br><br />
“Heat” = H; <br><br />
“Cool” = C; <br><br />
“Auto” = A; v<br />
“,VALUE” = temperature; <br><br />
Example : <br><br />
“1:;2:H,72;3:C,73;4:A,74” - “no change” for mode #1, and the other three are heat, cool, auto.<br />
<br />
==== 3.4.2 DEVICE_CATEGORY_DOOR_LOCK ====<br />
<br />
No Change = nothing;<br><br />
“Lock” = L;<br><br />
“Unlock” = U.<br><br />
Example : “1:;2:L;3:U;4:” - “no change” for mode #1 and #4, #2 - “Lock” and #3 - “Unlocked”<br />
<br />
<br />
==== 3.4.3 DEVICE_CATEGORY_SWITCH & DEVICE_CATEGORY_DIMMABLE_LIGHT ====<br />
<br />
No Change = nothing;<br><br />
“On” = N;<br><br />
“Off” = F.<br><br />
Example : “1:;2:N;3:F;4:” - “no change” for mode #1 and #4, #2 - “On” and #3 - “Off”<br />
<br />
<br />
== 4. Default modes ==<br />
<br />
DEVICE_CATEGORY_SECURITY_SENSOR (4)<br><br />
: DEVICE_SUBCATEGORY_GLASS (6) 1:A;2:A;3:A;4:A<br><br />
: DEVICE_SUBCATEGORY_SMOKE (4) 1:A;2:A;3:A;4:A<br><br />
: DEVICE_SUBCATEGORY_CO (5) 1:A;2:A;3:A;4:A<br><br />
: DEVICE_SUBCATEGORY_DOOR (1) 1:;2:A;3:A;4:A<br><br />
: Other 1:;2:A;3:;4:A<br><br />
DEVICE_CATEGORY_SIREN (24) 1:;2:A;3:A;4:A<br><br />
DEVICE_CATEGORY_CAMERA (6) 1:;2:A;3:A;4:A<br><br />
DEVICE_CATEGORY_HVAC (5) 1:;2:;3:;4:<br><br />
DEVICE_CATEGORY_DOOR_LOCK (7) 1:;2:;3:;4:<br><br />
DEVICE_CATEGORY_SWITCH (3) 1:;2:;3:;4:<br><br />
DEVICE_CATEGORY_DIMMABLE_LIGHT (2) 1:;2:;3:;4:<br></div>Andreimios