UI Simple - Revision history

Futzle at 22:00, 27 August 2013

2013-08-27T22:00:27Z

Micasaverde at 20:52, 5 September 2012

2012-09-05T20:52:11Z

Mcvdaniel at 20:19, 16 May 2012

2012-05-16T20:19:56Z

Show changes

Micasaverde: /* Status of the device or scene and control buttons */

2012-01-25T15:10:04Z

‎Status of the device or scene and control buttons

Mcvflorin: /* Testing everything on a public MiOS engine */

2012-01-18T13:34:21Z

‎Testing everything on a public MiOS engine

Micasaverde at 04:48, 6 September 2010

2010-09-06T04:48:52Z

Ap15e: /* lu_sdata: The polling loop */

2010-08-30T14:01:59Z

‎lu_sdata: The polling loop

Ap15e: /* lu_sdata: The polling loop */

2010-08-30T13:59:49Z

‎lu_sdata: The polling loop

Micasaverde at 22:47, 23 August 2010

2010-08-23T22:47:46Z

Micasaverde at 22:45, 23 August 2010

2010-08-23T22:45:14Z

@@ Line 34: / Line 34: @@
 When the user clicks 'go' attempt to the open this url: http://ip:3480/data_request?id=lu_alive (substitute the actual IP), and if you get back an "OK" in the response, store the IP address in your controller locally (ie a conf file, registry, etc) and continue to the next step. If you don't get an OK, display an error and go back.
