PHCA Actions
This is the most important aspect of PHCA. Actions are commands that are sent to your PowerHome installation. Actions can either be an instruction to your server to do something (like close the garage door, or arm your burglar alarm), or to get the status of something (such as the current arming status). Actions can also do nothing. For instance, if you create a page where there are two logical sections (perhaps the top few commands are for the upstairs lighting and the bottom few commands are for the ground floor). You could use an action that does nothing but serve as a label to help you identify those sections. What’s more, the action labels (the part you see on the screen) can contain variables. Variables are objects declared in phca. Whenever a variable is updated (perhaps by an action that requests the arming status, or perhaps by C2DM push messaging), any place where that variable was used will be updated with its current value. In other words, the labels for the actions are dynamic, and can change based on any number of variables and their current values. Variables have a lot of other settings and options, but let’s just leave it at this for now. Navigate to the “Page chooser” configuration page and select the mainmenu page. Unless you have already added some actions and/or pagelinks to the mainmenu, you should be looking at a mostly blank page. Hit the menu button and you will see options to add an action item, a pagelink item, or edit page settings. Click on Add action item.
Adding action items. Actions have a lot of settings, so let’s go over them one at a time:
The first two settings are for the major and minor labels. They only apply to menu type pages (image pages don’t have a place for labels). This is the text that you will see in the menus. If you want to include a variable in either of the labels, just enclose the variable name between tildes “~”, such as ~garagedoorstatus~.
TIP: Entering text like variable names often results in words that are not real words. At least to an auto-correcting android keyboard they are not real words. You might have better luck entering these with the standard, non-auto correcting android keyboard.
TIP: Finding the tilde on some android keyboards can be tricky. I haven’t seen one yet that DOESN’T have a tilde, but some of them hide it pretty good.
Any text that is inserted between tildes will be treated as a variable and will be replaced with that variable’s current value.
The next setting is for a note. This is an optional setting on both menu and image-type pages. However, I strongly encourage you to use them on your image type pages because the note will be the only thing that will clue you in as to what the action does since the major and minor labels are not used on image-type pages.
The Color setting is for image-type pages only. What color from the colormap will serve as the target for this action. You can use the common name for most colors, or you can use the hex value of the color. I suggest that you try and stick with the common names just to keep things simple.
Check the box next to Protect with PIN if you want to password-protect this action. This setting will be grayed-out (disabled) if you have not set a PIN in the global options.
For the Network setting, the options are None, Web, And Socket Server. If this action doesn’t actually do anything, then choose none. If you want the action sent as an http request, choose web, and if you want to use the socket server, then choose socket server.
TIP: If you can, I strongly suggest using the socket server. It is much faster than http communication.
If you are using a socket server, then you have to indicate what type of command you are sending. I have not personally ever used anything other than “FORMULA”, so the other options are untested, but should work. If you are using something other than FORMULA, I would like to hear about it in the comments so I can know if they are working.
Socket Server Body and URL are the commands that you want to send to the powerhome server. For example, ph_macro(‘arm_system_away_mode’)
Auto-update variable is to enable you to apply the server response to the value of the assigned variable. For instance, if you want to ask the PH sever the value of a PH global variable, perhaps using ph_getglobal_s(‘arm_status’), then the value returned will be stored in the assigned variable.
Action parameters allow you to set a customizable value before the command is sent. For instance, you could have a command to set the light level for your kitchen light. I have a PowerHome macro that takes parameters to adjust the light level of any light in my house to any level. I execute the macro with ph_macroparm(‘adjust_any_light’, ‘kitchen’, ~lightinglevel~,0,0,0). Note the variable in the command “~lightinglevel~”. This variable will be replaced with the value of lightinglevel before it is sent. So the action parameter allows you to set that value right before the command is sent. You have two user interface options here: a slider (“seekbar” in Android language) and a text box. Sliders work well when you are going to set a numerical value, such as a lighting level or a temperature. The text box works well for text type entries. I use a text box in a macro that I have to set the text in the keypad displays of my Elk keypads. Either type of action parameters (slider or text box) takes a setting for the prompt (such as “Select kitchen lighting level” or “Enter the text to be displayed on the keypads”). Sliders also have settings for min and max values.
Finally, you have an option to have a dialog pop up with the return value. If you want to get the current arm status, for instance, select “Dialog” and you will get a pop-up dialog box with the message returned by the server. Choose “none” if you do not need a pop-up. If you do choose “dialog”, you can also set a caption for that dialog, such as “Current arming status”.
One action can execute as many individual commands as you wish. If you want to enter some more action commands, click on “Save and add additional commands”. Otherwise just click on “Save Action” to save your action.