Premise HTTP_API. Connect Premise to The Home Remote.

[123]

In this thread, a fresh new face for Premise, I described a means of opening up Premise to The Home Remote (THR). THR lets you create a user-interface (for almost anything) that'll run on iOS, Android, and Windows devices. Here's a sample from The Home Remote's web-site (Android):
 

 
 
To achieve this goal, and make the process practical, two things are needed:
 
1) STATUS REQUEST: Premise delivers current status of all device properties.
Upon request, via HTTP, Premise must reply with a list of all its devices (non-hidden devices in Premise Home) and their respective property values. With the notable exception of MediaZones (and KeyPads), this work is finished. Upon demand, Premise can rapidly generate this information in XML format.
 
2) EXPORT: Premise exports all devices in Home Remote format.
A typical Premise Home contains many devices where each one has several properties. A complete list of all device properties can contain over a hundred items. Typing this information into Home Remote's Designer is impractical. Premise must be able to export all properties into a format that can be imported into Home Remote. This feature has been completed.

The attached Module (HTTP_API) implements the two functions: Status Request and Export. After importing it into Premise Builder, go to Devices > CustomDevices and create a new "API" device. Don’t change its name.
 
Now the following URL will make your Premise Server respond with the status of every non-hidden device in your Premise Home. The notable exception is MediaZone (I don't have enough experience with this complicated device to handle it properly).
 

http://ServerName/sys/devices/customdevices/api?d??Status 
 
Here’s a sample of the status response. You probably won't see it in a browser. It’s XML but Premise’s HTTP header says ContentType=text/html (I can't change that). There’s a mismatch between the ContentType (text/html) and what is actually delivered (text/xml) so the browser shows … nothing.
 

<?xml version="1.0" encoding="UTF-8"?>
<PremiseHome>
<Scene>
<SC ID="{D2C19ADC-C7DC-4F45-9CCD-BC08BF0B6FC0}" N="Wakeup" PLY="0" />
<SC ID="{BACFBB26-D0CF-4634-9872-EC143AE4295B}" N="Evening" PLY="-1" />
</Scene>
<Lighting>
<L ID="{8B37F62F-6DAF-457F-BACC-B8CFBCEE757B}" N="PorchLight" PS="-1" B="1" />
<L ID="{A0EF7479-CF71-4909-894E-51D727E53A8F}" N="MantleLight" PS="-1" B="0.4" />
<L ID="{1C4D7AD0-EE42-4859-AD3F-7C1B572FA96D}" N="KitchenLight" PS="0" B="0" />
<L ID="{6187C1CD-AB19-4DF5-9F9D-3575751D4075}" N="SinkLight" PS="-1" B="0.35" />
</Lighting>
<HVAC>
<HV ID="{24644D9D-C617-40BE-A4EA-1BD8019B2CF7}" N="FoyerLightSensor" LI="26" />
<HV ID="{D190AD1E-BE6B-4AC2-9CA2-9EA21157D618}" N="Thermostat" HSP="21" CSP="25.5" CURSP="21" UH="-1" OT="-1.23" T="21.5" FC="0" FS="0" TM="1" HS="4" THM="2" />
</HVAC>
<Appliance>
<A ID="{61CA95CD-808C-47C7-88B5-AD49A9836022}" N="Pump" PS="0" />
<A ID="{C0157699-FE6F-4F5F-ABFB-A8034C0253E9}" N="Fountain" PS="0" />
<A ID="{3366BCF0-082F-4B9C-89BB-EE7C97E86848}" N="LowerWestLawn" ST="0" />
</Appliance>
<Security>
<SE ID="{B1BD90B6-F0F2-43FF-A662-1F9A70BC3697}" N="Sensor" DO="0" />
<SE ID="{F688F519-3280-4EC2-A8EE-0A802CA64413}" N="Sensor" GDO="0" />
<SE ID="{EFC474F7-C836-4FDA-9791-3A21F237881E}" N="SecuritySystem" SST="1" SRDY="-1" STAY="0" EXIT="0" DARM="0" DCODE="" PFIRE="0" PMED="0" PPOL="0" LSTCH="Ready To Arm, 3/07/2018 10:04:52 PM" LZTR="Front_Door (1)" LFUN="ExitArm, 3/07/2018 4:20:52 PM" SLFUN="Disarmed, 3/07/2018 10:04:52 PM"/>
<SE ID="{87D778F4-F10B-4DAD-97FD-A59C8C907DC8}" N="RearDoor" TR="0" />
<SE ID="{AAC5A30B-B302-40CD-8992-1959004FFF12}" N="MainGlassBreak" TR="0" />
<SE ID="{4675277A-9DCE-4ED1-BB43-646A0CBAD32B}" N="BasementMotion" TR="0" />
</Security>
</PremiseHome>

 
The URL is used by Home Remote to poll your Premise Server (every second or two). Premise's status response is used to keep Home Remote's UI up to date. For that matter, the status response can be used by other external software, not just Home Remote.