-If the user supplied a mios.com username, open this URL: http://sta1.mios.com/locator_json.php?username=user (substitute 'user' for the actual username). This will return a list of all the engines you can control, both with method #1 and with method #2, meaning you will see both engines on the local network which may or may not be tied to the user's mios.com account, and you will see engines tied to the mios.com account which may or may not be on the local network. As with most of the requests, the returned data is in JSON format. The data you get back is not formatted with new lines and spaces. If you want to be more human readable for debugging, copy/paste the results into http://jsonlint.com and it will format it nicely. The controller needs to have a json library so it can parse the json responses. The data you get back will be like this:
+If the user supplied a mios.com username, open this URL: https://sta1.mios.com/locator_json.php?username=user (substitute 'user' for the actual username). This will return a list of all the engines you can control, both with method #1 and with method #2, meaning you will see both engines on the local network which may or may not be tied to the user's mios.com account, and you will see engines tied to the mios.com account which may or may not be on the local network. As with most of the requests, the returned data is in JSON format. The data you get back is not formatted with new lines and spaces. If you want to be more human readable for debugging, copy/paste the results into http://jsonlint.com and it will format it nicely. The controller needs to have a json library so it can parse the json responses. The data you get back will be like this:
      "units": [

@@ Line 353: / Line 353: @@
 CATEGORY #6 - Camera: These don't have a status. The control button is marked 'VIEW', but it doesn't send an action. It just displays an image viewer on the controller. The viewer should have a large JPEG image which you get by calling: http://ip:3480/data_request?id=cam_image&amp;Device_Num=x where x is the device ID. This request returns a JPEG file. If the camera also has a status 'streaming' and the status is not empty, the the image viewer popup should display a 'LIVE VIDEO' button, which displays the streaming video instead. See the [[Remote Camera Streaming]] to learn how. Both the JPEG image viewer and the motion image viewer must have buttons for the user to control the pan/tilt/zoom of the camera. These buttons are L, R, U, D, +, - (for left, right, up, down, zoom in, zoom out). When those buttons are pressed, use the lu_action with the service "urn:micasaverde-com:serviceId:PanTiltZoom1" and the action "MoveLeft", "MoveRight", "MoveUp", "MoveDown", "ZoomIn" or "ZoomOut". There are no arguments for those actions.
-CATEGORY #7 - Door lock: 'status' is 0 for locked or 1 for unlocked. Display a 'lock' and 'unlock' button which are bound to the 'status' variable. If selected, use the service "urn:micasaverde-com:serviceId:DoorLock1" action "SetTarget" and value newTargetValue which is 0 for unlocked and 1 for locked.
+CATEGORY #7 - Door lock: 'status' is 1 for locked or 0 for unlocked. Display a 'lock' and 'unlock' button which are bound to the 'status' variable. If selected, use the service "urn:micasaverde-com:serviceId:DoorLock1" action "SetTarget" and value newTargetValue which is 0 for unlocked and 1 for locked.
 CATEGORY #8 - Window covering: same as Dimmable Light.

@@ Line 334: / Line 334: @@
 When the user selects a control button for a device or scene, you will use lu_action to tell the engine what to do.  In all cases you will get back either an OK or a JobID inside a response tag.  If you don't, you will get back an error message which you should pass to the user.  If you don't get anything back, retry the lu_action once every 2 seconds for up to 30 seconds, displaying an hour glass or busy indicator while you do, and, if, after 30 seconds you still cannot get a response to lu_action, report to the user that you lost contact with the engine.  It is normal for lu_action to fail if the engine is reloading.  So, for example, if the user clicks 'Lock' and you get back the error message "Lock operation is not available", then display a popup message in the user interface with an 'ERROR' icon and display the message "Lock operation is not available" with an 'OK' button.  On the other hand if you do not get any response at all to lu_action, or get an html error, just keep retrying over and over until you either get a response or timeout.
-You will always pass a 'service', an 'action', and optionally arguments on lu_action.  So you should have a common function, like SendAction(string service, string action, string arguments), which has the logic of sending the command to the engine.
+You will always pass a 'service', an 'action', and optionally arguments on lu_action.  So you should have a common function, like SendAction(string service, string action, string arguments), which has the logic of sending the command to the engine.  To determine what service, action and arguments to use, you can 1) log in with ssh, the root password is the wi-fi password printed on the bottom, and type: ''tail -f /var/log/cmh/LuaUPnP.log | grep ^08'' and then control the device through the web UI.  You will see in the console all the service/action/arguments for the commands you're sending.  2) You can also call the data_request lu_invoke, like ''http://__IP__:3480/data_request?id=invoke'' which has a human-readable list of devices and when you click them it shows you the service/action/arguments available.  3) If you understand UPNP terminology, you can go in the Web UI to Apps, Develop Apps, Luup files, and retrieve the actual UPNP XML files.  The device files start with D_, and when you click the settings for a device in the web UI, you will see the name of the UPNP device file it uses.
 When the user selects a control button, do not automatically show that button highlighted.  For example, if a light is 'off' and the user selects 'on', give the user feedback with the 'on' button so he knows his selection was recognized, but do not automatically switch which button is highlighted.  The background poll loop will get back a new 'status' for the device when the engine has completed turning off the light.  As soon as you send the command with lu_action, the polling loop should immediately return and the state for the device or scene will change to 'PENDING'.  This means the user should see the 'blue' busy indicator so he knows the engine is busy controlling the device.  When the engine has succeeded in setting the device, the state will change to 'SUCCESS' and the status variable(s) will be changed, and that will cause the UI to re-render the control showing the new status.

@@ Line 368: / Line 368: @@
 Note: All devices, regardless of category, will have a 'watts' tag if we can measure the current consumption.
