PHCA Editing xml backup files

This is an optional, advanced topic. If you are not comfortable copying files to and from your android phone over USB, or if you do not have a strong background in xml, then you do not need to read this page.

You have the option of editing your xml configuration files on your computer and then uploading them to your phca directory on your phone. You might want to do this if you have an extensive menu structure and you think you can edit those menus faster externally in an xml editor or text editor that you can using the graphical interface built into phca. Note that there is a little less error checking in the restoration routine than there is in the gui routine. What this means is that when you edit your menus on the phone, there are a lot of error checking routines built in to ensure that everything should work as designed. If you edit a backup file, and then import the file, phca more or less assumes that the backup file is in the correct format because it assumes that phca created it. If you edit the file outside of phca control, you could break your installation. If you are careful, and follow the sample provided, you should not have any problems.

Before you get started, I suggest that you make one or two pages with the type of actions that you intend to use the most. Then you will be able to copy those actions to other pages and then just edit the parts that change, such as the major and minor labels, and the command itself.

There is a sample xml file here that you can use to refer to.

The first tag with the version and encoding information is required.
The opening “Preference” tag is required for all configuration files. The attributes in the Preference tag are
(All settings are required)
PhSocketServerAddress=”myhost.homedns.org” The hostname for your socket server. Note there is no protocol, such as http://
local_web_server=”http://192.168.1.110:8080″ If your phone is connected to your home wifi, what is the ip address of your ph web server
PhWebServerPassword=”my_web_server_password”
c2dm_enabled=”true” Do you want to use C2DM
version=”2.1.1″ The current version of this xml file. Should match the app version
PhWebServer=”http://myhost.homedns.org:8080″ The fully routable address to your web server
PhSocketServerPassword=”my_socket_server_password”
PhWebServerAuthMethod=”basic” either basic or cookie. Should match the auth method set in your PowerHome installation
SSID=”my_home_wifi_ssid” Used to determine if connected to home wifi network
pin=”1111″ must be set to four digits.
c2dm_turned_on=”true” currently receiving c2dm messages
PhWebServerUsername=”my_web_server_username”
PhSocketServerUsername=”my_socket_server_username”
PhSocketServerPort=”8500″
c2dm_password=”my_c2dm_password” from the phc-a.net website
c2dm_message_count=”2323″ how many messages have been received. No need to set this, but you could.
local_socket_server=”192.168.1.110″
c2dm_username=”my_c2dm_username” from the phc-a.net website
c2dm_reg_id=”APA91…” is updated each time you unregister and re-register c2dm from the phca app. No need to set this.

The “pages” tag is required and all individual pages will be nested inside of this tag.
Each page is in its own page tag. Each page will have the following attributes:

pagename=”lighting_firstfloor” A required setting for the page name. Must be unique among all pages.
pagetitle=”Downstairs lighting” A required setting for the human-readable page title, but OK to be blank.
page_note=”" Required, but ok to be blank. Place for you to enter any additional information about the page.
page_type=”image” Required, one of either “image” or “menu”
image_filename=”firstfloorvisible.png” Required for image type pages, this is the visible image that you will see in the app. Also required for menu pages–set to blank
colormap_filename=”firstflooroverlay.png” Required for image type pages, this is the colormap image (not visible within the app) Also required for menu pages–set to blank

Pages will have any number of actions and pagelinks, each nested within the page tag

