###################################################################### X10::Home 0.03 ###################################################################### NAME X10::Home - Configure X10 for your Home SYNOPSIS # System-wide /etc/x10.conf Configuration File module: ControlX10::CM11 device: /dev/ttyS0 receivers: - name: bedroom_lights code: K15 desc: Bedroom Lights - name: dsl_router code: ... # In your application: use X10::Home; my $x10 = X10::Home->new(); # Address services by name $x10->send("bedroom_lights", "on"); DESCRIPTION "X10::Home" lets you set parameters of all your home X10 devices in a single configuration file. After that's done, applications can access them by name and without worrying about details like "house codes", "unit codes", "serial ports", X10 commands and other low-level details. "X10::Home" also maintains a status database to remember the assumed status of cheap X10 devices without a feedback mechanism. Usage After a one-time setup of the "x10.conf" file, to switch the bedroom lights on, simply use use X10::Home; my $x10->X10::Home->new(); $x10->send("bedroom_lights", "on"); and $x10->send("bedroom_lights", "off"); to switch them off again. "X10::Home" uses the "ControlX10::CM11" or "ControlX10::CM17" CPAN modules under the hood to send actual X10 commands via the computer's serial port. Configuration File Upon initialization, "X10::Home" will search a configuration file in the following locations (in the order listed): * If "X10::Home::new()" gets called with the "conf_file" parameter set, the configuration will be read from "conf_file". * "~/.x10.conf" (in the user's local home directory) if present * "/etc/x10.conf" if present The configuration file is written in YAML format and looks like this: # /etc/x10.conf Configuration File module: ControlX10::CM11 device: /dev/ttyS0 baudrate: 4800 receivers: - name: bedroom_lights code: K15 desc: Bedroom Lights - name: dsl_router code: K16 desc: DSL Router The "module" parameter specifies which X10 low-level module to use, "ControlX10::CM11" or "ControlX10::CM17", it defaults to "ControlX10::CM11". The "device" parameter specifies the device entry of the serial port to use, it defaults to "/dev/ttyS0". This can be "/dev/ttyS4" or "/dev/ttyS5" if a serial PCI card gets plugged into the computer. The "baudrate" is the baud rate to be used to communicate over the serial port. It defaults to 4800. The "receivers" parameter specifies an array of receivers. The reason why this is an array an not a hash is that certain applications like to display all available receivers in a predefined order. Receivers are hashed internally by "X10::Home" by their "name" entries for quick lookups, though. METHODS "new()" Constructor. Optional parameters are "conf_file" to specify the path to a special x10.conf file instead of the natural search order of system x10.conf files. "db_file" to indicate that "X10::Home" should be maintaining a persistent data store with assumed device status. Defaults to "/tmp/x10.status". To check/manipulate the maintained status, see "db_status" below. "send($name, $action)" Sends a message to the specified X10 receiver. Uses locking (see "lock/unlock" below) internally to make sure that no other X10 commands are sent over the wire by this sender at the same time, which would confuse the receivers. "lock()" Aquire an exclusive lock. "unlock()" Release the previously acquired exclusive lock. "db_status($field, [$value])" For persistent storage of assumed device status, "X10::Home" maintains a file-based data store (if the constructor is called with the "db_file" parameter set to a persistent datastore location). If a device gets switched on or off, "X10::Home" will make a note of that in the data store. To query the (assumed) status of a device, use my $x10 = X10::Home( db_file => "/tmp/x10.status" ); if( $x10->db_status("bedroom_lights") eq "on" ) { print "Bedroom lights are on!\n"; } Sample Applications The "eg" directory contains a command line application "x10" which allows you to run X10 commands from the command line, e.g. $ x10 office_lights on or $ x10 office_lights status on The "eg" directory also contains an AJAXed X10 web application, check out "x10.cgi" and read the installation instructions at the top of the file. LEGALESE Copyright 2007 by Mike Schilli, all rights reserved. This program is free software, you can redistribute it and/or modify it under the same terms as Perl itself. AUTHOR 2007, Mike Schilli