-== Testing everything on a public MiOS engine ==
+== Testing everything on a public MiOS engine  ==
-A MiOS engine is available on the internet with a static IP so you can use it to test your user interface both in local mode, as well as remote mode.  The IP is demo.mios.com (76.168.224.30).  So to test your application in local mode, just use that IP and you will talk to it as though it were on the local network.  The port 3480 is publicly accessible like a device on the local network would be (see: http://76.168.224.30:3480/data_request?id=lu_sdata).  You can also test it in remote mode with the username demomios password demomios123 and serial number 12082.  So, you can retrieve the same data above with this URL in remote mode: https://fwd2.mios.com/demomios/demomios123/12082/data_request?id=lu_sdata
+'''<span style="color: rgb(255, 0, 0);">NOTE:</span> <span style="color: rgb(255, 0, 0);">demo.mios.com it's not available anymore</span>.'''
-So, as a walkthrough to see how things work, first open up the regular MiOS web-based user interface that comes with the system at: http://demo.mios.com:8080/cmh/ Note that unlike the simple control-only user interface described in this document, this is a full user interface that let's you change configuration and do advanced things.  It uses a different polling mechanism than the simple lu_sdata described here.
+A MiOS engine is available on the internet with a static IP so you can use it to test your user interface both in local mode, as well as remote mode. The IP is demo.mios.com (76.168.224.30). So to test your application in local mode, just use that IP and you will talk to it as though it were on the local network. The port 3480 is publicly accessible like a device on the local network would be (see: http://76.168.224.30:3480/data_request?id=lu_sdata). You can also test it in remote mode with the username demomios password demomios123 and serial number 12082. So, you can retrieve the same data above with this URL in remote mode: https://fwd2.mios.com/demomios/demomios123/12082/data_request?id=lu_sdata
-Now, in another tab, using Firefox, which has a built-in xml parser, open: http://demo.mios.com:3480/data_request?id=lu_sdata&output_format=xml  NOTE: You will not use output_format=xml in your app, it's just to make it easier to see what's going if you have a Firefox browser.
+So, as a walkthrough to see how things work, first open up the regular MiOS web-based user interface that comes with the system at: http://demo.mios.com:8080/cmh/ Note that unlike the simple control-only user interface described in this document, this is a full user interface that let's you change configuration and do advanced things. It uses a different polling mechanism than the simple lu_sdata described here.
-Now, in another tab, open this URL, but substitute the dataversion and loadtime variables from the prior tab: http://demo.mios.com:3480/data_request?id=lu_sdata&output_format=xml&loadtime=1282601808&dataversion=601808034&minimumdelay=3000
+Now, in another tab, using Firefox, which has a built-in xml parser, open: http://demo.mios.com:3480/data_request?id=lu_sdata&amp;output_format=xml NOTE: You will not use output_format=xml in your app, it's just to make it easier to see what's going if you have a Firefox browser.
-You should see that the page waits 3 seconds to load because the minimum delay is a minimum response time.  Then you get an empty page without any data, and the tag full is 0.  This means nothing has changed since the dataversion.  If you change even 1 digit in the loadtime= on the URL, which is a timestamp of the configuration file, then you will get back the full data again because the lu_sdata requests sees that you do not have the current database.
+Now, in another tab, open this URL, but substitute the dataversion and loadtime variables from the prior tab: http://demo.mios.com:3480/data_request?id=lu_sdata&amp;output_format=xml&amp;loadtime=1282601808&amp;dataversion=601808034&amp;minimumdelay=3000
-Now put back the correct loadtime and dataversion and add &timeout=15 to the URL, like this: http://demo.mios.com:3480/data_request?id=lu_sdata&output_format=xml&loadtime=1282601808&dataversion=601808034&minimumdelay=3000&timeout=15
+You should see that the page waits 3 seconds to load because the minimum delay is a minimum response time. Then you get an empty page without any data, and the tag full is 0. This means nothing has changed since the dataversion. If you change even 1 digit in the loadtime= on the URL, which is a timestamp of the configuration file, then you will get back the full data again because the lu_sdata requests sees that you do not have the current database.
-You should see that it now waits 15 seconds, and again returns nothing.  Now change the timeout to 60, and open the page again.  During the next 60 seconds while the page is loading, go back to the MiOS user interface you first opened, and in the room "Patio" turn the 'White Light' on if it's off, or off it's on.  The tab that's blocking on the lu_sdata should immediately return and give you this: <device id="3" status="1" state="1" comment="White Light: Sending the Z-Wave command after 0 retries"/>
+Now put back the correct loadtime and dataversion and add &amp;timeout=15 to the URL, like this: http://demo.mios.com:3480/data_request?id=lu_sdata&amp;output_format=xml&amp;loadtime=1282601808&amp;dataversion=601808034&amp;minimumdelay=3000&amp;timeout=15
-This is what causes your user interface to update device id 3.  The state is now '1', meaning it's pending or busy while the engine is turning on or off the device.  The indicator should appear in blue at this point.  Copy/paste the dataversion from the request back into the URL and request it again.  This time you should see: <device id="3" status="0" state="4" comment=""/>
+You should see that it now waits 15 seconds, and again returns nothing. Now change the timeout to 60, and open the page again. During the next 60 seconds while the page is loading, go back to the MiOS user interface you first opened, and in the room "Patio" turn the 'White Light' on if it's off, or off it's on. The tab that's blocking on the lu_sdata should immediately return and give you this: &lt;device id="3" status="1" state="1" comment="White Light: Sending the Z-Wave command after 0 retries"/&gt;
-The state will be 4 if you do it soon, meaning your user interface should show the device with a green 'success' indicator, and if you do it again in 30 seconds, it will have a state of -1, meaning nothing.
+This is what causes your user interface to update device id 3. The state is now '1', meaning it's pending or busy while the engine is turning on or off the device. The indicator should appear in blue at this point. Copy/paste the dataversion from the request back into the URL and request it again. This time you should see: &lt;device id="3" status="0" state="4" comment=""/&gt;
-To turn the device like your user interface will, open this:
+The state will be 4 if you do it soon, meaning your user interface should show the device with a green 'success' indicator, and if you do it again in 30 seconds, it will have a state of -1, meaning nothing.
-http://demo.mios.com:3480/data_request?id=lu_action&DeviceNum=3&serviceId=urn:upnp-org:serviceId:SwitchPower1&action=SetTarget&newTargetValue=1
+To turn the device like your user interface will, open this:
-change the =1 to an =0 to turn it off.  Note that the response is a jobID.  This means the engine is asynchronously turning on/off the device.
+http://demo.mios.com:3480/data_request?id=lu_action&amp;DeviceNum=3&amp;serviceId=urn:upnp-org:serviceId:SwitchPower1&amp;action=SetTarget&amp;newTargetValue=1
-Now try to turn on or off device #26, like this:
+change the =1 to an =0 to turn it off. Note that the response is a jobID. This means the engine is asynchronously turning on/off the device.
-http://demo.mios.com:3480/data_request?id=lu_action&DeviceNum=26&serviceId=urn:upnp-org:serviceId:SwitchPower1&action=SetTarget&newTargetValue=0
+Now try to turn on or off device #26, like this:
-You will get back an error "ERROR: No implementation".  In your user interface, this means if the user tries to control device #26, the user should get an error popup dialog box with that error message in it.
+http://demo.mios.com:3480/data_request?id=lu_action&amp;DeviceNum=26&amp;serviceId=urn:upnp-org:serviceId:SwitchPower1&amp;action=SetTarget&amp;newTargetValue=0
-You can test all the controls in your user interface with this demo system since it has all the current device categories.  The devices in the room "Patio" are real devices and will give you proper responses when you try to control them.  All other devices are dummy devices that will return an error if you do anything with them.  The 'White Light' is a functioning light that should go through the pending and success states when you control it.  The red light is a light that is ok, but, every time you try to control it, the job will fail.  So the user should see a blue pending for a while when trying to turn it on or off, which then goes red and stays there for several seconds with an error message, but, after a while, reverts back to a neutral state (-1).  The device 'Bad Light' is in a perpetually bad state and should always appear as red.
+You will get back an error "ERROR: No implementation". In your user interface, this means if the user tries to control device #26, the user should get an error popup dialog box with that error message in it.
-In the patio the scenes 'Light on' and 'Light off' turn the white light on and off.  One or the other scene will be 'active' depending on what state the light is in.
+You can test all the controls in your user interface with this demo system since it has all the current device categories. The devices in the room "Patio" are real devices and will give you proper responses when you try to control them. All other devices are dummy devices that will return an error if you do anything with them. The 'White Light' is a functioning light that should go through the pending and success states when you control it. The red light is a light that is ok, but, every time you try to control it, the job will fail. So the user should see a blue pending for a while when trying to turn it on or off, which then goes red and stays there for several seconds with an error message, but, after a while, reverts back to a neutral state (-1). The device 'Bad Light' is in a perpetually bad state and should always appear as red.
-Please don't try to change the configuration settings on this demo system since it is used by several developers.  If something is messed up on it, email support [at] micasaverde [dot] com and someone will restore it back to the default setting.
+In the patio the scenes 'Light on' and 'Light off' turn the white light on and off. One or the other scene will be 'active' depending on what state the light is in.

← Older revision		Revision as of 04:48, 6 September 2010
Line 1:		Line 1:
	[[Category:Development]]		[[Category:Development]]
		+
		+	NOTE: After reading this document to familiarize yourself with the concepts, see [[UI_Simple_Sample]] which has source code for a free implementation that you can embed within your applications to do all the work.

	MIOS is a lightweight home automation system. The 'brain' of the MIOS software is the back-end, the engine, which runs stand-alone on a variety of internet-connected devices, such as PC's, Mac's, Wi-Fi access points, and dedicated home automation gateways. MIOS also includes a portal at mios.com, which acts as secure relay to MIOS systems that may be behind firewalls. Users can register for an account at mios.com, and that account can be linked to one or more MIOS systems to provide the user remote access to his MIOS system from anywhere. It is easy to control a MIOS system with simple http get's (normal internet requests). The URL you will open is generally data_request?id=xxx, where xxx is some sort of request or control command.		MIOS is a lightweight home automation system. The 'brain' of the MIOS software is the back-end, the engine, which runs stand-alone on a variety of internet-connected devices, such as PC's, Mac's, Wi-Fi access points, and dedicated home automation gateways. MIOS also includes a portal at mios.com, which acts as secure relay to MIOS systems that may be behind firewalls. Users can register for an account at mios.com, and that account can be linked to one or more MIOS systems to provide the user remote access to his MIOS system from anywhere. It is easy to control a MIOS system with simple http get's (normal internet requests). The URL you will open is generally data_request?id=xxx, where xxx is some sort of request or control command.

@@ Line 205: / Line 205: @@
 full="1" loadtime="1282441735" dataversion="441736333" state="-1" comment=""
-full is either 0 or 1, and 1 means lu_sdata has returned the complete list of sections, rooms, devices and scenes.  If full is 0, the lu_sdata is only returning the devices and scenes which have changed since the last request.  On subsequent calls to lu_sdata you will the loadtime and dataversion back on the URL, like this:
+full is either 0 or 1, and 1 means lu_sdata has returned the complete list of sections, rooms, devices and scenes.  If full is 0, the lu_sdata is only returning the devices and scenes which have changed since the last request.  On subsequent calls to lu_sdata you will get the loadtime and dataversion back on the URL, like this:
 http://76.168.224.30:3480/data_request?id=lu_sdata&loadtime=1282441735&dataversion=441736333

← Older revision		Revision as of 22:47, 23 August 2010
Line 401:		Line 401:

	In the patio the scenes 'Light on' and 'Light off' turn the white light on and off. One or the other scene will be 'active' depending on what state the light is in.		In the patio the scenes 'Light on' and 'Light off' turn the white light on and off. One or the other scene will be 'active' depending on what state the light is in.
		+
		+	Please don't try to change the configuration settings on this demo system since it is used by several developers. If something is messed up on it, email support [at] micasaverde [dot] com and someone will restore it back to the default setting.

@@ Line 8: / Line 8: @@
 The user interface has only two screens, or modes: 1) Basic setup which only consists of identifying the engine the user will control, and 2) Normal usage which consists of running scenes (pre-defined groups of commands), and controlling devices.
 == Mode 1: Basic setup and locating the engine ==
