PowerHome Connector for Android Setup

 

The PowerHome Connector for Android (phca) is an Android application with a great deal of flexibility and configuration that can easily connect you to your PowerHome installation. If you are comfortable writing macros for PowerHome (ph), then you should be able to configure phca to suit your needs. Requirements are ph installed on a computer with the internal webserver or socket server (or both) running. You will also have to have a routable ip address or domain name. This may require the installation of a dynamic dns service on your ph computer. In other words, if you can see the web center for your installation from a computer not located in your house, then you probably know what you are doing and are good to go. You will also have to have a means of uploading a configuration file to your phone. There is no means to create the configuration file from within the phca app. You might be able to pull it off with a text editor on your phone, but I think that would be pretty painful trying to edit a file such as the configuration file for this app.

You can download phca from here. The permissions required for the app are “Storage”, “Network Communications” and “Phone Calls”. As you will soon see, the configuration file for phca is an xml file placed on your sd card. Phca will read and write to other configuration files and databases that will be placed on your sd card, hence the need for the “storage” permission. “Network Communications” is required for the app to communicate with the PowerHome and phc-a.net servers. Phone calls sounds strange, but I assure you it is not anything bad. The app needs to get a unique phone ID and the Android API requires the “Phone Calls” permission to retrieve it. I promise I am not going to make any phone calls or any other nefarious things.

When you do install the app, don’t choose to run it right away because you need to upload a working configuration file. If you just want to get your app up and running, you can read the usage instructions here. Those instructions tell you how to use the app using the sample configuration file. Eventually you will want to edit your own menus in which case you will want to come back here for details.

http://skipstechtalk.net/powerhome-connector-for-android-usage-instructions-and-screenshots/

Each “page” in phca consists of four elements: 1) a unique title; 2) optional status text; 3) optional actions; and 4) optional links to other pages. This will give you plenty of flexibility in setting up your pages. For instance, pages could have similar tasks and status information grouped together for your convenience such as security, home automation, home entertainment, etc. The xml configuration file will give the phca app all the information it will need to generate all of the pages and menus for your installation. Please see the sample file here to get started.

Here’s a link to a complete, working (with the exception of the login information) main_menu_pref.xml file.