Actions will be nested in an action tag
colormap_color=”gray” required for all pages, optional but unused for menu type pages. This is the target color from the colormap image for this action
majorlabel=”Arm status:~armstatus~ Arm state:~armupstate~ Alarm state:~alarmstate~” The first line of text in the menu or widget. Required, but ok to be blank (but that would be strange…)
minorlabel=”" The second line of text. Required, but ok to be blank
url=”" required, but ok to be blank. Required to be filled in if you want to send an http command
ss_body=”" required, but ok to be blank. Required to be filled in if you want to send a socket server command
ss_requestType=”FORMULA” Usually set to “FORMULA”. Other options are FORMULATRIGGER, and TRIGGER1 through TRIGGER6. See the ph documentation for more details. Required.
return_type=”silent” Do you want a dialog to pop up with the information the server returns? required setting, one of either “silent” or “dialog”.
net=”none” Required setting. One of “none”, “web” for http, or “ss” (for socket server)
note=”" Required, but ok to be blank. Highly encouraged for image pages to be filled in.
update_varname=”None” The variable that will be updated with the server returned information. Required setting, use “none” if this option is not needed.
paramType=”none” Do you need a popup before the command is sent, such as a slider dialog or a text box, to enter more information before the command is sent? Required setting, use one of “none”, “slider”, or “dialog” (for text entries)
slider_min_val=”0″ required setting for slider type parameters (otherwise ignored)
slider_max_val=”100″ required setting for dialog type parameters (otherwise ignored)
action_parameter_var_name=”" What variable to you want to update with the value from the slider or text box. Required for actions that have a paramType other than “none”
dialog_prompt=”" optional, but highly recommended for paramType other than none. This is the title on the popup requesting the additional information
pin=”false” Is this action pin protected? true or false. Required setting. Ignored if the pin has not been set in the global settings above.
dialog_title=”" Optional, but highly suggested for return_type other than none. This is the title on that dialog.
> Don’t forget to close the action tag with the closing symbol “>”

Action commands are additional actions tied to this action. They are represented in the xml file as follows:

Opening tag for this action command. Required.
url=”" required entry. Required to be filled in for http commands. May be blank for socket server commands.
variablename=”armstatus” The variable that will be updated with the information returned by the server. Required setting, but may be blank.
ss_requestType=”FORMULA” Required setting, but unused for http commands (just set it to “FORMULA”).Otherwise, usually set to “FORMULA”. Other options are FORMULATRIGGER, and TRIGGER1 through TRIGGER6. See the ph documentation for more details. Required.
ss_body=”ph_getglobal_s(‘ELK_ARM_STATUS_AREA1′)” Required setting, but may be blank for http commands. Required to be filled in for socket server commands.
net=”ss” Either “ss” for socket server or “web” for http. Unlike the action setting, this cannot be set to “none”.
commandname=”Get arm status” Required setting, and may not be blank. This is a description for this command, which will be shown on the action command chooser page. This is how you will identify this action command from other action commands.
/> Don’t forget to close the action_command tag
When done with all of the action commands, don’t forget to close the action tag

Pagelinks are represented in xml like this:

Required opening tag for a pagelink
pagename=”armstatus” Required, non-blank. Must have the name of the target page
minorlabel=”PHCA Page” Required, but may be blank.
note=”" required, but may be blank. Highly encouraged to fill in on image type pages
pin=”true” required, either true or false.
/> Don’t forget the closing tag for the pagelink

When done with all of the actions and pagelinks on this page, don’t forget to close the page tag
When done entering all pages, don’t forget to close the page tag

Variables are represented in xml as follows:
Opening tag for all variables. All individual variables are nested inside of the variables tag. Required.
Opening tag for an individual variable. Required.
variablename=”cloudpushtest” Required, may not be blank, may not match another existing variable.
defaultcolor=”gray” Default font color for the variable. Required.
defaultvalue=”UNKNOWN” Default value for the variable. Required.
notificationphrase=”Cloud push test term is ~cloudpushtest~” Taskbar phrase when the variable is updated in the background over C2DM. Required for all variables, even if the variable won’t be updated over C2DM. Can be blank.
> Don’t forget the closing tag for the variable
Opening tag for an optional variable value setting. Can be omitted (along with all associated settings). A variable can have any number of value settings (including zero)
value=”hello_c2dm” Variable value for this setting. Required.
color=”black” Font color when the variable is equal to the value. Required
sound_uri=”content://media/external/audio/media/19″ Optional sound uri for the notification. These are hard (impossible???) to figure out from outside of the phca app, so I suggest omitting this setting and setting it from within the phca app. If a variable value setting does not need a notification sound, then this setting should be completely omitted. Do not enter in a blank setting here.
notification_type=”none” One of none, toast, bar (task bar), and toastbar (toast and taskbar).
/> Closing tag for this variable value setting
Closing tag for this variable
Closing tag for all variable
Finally, the closing tag for all settings.