Floorplan Script Functions

From XAP Automation
Revision as of 17:10, 28 April 2008 by Jamest (Talk | contribs)

Jump to: navigation, search

Available functions:


Globals

GetGlobal

GetGlobal(Globalname) GetGlobal returns the data stored within the global variable GlobalName. You should use SetGlobal to put the data in to the variable.

ret=GetGlobal("MyVariableName")

Note globals stored with getglobal/setglobal do not persist across restarts of Floorplan. If you need that functionality then you should use GetDBglobal/SetDBGlobal instead

SetGlobal

SetGlobal(Globalname, NewData) As Boolean SetGlobal puts the data NewData in to the global variable GlobalName. You should use GetGlobal return the information.

SetGlobal "MyVariableName","Hi, this is my data"

Note globals stored with getglobal/setglobal do not persist across restarts of Floorplan. If you need that functionality then you should use GetDBglobal/SetDBGlobal instead

GetDBGlobal

GetDBGlobal(Globalname) As Variant

GetDBGlobal returns a Variant, as you can have an array of DBGlobals. Most users are frequently only going to use a single item (the zero'th) as in this case.
if GetDBGlobal("HouseEmpty")(0) then
....some code
end if

The DBGlobal being used here is storing Boolean.

SetDBGlobal

SetDBGlobal(Globalname, NewData, Overwrite As Boolean) As Boolean

The following will set the HouseEmpty global variable to TRUE, overwriting an existing value.
	SetDBGlobal "HouseEmpty", TRUE, TRUE


Devices BSC/TSC

GetState

GetState(xAPName) As String

This returns the state of the device which can be referenced by the xAP full source string.
y=GetState("phaedrus.netiom.node2-1:heating.outstatus.go")
Or by the xAP Floorplan friendly name
y=GetState("Heating GO")

GetLevel

GetLevel(xAPName) As String

This returns the level of the device which can be referenced by the xAP full source string.
y=GetLevel("phaedrus.netiom.node2-1:light.level")
Or by the xAP Floorplan friendly name
y=GetLevel("Light Level")

GetLevelMax

GetLevelMax(xAPName) As String

This returns the maximum level of the device, as reported by the device, which can be referenced by the xAP full source string.
y=GetLevelMax("phaedrus.netiom.node2-1:light.level")
Or by the xAP Floorplan friendly name
y=GetLevelMax("Light Level")

GetDisplayText

GetDisplayText(xAPName) As String

This returns the display text of the device which can be referenced by the xAP full source string.
y=GetDisplayText("phaedrus.netiom.node2-1:Alarm")
Or by the xAP Floorplan friendly name
y=GetDisplayText("Alarm")

GetText

GetText(xAPName) As String

This gets the string from the Text name/value pair for the BSC device.

Temp=GetText("mmwave.tom10.g8kmh_hapc2:lounge")

GetLastUpdate

GetLastUpdate(xAPName) As Date

This returns the date and time xAP Floorplan updated the device from the received xAP message.
x=GetLastUpdate("mmwave.lcdswitch.bedroom1:07")

GetLastChange

GetLastChange(xAPName) As Date

This returns the date and time xAP Floorplan updated the device from the received xAP BSC Event message.
x=GetLastChange("mmwave.lcdswitch.bedroom1:07")

SetDisplayText

SetDisplayText(xAPName, NewValue) As Boolean

Use this to change the displayed text on the map. For example, to change the colour of the display which in this example is a Temperature:

DisplayString="<fontcolor=""red"">"&Temp&"</font>"
SetDisplayText ScriptExtras, DisplayString

Note the use of ScriptExtras which holds the xAPName of the device calling the script. This allows a single script or function to be used by many similar devices. See also xAP Floorplan Global.xsp

SetDisplayTooltip

SetDisplayTooltip(xAPName, NewValue) As Boolean

Overrides then builtin tooltips on devices with the string passed to this function. Set to "" to revert to original practice.

SetDisplayTooltip "mmwave.lcdswitch.bedroom1:07","This is the new tooltip"

Devices Raw

GetValue

GetValue(xAPName) As String

GetDisplayValue

GetDisplayValue(xAPName) As String

SetDisplayValue

SetDisplayValue(xAPName, NewValue) As Boolean

SetDisplayTooltip

SetDisplayTooltip(xAPName, NewValue) As Boolean

Sending

SendxAP

SendxAP(xBody, xClass, Optional xTarget)

This sends an xAP message to a non BSC device.

body="display.text" & chr(10) & "{" & "line1=Lounge temp " & y & chr(10)& "duration=10" & chr(10)& "}" & chr(10) 
SendxAP body, "message.display",  "mmwave.lcdswitch.lounge1"

SendxPL

SendxPL(xBody, xClass, Optional xTarget)

This sends an xPL message. Here a TTS message to all devices. Note that xPL messages should not have braces '{' and '}'.

	SendXPL "speech="&CurrMsg,"tts.basic", "*"

SendBSCState

SendBSCState(xTarget, NewState)

This script function changes the state of a device. In this case the state is toggled.

SendBSCState "phaedrus.netiom.node3-2:output.11", "toggle"

SendBSCLevel

SendBSCLevel(xTarget, NewLevel)

This function changes the device level, for example a dimmer.

SendBSCLevel "mmwave.dmx512.g8kmh_hapc1:House.Upperfloor.Landing.Lobby","50%"

or

SendBSCLevel "mmwave.dmx512.g8kmh_hapc1:House.Upperfloor.Landing.Lobby","128/255"

SendBSCText

SendBSCText(xTarget, NewText)

SendBSC

SendBSC(xTarget, NewState, NewLevel, NewText)

This function controls a BSC device, allowing a number of the device attributes to be controlled. For example, this turns the device on and sets the level in one operation.

level ="90/255"
SendBSC "mmwave.dmx512.g8kmh_hapc1:House.Upperfloor.Bedroom2.Ceiling.Main","on",level, ""

Timers

AddTimer

AddTimer(TimerName As String, TimerTime As Date, Script As String, Optional RawCode) As Boolean

Here a timer is set to run 5 minutes from now and execute a script.

AddTimer "UFHPumpRun", DateAdd("n", 5, Now()), "UFHPumpRunOff"

You can check the timer is set by going to the 'Timers' tab.

DeleteTimer

DeleteTimer(TimerName As String) As Boolean

Example

DeleteTimer ("UFHPumpRun")

EditTimer

EditTimer(TimerName As String, TimerTime As Date, Script As String, Optional RawCode) As Boolean

CheckTimer

CheckTimer(TimerName As String) As Variant

This returns a Variant so each element returns different information regarding the timer. The first is the timer name. Those created from scripts are prefixed 'Script:' in the return and the Timers tab.

TimerName=("DiningPIR")(0)

The following returns TRUE when...

TimerRet=CheckTimer("DiningPIR")(1)

The following returns the Date/Time when the timer will fire.

TimerDate=CheckTimer("DiningPIR")(2)

The next returns the name of the script to execute when the timer fires.

TimerScript=CheckTimer("DiningPIR")(3)

The next returns the optional raw code to execute when the timer fires.

TimerRawCode=CheckTimer("DiningPIR")(4)

You can of course use the following approach

TimerVariant=CheckTimer("DiningPIR")
TimerName=TimerVariant(0)
..etc

ScriptRun

ScriptRun(ScriptName)

This runs another script.

ScriptRun("Security")

To run an Auto script add a '.' to the name.

ScriptRun(".LightsOff")

Time

DawnTime

DawnTime() As String

DuskTime

DuskTime() As String

IsDay

IsDay() As Boolean

IsNight

IsNight() As Boolean

Database

ExecuteSQL

ExecuteSQL(SQL)

This function requires some knowledge of SQL. The following example can be used to create a table in the xAP Floorplan database.

SQL="Create Table Setpoints (Location Text, Hour Integer, SetpointOcc Integer, SetPointAway Integer);"
SQLReturn=ExecuteSQL("SQL")

RunSQL

RunSQL(SQL) As Variant

To access a table, returning a variant.

Location=Lounge
SQL="Select * from Setpoints where Location= " & Location & ";"
SQLResult=RunSQL(SQL)

msgbox "Row 1 item 1 is " & SQLResult(1,1)

Rooms

GetRoomMode

GetRoomMode(RoomName)

GetRoomState

GetRoomState(RoomName)

GetRoomOccupancy

GetRoomOccupancy(RoomName) As Boolean

SetRoomMode

SetRoomMode(RoomName, RoomMode As Integer) As Boolean

SetRoomOccupancy

SetRoomOccupancy(RoomName) As Boolean


Custom Page specific

GetLastEvents

GetLastEvents() As Variant

TitleStripGreen

TitleStripGreen(xTitle, xURL)

TitleStripBlue

TitleStripBlue(xTitle, xURL)


Other Functions

LogDebug

LogDebug(Message) When writing scripts it is often useful to see what is happening. This function lets you write messages that can then be viewed in the Floorplan web interface

LogDebug "This text will appear in the log"

The debug log is found in config pages of Floorplan under scripts/scripts debug or from this url /scriptsdebug.xsp

GetFromRaw

GetFromRaw(RawMessage, ItemToFind)

This gets the value from a name/value pair in a raw(non BSC/TSC) message. Take care to follow the format shown (section name comma item), additional spaces cause errors.

CurrTemp=GetFromRaw(rawmessage, "weather.report,tempc")

To access infomation from the message header you can use

  • message.header,source
  • message.header,class
  • message.header,uid
  • message.header,target