@@ Line 98: / Line 100: @@
 units is an array of JSON objects, one representing each engine.  If the tag ipAddress exists for an engine, that means it's available on the local network and can be controlled locally with method #1, otherwise the ipAddress tag will not exist.  The users array is a list of all the mios.com usernames which have access to this engine.  So, if the username you passed on the locator_json.php URL is also in the users array, then the engine can be controlled remotely with the username, using whatever server is listed in the "active_server" tag.  The forwardServers tag lists the primary server for remote access and one or more backups.  If the tag "name" exists, that is a name which the user assigned to his engine.
 The next screen in the UI should say "What MiOS engine do you want to control?" and then display a list of all the engines with both the serialNumber and name if it exists.  You should have 2 icons next to each for 'remote' and 'local' access.  In the above example, assuming the username I passed in is "skyvera" 10516 will have the 'local' icon only, since there are no users, and for 8035 it will also be 'local' only because skyvera is not one of the allowed users.  For 10266 display both the 'remote' and 'local' icon.  At the bottom of the page you can have a legend:
@@ Line 326: / Line 330: @@
 This depends on what category of device you are showing.  The status tags returned by lu_sdata are different for a thermostat, which has status tags like mode, heatsp, coolsp, etc., than for a light switch with has the status tags level and status.  Normally a control button, like the button that turns on a light, if bound to a status so the user can tell by whether the button is highlighted or not if the command is already active.  For example, with a light switch, there is a 'status' tag that is 0 or 1 depending on if it's on or off.  There are also 2 command buttons: on and off.  Those 2 command buttons are bound to the status, meaning that if the status is 0, then the 'off' button should appear highlighted so the user can tell the light is already off.  Each control button is tied to a command, like the 'on' button sends the 'on' command to the device.  You should always send the command even if the command button is already highlighted.  In other words, even if the status of a light is 0 (off) and the off button is already highlighted, when the user selects the off button, send the 'off' command regardless.  You send commands by opening a URL on the engine, just like the poll loop does.  The difference is that to run a command the data_request is generally "lu_action" instead of "lu_sdata".  The engine is multi-threaded and can handle many requests at once.  So you should not interrupt the background polling loop when you want to send a command.  The polling loop will continue to block on the lu_sdata request, and, in parallel, the you will do a lu_action request when the user selects a command button.