<?xml version="1.0" encoding="utf-8"?>
<Preference
  xmlns:android="http://schemas.android.com/apk/res/android" 
  PhWebServer="http://MyPhWebServer:PortNum"
  PhSocketServerAddress="myPhSocketServerFQDN"
  PhSocketServerPort="8500"
  PhWebServerUsername="MyPhWebServerUsername" 
  PhWebServerPassword="MyPhWebServerPassword" 
  PhWebServerAuthMethod="cookie"
  PhSocketServerUsername="MySocketServerUsername" 
  PhSocketServerPassword="MySocketServerPassword"
  version="1.0.0">
  <pages>
    <page
      pagename="mainmenu"
      pagetitle="Main Menu"
      statustext="PowerHome Uptime: %ph_uptime%&#xA;Sunrise today: %sunrise%&#xA;Cloud Push Test: %cloudpushtest%">
      <refresh>
        <update url="ph_powerhomeuptime_s()" variablename="ph_uptime"></update>
        <update url="ph_getsuntime(today(),1)" variablename="sunrise"></update>
      </refresh>
      <actions>
        <action label="Testing (ss)" ss_body="ph_macro('TESTING')" ss_requestType="FORMULA" return_type="dialog"></action>
        <action label="Testing (web)" url="ph_macro('TESTING')" return_type="dialog"></action>
      </actions>
      <pagelinks>
        <pagelink label="Sun" pagename="sun"></pagelink>
        <pagelink label="PowerHome stats" pagename="ph_stats"></pagelink>
      </pagelinks>
    </page>
    <page 
      pagename="sun" 
      pagetitle="Sun" 
      statustext="Sunrise: %sunrise%&#xA;Sunset: %sunset%&#xA;Dusk: %dusk%&#xA;Dawn: %dawn%">
      <refresh>
        <update url="ph_getsuntime(today(),1)" variablename="sunrise"></update>
        <update url="ph_getsuntime(today(),2)" variablename="sunset"></update>
        <update url="ph_getsuntime(today(),3)" variablename="dawn"></update>
        <update url="ph_getsuntime(today(),4)" variablename="dusk"></update>
      </refresh>
      <actions>
        <action label="Get Current Server Time" url="now()" return_type="dialog"></action>
      </actions>
      <pagelinks>
        <pagelink label="PowerHome stats" pagename="ph_stats"></pagelink>
      </pagelinks>
    </page>
    <page 
      pagename="ph_stats" 
      pagetitle="PowerHome Stats" 
      statustext="PowerHome Uptime: %ph_uptime%&#xA;PowerHome Directory: %phdir%&#xA;PowerHome Operating Mode: %phmode%">
      <refresh>
        <update ss_requestType="FORMULA" ss_body="ph_powerhomeuptime_s()" variablename="ph_uptime"></update>
        <update url="ph_getphdir()" variablename="phdir"></update>
        <update ss_body='if(ph_getmode()=0,"Normal","Restricted")' ss_requestType="FORMULA" variablename="phmode"></update>
      </refresh>
      <actions>
        <action label="List Processes" ss_body="ph_listprocesses(1)" ss_requestType="FORMULA" return_type="dialog"></action>
        <action label="Reinitialize" ss_body="ph_reinitialize()" ss_requestType="FORMULA" return_type="silent"></action>
      </actions>
    </page>
  </pages>
  <variables>
    <variable 
      name="ph_uptime" 
      defaultcolor="#888888" 
      defaultvalue="UNKNOWN"
      notificationphrase="PowerHome uptime: %ph_uptime%">
    </variable>
    <variable 
      name="sunrise" 
      defaultcolor="#888888" 
      defaultvalue="UNKNOWN"
      notificationphrase="Today's sunrise: %sunrise%">
    </variable>
    <variable 
      name="sunset" 
      defaultcolor="#888888" 
      defaultvalue="UNKNOWN"
      notificationphrase="Today's sunset: %sunset%">
    </variable>
    <variable 
      name="dusk" 
      defaultcolor="#888888" 
      defaultvalue="UNKNOWN"
      notificationphrase="Today's dusk: %dusk%">
    </variable>
    <variable 
      name="dawn" 
      defaultcolor="#888888" 
      defaultvalue="UNKNOWN"
      notificationphrase="Today's dawn: %dawn%">
    </variable>
    <variable 
      name="phdir" 
      defaultcolor="#888888" 
      defaultvalue="UNKNOWN"
      notificationphrase="PowerHome directory is %phdir%">
      <setting value="c:\powerhome" color="#00FF00"></setting>
    </variable>
    <variable 
      name="cloudpushtest" 
      defaultcolor="#888888" 
      defaultvalue="UNKNOWN"
      notificationphrase="Cloud push test term is %cloudpushtest%">
      <setting value="phca" color="#00FF00" notification="true"></setting>
      <setting value="powerhome" color="#FF0000" notification="true"></setting>
      <setting value="rapunzel" color="#0000FF"></setting>
    </variable>
    <variable 
      name="phmode" 
      defaultcolor="#888888" 
      defaultvalue="UNKNOWN"
      notificationphrase="PowerHome mode is %phmode%">
      <setting value="normal" color="#00ff00"></setting>
      <setting value="restricted" color="#ff0000"></setting>
    </variable>
  </variables>
</Preference>

Leave lines 1, 2 & 3 alone. For lines 4 – 11, enter in the information for your PH server. For the PhWebServer, be sure to put the http:// or https:// in front. Only the latest PH versions support https on it’s internal webserver, so make sure you enter in the correct protocol and port number if necessary. For instance, http://myPhWebServer:8080, or https://myPhWebserver.com (use the default port). Similarly, the fully qualified domain name for the socket server will not have a protocol at the front. An example entry there might be myphserver.com or an ip address, such as 123.45.67.89. Then enter in your usernames and passwords in the appropriate places. Also be sure to declare the authentication method that your PH webserver is using (either basic or cookie). If you want, you can save this file now, rename it to main_menu_pref.xml, and upload it to your phone’s sd card root. But if you want to understand what the rest of the settings are for, read on.

