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 <m@perlmeister.com>

cpanm X10::Home

perl -MCPAN -e shell
install X10::Home