-When the user selects a control button for a device or scene, you will use lu_action to tell the engine what to do.  In all cases you will get back either an OK or a JOB.  If you don't, you will get back an error message which you should pass to the user.  If you don't get anything back, retry the lu_action once every 2 seconds for up to 30 seconds, displaying an hour glass or busy indicator while you do, and, if, after 30 seconds you still cannot get a response to lu_action, report to the user that you lost contact with the engine.  It is normal for lu_action to fail if the engine is reloading.  So, for example, if the user clicks 'Lock' and you get back the error message "Lock operation is not available", then display a popup message in the user interface with an 'ERROR' icon and display the message "Lock operation is not available" with an 'OK' button.  On the other hand if you do not get any response at all to lu_action, or get an html error, just keep retrying over and over until you either get a response or timeout.
+When the user selects a control button for a device or scene, you will use lu_action to tell the engine what to do.  In all cases you will get back either an OK or a JobID inside a response tag.  If you don't, you will get back an error message which you should pass to the user.  If you don't get anything back, retry the lu_action once every 2 seconds for up to 30 seconds, displaying an hour glass or busy indicator while you do, and, if, after 30 seconds you still cannot get a response to lu_action, report to the user that you lost contact with the engine.  It is normal for lu_action to fail if the engine is reloading.  So, for example, if the user clicks 'Lock' and you get back the error message "Lock operation is not available", then display a popup message in the user interface with an 'ERROR' icon and display the message "Lock operation is not available" with an 'OK' button.  On the other hand if you do not get any response at all to lu_action, or get an html error, just keep retrying over and over until you either get a response or timeout.
 You will always pass a 'service', an 'action', and optionally arguments on lu_action.  So you should have a common function, like SendAction(string service, string action, string arguments), which has the logic of sending the command to the engine.
@@ Line 361: / Line 365: @@
 Note: All devices, regardless of category, will have a 'watts' tag if we can measure the current consumption.