Next we will create the main menu.¬†Each page in phca must have a pagename and a title. The sample configuration file here has three pages: the Main Menu, Sun, and PowerHome Stats. The pagename is used internally by phca to uniquely identify each page. Therefore, it must be unique among all of your pages. Do not rename the mainmenu. You can change the title of it though (maybe something like “Skip’s PowerHome”???). The next entry is for the status text. This string will be reproduced at the top of the page menu in phca. You may insert placeholders for variables which will be replaced with their actual values when that value is updated. Place all variable names inside percent signs. Each variable used must be unique among all of the pages. For instance, %sunrise% can only refer to one thing throughout the entire application. Although, %sunrise% could be on more than one page. The variables themselves will be declared in the last section of the configuration file. Also note that carriage returns must be encoded as they would be for any xml file:

&#xA;

including the semicolon… (that’s ampersand-hash-letter x-letter A-semicolon). Other special characters would also have to be properly encoded, such as quote marks. Because the variable names are delimited with percent signs, you will not be able to use percent signs anywhere else in your status text. Next we will edit the refresh commands.

When you tap on the status text, all of the commands in the refresh section for that page will be executed. Each update command can only update one variable. The commands can be either Socket Server commands or actual urls to your PowerHome server. All urls in phca will be called like this example: http://myPowerHomeserver/ph-cgi/eval?formula=ph_powerhomeuptime_s(). The only part we need to specify in this configuration file is the formula that is executed because the rest stays the same for each command. Socket server commands must declare the request type (FORMULA, FORMULATRIGGER, TRIGGER1, TRIGGER2, TRIGGER3, TRIGGER4, or TRIGGER5–see the Socket Server documentation for details). An example socket server command will look like ss_requestType=”FORMULA” ss_body=”ph_powerhomeuptime_s()”. As you can see, for both of these examples, the command simply to execute the ph_powerhomeuptime_s() command which returns a string representing how long PowerHome has been running. Phca will store that value in the ph_uptime variable so it can be displayed in any status text with the %ph_uptime% variable. You can enter as many refresh update urls as you need for each page, and the variable that a particular refresh command refreshes doesn’t even need to appear on that page’s status text. Formulas can be as complex as you need as long as they return a single value. For instance, if(ph_getdigital(‘FRONT_DOOR’)=1,’OPEN’,'CLOSED’) will work just fine. Variables are only updated when you press the “Refresh” link. However, there is an option to use the Android C2DM service to push variable updates to your phone in near real time and much less power (which means longer battery life). More on the C2DM is below.

The next section in each page are the actions. These actions tell your PowerHome to do something, like close the garage door, turn your tv off, turn lights on, or start your sprinkler system. At its simplest level, what we are really doing is telling ph to execute a macro. The macro doesn’t have to return any value, but it can. It just has to execute and do its thing. For actions that do return values, you can optionally have that value displayed in a dialog box by setting return_type to “dialog”. Each action needs a label that will be displayed on the page menu. You may have as many actions as you want on each page, including the Main menu.

The final section of the main menu page are the page links. Other pages cannot have pagelinks (there are no sub-menus, or nested menus). You should put a page link to each of your pages here. If you don’t you will have no way to get to that page. The label again is the text that you will see in the menu and the pagename must be the same as the name of the page that you want this link to point to.

Other pages are configured the same way. Just follow the examples.

The final section of the configuration file is the “variables” section. Each variable used in the status texts of your pages needs to be declared here. Each variable will have a default color which will be the color if that variable is set to a value that you have not assigned here. Each variable will also have a default value which will be displayed until that variable has been updated by a refresh or by C2DM pushes. Also take note of the “notification” setting. When that is set to true you will get Android notifications on the status bar when that variable has been set to that value. From within the Phca app you will have the option to assign a notification sound to that as well. The notification setting only refers to push notifications. The idea is that if a variable is updated when the app is not in the foreground, you can still be notified of that change in real time. The notificationphrase setting refers to the text that appears in the notification area when that variable has been updated.

