hvsrv - HomeVision Network Server All commands are in the form of a command identifier and a number of command specific parameters. All commands receive acknowledgement (either success or a specific error) from the server. If the command results in events being sent, all events that were a result of this command are received by a client before the client receives the initiating commands response. All parameters on the command line are space delimited. If you have a parameter that has integral spaces in it (like descriptions and the like), surround the entire parameter with double quotes. hvsrv, by default, uses port 1588 to communicate with your clients in a structured format (described below) Port 1589 (again, by default) is a raw binary connection to the HV hardware. Unless shared ports are enabled when HVSRV is started (via the -sharedraw switch), when a binary connection is open, normal clients are suspended until the connection is closed. Also, only one raw connection at a time is allowed (again, unless you use -sharedraw). Raw access is really meant to allow other programs that expect to talk directly to HV to be able to do so without interferences. When you connect to HVSRV on port 1588, you will immediate receive a welcome message formatted like this: HVSRV V1.0 READY THe first word identifies what we are. The second is the servers version and the last is the state the server is in. In the future, additional parameters may be appended to the welcome message, so you should never assume the state can be read by simply grabbing the end of the string. The order and type of existing parameters will never change -- just be aware new ones may appear after the state and code accordingly. A typical client will then issue a GET_CONFIG call for each item they are interested in to see what the current state of everything is. This is the fastest, easiest way to "get up to speed" with the server. Once you have the state, HVSRV will send update messages whenever anything changes the items current value/state. This includes other clients making requests, macros/schedules/etc in HV changing values or even your own clients commands. Attributes: Each resource type can have an arbitrary number of name/value attributes associated with it. In the case of the X10 resource, some of that names and the values they can be set to are reserved and directly affect how the devices are controlled. Beyond that though, they are there for your puposes. Attributes are written to a hvsrv.attr file in the same directory the hvsrv process is started from. The attributes are written out whenver the HVSRV exits normally of whenever a HVSERVER SAVE_STORE command is executed. If you make a lot of changes to the attributes, you may want to issue a HVSERVER SAVE_STORE. If for some reason the HVSRV process ends abnormally, you changes would otherwise be lost. It's planned to eventually have the HVSRV periodically save any changes to the permanent store when it's been idle for a while. ** NOTE: HVSRV enables the HomeVision update reporting protocol. This protocol triggers a message from HomeVision to HVSRV whenever an internal state change in HomeVision occurs. Unfortunatly for things like flags and variables, HV sends an update anytime a flag or variable is assigned a value, even if the assignment doesn't result in changing the value of the flag/variable. For example Var #0 = 1 // HV would send a message saying Var #0 changed to 1 Var #0 = 1 // HV would send another message saying Var #0 changed to 1, but in reality, there was no change - just an assignment Because of this, you need to be careful about things that get assigned in quickly executing events (periodic events that execute on every loop are a good example). Instead of unconditionally assigning a variable or flag in those cases, wrap an IN/THEN around it to do the assignment only if the new value represents a change in the flag/variable. You really do not need to do this for longer term events, but anything that executes regularly at 2 minutes or less intervals could benefit and things that execute ever loop require this. If not done, the flood of messages comming from HV to HVSRV will basically paralyze HVSRV. Command line: The hvsrv command line minimally looks like this: hvsrv /dev/ttyS0 where /dev/ttyS0 is the serial port the HV hardware is conneted to. By default, hvsrv assumes the HV hardware operates at 19200. if it operates at a different speed, put that speed after the device name (i.e. hvsrv /dev/ttyS0 9600). hvsrv can also connect to the HV hardware via a network connection. This is done by using a host name in place of the serial port like this: hvsrv remoteHV.mynet.org By default, hvsrv will attempt to connect to the remote HV on port #23. You can change that port number by including it after the host name like this: hvsrv remoteHV.mynet.org 1002 In addition, the following switches can be supplied -autoclock hvsrv will periodically reset the HV hardware clock to match the clock of the computer HVSRV is running on. The clock is reset about once a day (about the same time you last started hvsrv). This is beneficial if your computer runs a NTP task that keeps it in sync with the internet time clocks. write a message to the system log for every client that connects or disconnects -debug hvsrv will print copius debugging messages. It will also not automatically detach the your terminal session -port xxx Change the client connection port to port number xxx. The default is 1588 -rawport xxx Change the raw client connection port to port number xxx. The default is 1589 -shareraw Allow simulataneous raw and normal client connections. Normally, when a raw connection is opened, the normal client connections are put "on hold" until the raw connection is closed. However, if you need to hav ethe raw port open for a long time, you may want to allow both raw and normal connections at the same time. Be aware that this can have strange consequences if the raw port is sending lots of odd commands and the normal clients are fed the results. -no_x10 -no_ir -no_flag -no_var -no_dinput -no_doutput These switches disable the automatic enabling of reporting changes in HV. This does not disable the ability for hvsrv to control, track and report changes in the resource, but just does not enable the automatic updates HV would normally send whenever an aspect of that resource changes. This is most useful if you have a schedule that changes a variable/flag/etc on every loop or something else that causes quick changes. Such quick changes can overwhelme your computer and/or hvsrv. In those cases, you'd disable automatic reporting in hvsrv and then have your schedule periodically kick an update status message out. If you do not do that, hvsrv will have an incorrect idea of the state inside your HV hardware. Finally, this switch just supresses the normal command that hvsrv sends to the HV hardware to enable automatic reporting. It does not explicitly disable such reporting - you need to make sure the HV hardware has that option disabled (if you care). With these switches, hvsrv will not change/alter whatever automatic reporting settings your HV hardware is set to. HVSRV responds to the following signals: TERM - logical shutdown (same as HVSERVER SHUTDOWN) USR1 - reconfigure HV hardware (same as HVSERVER RECONFIGURE) You should always use a TERM signal to shutdown HVSRV as that allows hvsrv to shutdown gracefully and save it's current state and attribute settings. Whacking hvsrv with a harsher signal (like -9) could result in changes to the settings you've made in hvsrv being lost Command/Event List: NOTE: Items with astericks are planned but not implemented /* X10 commands */ X10 ON A10 device X10 OFF A10 X10 SELECT B8 X10 ENABLE B8 X10 DISABLE B8 X10 HOUSE_ON B X10 HOUSE_OFF B X10 HOUSE_DIM B [count] X10 HOUSE_BRIGHT B [count] X10 DIM A10 [count] X10 BRIGHT A10 [count] X10 DIM_TO A10 50% X10 ENABLE A1 X10 DISABLE A1 X10 ALL_LIGHTS_ON A X10 ALL_LIGHTS_OFF A X10 ALL_UNITS_OFF A X10 STATUS A10 - send status for A10 X10 STATUS A - send status for each device in house code A X10 STATUS ALL - send status for all known devices X10 SET_ATTR unit attrname value X10 GET_ATTR [unit|house|ALL] [attrname|ALL] *X10 GET_ATTR_LIST X10 GET_ATTR_LIST attrname description valuelist attrname - name of the attribute description - description of the attributes purpose valuelist - indicates what values can be set for the attribute attributes can be formed in a couple of ways Simple types: [INTEGER] - Allows any integer number as a value [INTEGER:0:255] - Allows any integer between 0 and 255 [BOOLEAN] - Allows TRUE or FALSE [BOOLEAN:YES:NO] - Allows YES/NO as Boolean values [DECIMAL] - Allows a decimal number [DECIMAL:2] - Allows a decimal number with 2 decimal places [DECIMAL:2:-100:100] - allows a 2 decimal place value from -100 to +100 [TEXT] - Allows any text [TEXT:255] - allows text up to 255 characters long Enumerated types: These are lists of values. Because the list may contain spaces and other delimiters, the entire list is sent inside quotes. If the first character is not alphanumeric, then it starts a two character sequence the first of which identifies the inter-element delimiter (usually a comma) and the second is the intra-element delimiter (usually a colon). If the first character is alphanumeric, then the inter-element delimiter is set to comma and the intra-element delimiter is set to colon. You can have a simple list of values (i.e. RED,GREEN,BLUE) or add descriptions to values (i.e. ROOM1:Living Room,ROOM2:Kitchen) where the description is for viewing and the value (the portion before the colon) is the value to send/expect. RED,GREEN,BLUE ,:HIGH,MEDIUM,LOW |LEFT CENTER RIGHT ,:TOP:Top of Screen,MIDDLE:Middle of Screen,BOTTOM:Bottom of Screen $-ALPHA-The first$BETA-The Second$OMEGA-The Last The only delimiter you cannot use is [ (which is used to connote simple types) Standard X10 Attributes Name Description Values ---------- ----------------------------- ------------------------- DIMMABLE Is unit able to be dimmed TRUE,FALSE DIM_TYPE What sort of dimming is done X10,LEVITON,PCS,NON_DIMMING RESUME_DIM Does the unit resume to lvl TRUE,FALSE LOCATION Where is this device text DEV_TYPE What sort of device is it PLUGIN,WALL_SWITCH,WALL_OUTLET,INLINE,INTERFACE,OTHER ICON Name of icon for device text X10 GET_CONFIG - Sends all status, attributes, etc for all units Events: X10 UPDATE B3 ON 100 - House/Unit, ON/OFF state and dim level X10 ATTR_UPDATE B3 DIMMABLE TRUE - Change in an attribute /* I/R commands */ IR SEND 128 [count] IR SELECT_ZONES ALL -or- 1 4 5 IR ENABLE [TRANSMIT|RECEIVE] 128 IR DISABLE [TRANSMIT|RECEIVE] 128 IR SET_ATTR signal# attrname value IR GET_ATTR [signal#|ALL] [attrname|ALL] IR GET_CONFIG Events: IR RECEIVED 22 - I/R # in HomeVision IR STANDARD 34 12 - I/R Standard code device & keycode - Note you'll receive one of these even for HV Known I/R signals too IR ATTR_UPDATE 23 LABEL "TV Off" - I/R number, attr name and value /* Macro commans */ MACRO ENABLE 23 MACRO DISABLE 23 MACRO EXECUTE 23 MACRO SET_ATTR macro# attrname value MACRO GET_ATTR [macro#|ALL] [attrname|ALL] MACRO GET_CONFIG Events: MACRO ATTR_UPDATE 0 LABEL "Open Garage Door" - Macro #, attr name and value /* Variable commands */ VAR SET 123 100 VAR GET 123 VAR GET ALL VAR SET_ATTR var# attrname value VAR GET_ATTR [var#|ALL] [attrname|ALL] VAR GET_CONFIG Events: VAR UPDATE 1 2 - Var # and new value VAR ATTR_UPDATE 18 LABEL "Home/Away Status" - Var #, attr name and value /* Flag commands */ FLAG SET 123 FLAG CLEAR 123 FLAG NEUTRAL 123 FLAG INSTALL 123 state (SET, CLEAR or NEUTRAL) FLAG GET 123 FLAG GET ALL FLAG SET_ATTR flag# attrname value FLAG GET_ATTR [flag#|ALL] [attrname|ALL] FLAG GET_CONFIG Events: FLAG UPDATE 2 SET - Flag # and state (SET, CLEAR, NEUTRAL) FLAG ATTR_UPDATE 0 LABEL "Garage Open" - Flag #, attr name and value /* Digital I/O commands */ DINPUT GET [num|ALL] DINPUT DISABLE x DINPUT ENABLE x DINPUT SET_ATTR input# attrname value DINPUT GET_ATTR [input#|ALL] [attrname|ALL] DINPUT GET_CONFIG Events: DINPUT UPDATE 1 LOW - Digital Input # and state (LOW or HIGH) DINPUT ATTR_UPDATE 0 LABEL "Doorbell" - Input #, attr name and value DOUTPUT GET [num|ALL] DOUTPUT LOW x DOUTPUT HIGH x DOUTPUT SET x state (LOW or HIGH) DOUTPUT TOGGLE x DOUTPUT ENABLE x DOUTPUT DISABLE x DOUTPUT PULSE_LOW x millis (milliseconds: 0-65535) DOUTPUT PULSE_HIGH x millis (milliseconds: 0-65535) DOUTPUT SET_ATTR output# attrname value DOUTPUT GET_ATTR [output#|ALL] [attrname|ALL] DOUTPUT GET_CONFIG Events: DOUTPUT UPDATE 2 HIGH - Digital Output # and state (LOW or HIGH) DOUTPUT ATTR_UPDATE 0 LABEL "DD Decoder" - Output #, attr name and value /* Timer Commands */ *TIMER HALT x *TIMER RESUME x *TIMER STOP x *TIMER LOAD_GO x #_centiseconds (hundredsth of a second) *TIMER GET_ATTR [x|ALL] [a|ALL] *TIMER SET_ATTR x attrName attrValue *TIMER GET_CONFIG /* Scheduled Events */ *SCHD ENABLE n *SCHD DISABLE n *SCHD EXECUTE n *SCHD GET_ATTR [x|ALL] [a|ALL] *SCHD SET_ATTR x attrName attrValue *SCHD GET_CONFIG /* Periodic Events */ *PERIOD ENABLED n *PERIOD DISABLE n *PERIOD EXECUTE n *PERIOD SET_PERIOD x (x=LOOP, 1M, 5M, 13M, 1H, 2H, 4H, 8H) *PERIOD GET_ATTR [x|ALL] [a|ALL] *PERIOD SET_ATTR x attrName attrValue *PERIOD GET_CONFIG /* Server Commands */ HVSERVER RECONFIGURE - Forces server to reconfigure HV hardware - Used mostly if the HV hardware was disconnect and reset by some other software HVSERVER SHUTDOWN - Asks HVSRV to logically shutdown HVSERVER SAVE_STORE - Save any pending changes to the attribute store HVSERVER SET_TIME - Sets the HV hardwares time. If the parameter is ommitted, the the time of the machine hvsrv is on is sent. If a date/time is sent, it needs to be in YYYYMMDDHHMMSS format (i.e. October 7, 2002 at 8:43:37PM would be 20021007204337 Events: HVSERVER SHUTDOWN - HVServer is shutting down HVSERVER RECONFIGURE - HVServer has reconfigured itself /* Client messaging */ /* NOTE: Client messaging doesn't involve the HV hardware */ /* in any way. It's simply a way to deliver/broadcast */ /* messages between clients. Other than redistrubting */ /* messages, HVSRV does not act on these messages at all */ MSG SET_LABEL clientName - set optional published name of this client MSG SEND_TO [clientName|ALL] msgType - send message "msgType" to the specified named client (or all clients) with the optional additional parameters (max 99) Events: MSG msgType - A client sent message msgType with it's optional parms /* Script commands */ Script commands allow you to create/edit and execute a series of HVSRV commands. The list of commands is kept on the hvsrv server so it's available to all hvsrv clients. Scripts are kept in a scripts/ directory immediatly under the directory that hvsrv is started in (and where the hvsrv.attr attributes store is located). The directoy will automatically be created, if needed, when the first script is created. Script lines consist of any valid HVSRV command (including other SCRIPT commands). Blank lines and comments are ignored (comments are any line that starts with a #). Scripts also support the following "script only" commands RETURN Cause the current script to stop executing. If this script was invoked from within another script, the other script resumes executing QUIT Causes the current script AND ANY SCRIPTS THAT CALLED the current script to immediatly stop executing. SYSTEM Everything after the SYSTEM command is submitted to a shell to be executed. Any system command and/or shell command can be included. SYSTEM is synchronous - hvsrv will stall and wait for the command to complete before resuming. Be careful about running long executing commands via SYSTEM. SPAWN Much like the SYSTEM command, except the command is immediatly detached and run in background and HVSRV immediatly continues on while that command continues to run. SCRIPT CREATE ScriptID Creates a new script with the passed ScriptID. ScriptIDs can be a mix of letters and numbers but cannot have spaces and should be kept short. Valid ScriptIDs look like SCRIPT1, SCENE_NIGHT, SHUTDOWN_HOUSE, etc. Script IDs are case insensitive and are always internally converted to upper case. If a script by that ID already exists, you'll get an response code of 103 back If the EXISTING keyword is included, then the file for the script ID must already exists, the script must not yet be known to HVSRV. This allows you to create a script external to HVSRV and then add it into HVSRVs internal directory. If a file mathcing the script ID exists but the EXISTING keyword is not supplied, the existing file is trucated/recreated, destroying whatever was in it. SCRIPT DELETE ScriptID Delete the script specified. SCRIPT EXECUTE ScriptID Execute the specified script. Scripts can nest so scripts can invoke other scripts (max limit is currently 32 levels deep). SCRIPT APPEND_LINE ScriptID "the line" Append the contents of "the line" as a single new line to the end of the named script SCRIPT INSERT_LINE ScriptID beforeLine# "the line" Insert "the line" before line number #. Line numbers run from 1 to the maximum # of lines in the script. Specifying a line number greater than the maximum number of lines in the script acts like an APPEND_LINE SCRIPT DELETE_LINE ScriptID [line#|ALL] Delete the line # specified from the script specified. Line #s run from 1 to the # of lines in the script. If you specify a line number less than 1 or greater than the number of lines, the command errors out and doesn't change the script. If you pass a line # of ALL, then all lines in the script are purged. SCRIPT GET_LINE ScriptID [line#|ALL] Causes hvsrv to send the specific line of the script (or all lines) to the client via SCRIPT LINE_STATUS messages SCRIPT SET_ATTR ScriptID attrname value SCRIPT GET_ATTR [ScriptID|ALL] [attrname|ALL] Note: Attribute LINE_COUNT contains the current # of lines for a given ScriptID. You cannot change it's value via SET_ATTR but can retrieve if via GET_ATTR. SCRIPT GET_CONFIG Events: SCRIPT SCRIPT_UPDATE ScriptID [CREATED|DELETED|EXECUTING|EXECUTED|UPDATE [linecount]] EXECUTING is send before the first line of a script is run and EXECUTED is sent after the last line of the script is completed. UPDATE includes a linecount parameter which indicates the # of lines currently in the script. SCRIPT LINE_STATUS ScriptID Line# "the line" SCRIPT ATTR_UPDATE ScriptID attrName attrValue Command Responses: /* Standard response codes */ 100 Command Executed OK 101 Too few parameters 102 Too many parameters 103 Invalid device/object ID 104 Command timedout out 105 Value out of range 106 General comm failure 107 Unknown command 108 Unknown function 109 Unable to perform Automatic Script Execution: HVSRV will attempt to run scripts automatically in respond to certain events occuring. These scripts are entirely optional and if they do not exist, do not result in any performance slowdown. All "automatic" scripts file names start with $ and like any other script, must be registered in HVSRV via SCRIPT CREATE. The following automatic scripts are supported: X10 device transitions -- $X10_dev_state dev is the X10 device ID (i.e. B3 or C10) and state is either ON or OFF. So, if device D8 was turned on, HVSRV would attempt to run a script named $X10_D8_ON I/R defined signal reception -- $IR_irNum irNum is the HV assigned number (0-255) of this I/R signal. So if IR signal #21 was received, HVSRV would attempt to run a script named $IR_21. I/R standard signal reception -- $IR_STD_dev_key dev is the device code of a "standard" I/R signal and key is the key code pressed. HV will report keypresses on standard devices even if those codes are not defined in the HV I/R screen. Note that if a standard code is also defined as a HV I/R code, then both scripts will attempt to execute - the $IR_ script first and the $IR_STD_ script second. If the device code was 104 and the key was 10, HVSRV would attempt to run a script named $IR_STD_104_10 Digital Input transitions -- $DINPUT_inpNum_state inpNum is the HV input number (0-??) and state is the condition of that line (HIGH or LOW). So if digital input #7 transitioned from HIGH to LOW, HVSRV would attempt to run a script named $DINPUT_7_LOW Digital Output transitions -- $DOUTPUT_outNum_state outNum is the HV digitial output number (0-??) and state is the condition of that line (HIGH or LOW). So if digital output #12 transitioned from LOW to HIGH, HVSRV would attempt to run a script named $DOUTPUT_12_HIGH