Here's how to export devices in Premise Home into a format compatible with Home Remote's Designer (i.e. the software for creating user-interfaces). In Premise Builder, navigate to Devices > CustomDevices > API.
 

1. First, set Temperature Unit to Fahrenheit. As you know, Premise defaults to using Kelvin. Converting temperatures in Home Remote is a bit of a bother so it’s easier to make Premise deliver them in the preferred units.
2. If you have Debugview running on your Premise Server, set the Module’s Debug Level to Errors. Should the Module encounter an object it cannot process, it’ll report it in Debugview. An example of something it cannot process is a custom Module that inherits from Lighting, Appliance, Security, etc. For example, I have DoorbellMonitor and CallMonitor (they inherit from the Appliance class) and HTTP_API reports that it cannot process them. Naturally, HTTP_API can be modified to support any custom class .
3. Confirm Hostname, Export Path, and Export File Name are correct. Don’t forget that the export path is on the server, not the client!
4. Refresh Rate is the status polling interval (in milliseconds) performed by Home Remote. The default is 2000 (2 seconds). Set it to whatever you wish but the Module will reject values shorter than 500 milliseconds.
5. Click Export. An Event message will popup in Builder indicating if the operation was a success or if there was an error.
6. If successful, there’ll be a Devices.xml file in the folder specified by Export Path. Make a copy of this file.

 
Now for the fun part. Home Remote’s file extension is ".hrp". It’s nothing more than a zip file. You’re going to use Designer to create a nearly-empty .hrp file to serve as a template. It’ll contain a Devices.xml file that you will overwrite with the one produced by the Module. Here goes:
 

1. Start Home Remote Designer and create a new project file.
2. Configure it for iOS or Android or Windows. At this point, it doesn’t matter which one.
3. Add an HttpClient Device. Don’t bother configuring it. It’ll get overwritten later.
4. Save the project file with whatever name you wish (say, test1.hrp) and exit Designer.
5. Using Windows File Manager, rename test1.hrp to test1.zip.
6. Open the zip archive and you’ll see it contains three XML files and some folders. One of those XML files is called Devices.xml and you must replace it with the version the Module created. Just copy the Module’s Devices.xml file and paste it into the zip archive. Allow it to overwrite the existing file.
7. Rename test1.zip back to test1.hrp.
8. Now open test1.hrp and Designer will have a new HttpClient called “Premise.Home” containing HttpVariables for all your Premise objects.

 
That’s a lot faster than manually typing them into Designer! Premise's "Large Home" example contains hundreds of properties and here's what one of them looks like in Home Remote's Designer.
 

 
The other file I attached (PremiseDevices.zip) is something I created to help me build this Module. It’s an XML “cheat sheet" listing Premise devices, their properties, types, and the classes they inherit from. You may find it handy when building a UI in Designer. For example, a Thermostat’s TemperatureMode property is a MultiValue but what are its available values? The cheat sheet lists them. Sure, you can ctrl-click your way through Builder to hunt them down to the “ClimateSetting” enumeration … but it’s faster with the cheat sheet.
 

 

[chucklyons]

I have yet to get the export to work. I don't get a popup, or any message. Tried it in normal mode (client), remoted in to the server and did it locally. Any ideas what I'm missing this time (as I have been prone to do...)

Oddly enough, I was able to get the Devices.xml created. I'll have to walk thru the steps a few times to see what is going on (although I didn't get the popup).

Once I get it installed on HR, I'll give an update..

 

[123]

In Premise Builder check: Tools > Configuration > Session > EventPrompting
 
If it's disabled, as I suspect it is, you won't see a popup message when there's an Event.
 
I didn't consider the possibility this option might be disabled. No worries. I use it purely for notifying the end-user that the export process has completed.  If you go to Monitor > Events you'll see a record of all the times you used the Export function to create Devices.xml.
 
 

 

[chucklyons]

unnnhhhh. Thanks for playing!!! Nope, I had it set. Bizarrely, I did another export, and had the SUCCESS event popup!! BTW, when I looked at events under "Monitor". each event was there for each export that I had previously done.
 
In all fairness, my Surface died and I have had to go thru and setup permissions between it and my Premise server, etc. What a PITA!