When you have updated your configuration file, ensure it is named precisely main_menu_pref.xml (all lowercase) and upload it to the sd card of your phone. There are several ways to do it but for most android phones it is a matter of simply connecting your phone with a usb cable to your computer and mounting the phone’s storage. Some phones have two or more storage mount points so you may have to try several places. On my phone it is /mnt/sdcard if that helps. You can use adb or windows explorer to copy the file over.

C2DM
Cloud to Device Messaging, or C2DM, is an Android service available on FROYO operating systems and later (Android 2.1 and later). It is just like text messages in that the phone does not poll any server for messages. Instead, the messages are pushed to the phone. The beauty of this is that the messages arrive nearly instantly after sending them and the phone uses practically no power waiting for the message. There is no service running in the background waiting for the messages. It just works. If you have a phone capable of supporting C2DM then you can (and probably should) enable C2DM for phca. You will have to register for a free account at https://phc-a.net and then write a few formulas in some of your PowerHome macros.
1. Register at https://phc-a.net. Please read the part about choosing a username and password carefully. I am not a computer and internet security expert. I think I have your username and password stored nice and secure, but who knows. Probably not, actually. So make up a username and password that you have never used before. If you forget it, it’s not a big deal. Just re-register. The bottom line is, if my website is hacked and the username & passwords are stolen, I am not responsible if you used your paypal username and password here and the bad guys figure it out.
2. Once you have registered at the website, start up phca, click on the menu button and choose “Enable C2DM”. Enter in the same username and password and you should see after a few seconds that C2DM is enabled. Next we can test the C2DM service. Open phca and look at the status area of the main menu. We are first going to test the c2dm using a web browser to send a message to your phone and change the value of the Cloud Push Test variable (%cloudpushtest%).

Open any web browser and enter the following address in the address bar. After editing the username and password, press enter and in a few seconds you should see your message.

https://phc-a.net/testsend.php?username=YourUsername&password=YourPassword&varname=cloudpushtest&varvalue=HELLO_WORLD

Within just a few seconds you should see the value change to the new value. If it doesn’t work double check the username and password. If you have any spaces in the username, password, varname or varvalue then you will have to encode them with %20 (best to test with no spaces). If it still doesn’t work, try disabling C2DM and then re-enabling it. If it still doesn’t work, try the google app “Chrome to Phone” from the market. It uses the same C2DM service. Leave comments here if you need help. You can also use one of the logcat programs in the market to read your logs for clues.
3. Now that we know your phone is receiving the C2DM messages, let’s enable PowerHome to send the messages automatically. You can easily send messages to the phc-a server using the PowerHome ph_geturl() formula. I suggest that you use the testsend.php page while testing and then move to the regular send.php once you are sure you have everything working. What I do is put my username and password in a global variable ({PHCA_USER} and {PHCA_PASS}). Then all you have to do is add the variable name and variable value. Again, remember that if any of these required fields have spaces or other url non-safe characters that you must escape them. Fortunately ph comes with a nice formula ph_htmlescape() to do that for you.

ph_geturl(“https://phc-a.net/testsend.php?username={PHCA_USER}&password={PHCA_PASS}&varname=cloudpushtest&varvalue=phca”)
ph_geturl(“http://phc-a.net/testsend.php?username={PHCA_USER}&password={PHCA_PASS}&varname=cloudpushtest&varvalue=” + ph_htmlescape(“A special message”))

What happens when you send “phca” or “powerhome” as the variable value? From within the phca app, hit menu->variable settings. Set a ringtone for the cloudpushtest variable, phca value. Now when you send a value of phca, you should hear the ringtone that you selected.

If you want to save the testsend webpage output, just have it dump the results of the ph_geturl formula to the event log or store it in a global variable.

That’s about it. If you have any questions, leave a comment below and click the subscribe to comments checkbox.

Again, here’s a link to a complete, working main_menu_pref.xml file.

 Posted by at 5:36 pm

Leave a Reply