CM11(3) User Contributed Perl Documentation CM11(3)NAMEControlX10::CM11 - Perl extension for X10 'ActiveHome' Controller
SYNOPSIS
use ControlX10::CM11;
# $serial_port is an object created using Win32::SerialPort
# or Device::SerialPort depending on OS
# my $serial_port = setup_serial_port('COM10', 4800);
$data = &ControlX10::CM11::receive_buffer($serial_port);
$data = &ControlX10::CM11::read($serial_port, $no_block);
$percent = &ControlX10::CM11::dim_level_decode('GE'); # 40%
&ControlX10::CM11::send($serial_port, 'A1'); # Address device A1
&ControlX10::CM11::send($serial_port, 'AJ'); # Turn device ON
# House Code 'A' present in both send() calls
&ControlX10::CM11::send($serial_port, 'B'.'ALL_OFF');
# Turns All lights on house code B off
DESCRIPTION
The CM11A is a bi-directional X10 controller that connects to a serial
port and transmits commands via AC power line to X10 devices. This
module translates human-readable commands (eg. 'A2', 'AJ') into the
Interface Communication Protocol accepted by the CM11A.
send command
This transmits a two-byte message containing dim and house
information and either an address or a function. Checksum and
acknowledge handshaking is automatic. The command accepts a string
parameter. The first character in the string must be a House Code
in the range [A..P] and the rest of the string determines the type
of message. Intervening whitespace is not currently permitted
between the House Code and the Operation. This may change in the
future.
STRING ALTERNATE_STRING FUNCTION
1..9 Unit Address
A..G Unit Address
J ON Turn Unit On
K OFF Turn Unit Off
L BRIGHT Brighten Last Light Programmed 5%
M DIM Dim Last Light Programmed 5%
O ALL_ON All Units On
P ALL_OFF All Units Off
There are also functions without "shortcut" letter commands:
ALL_LIGHTS_OFF EXTENDED_CODE EXTENDED_DATA
HAIL_REQUEST HAIL_ACK PRESET_DIM1
PRESET_DIM2 STATUS_ON STATUS_OFF
STATUS
Dim and Bright functions can also take a signed value in the range
[-95,-90,...,-10,-5,+5,+10,...,+90,+95].
ControlX10::CM11::send($serial_port,'A1'); # Address device A1
ControlX10::CM11::send($serial_port,'AJ'); # Turn device ON
ControlX10::CM11::send($serial_port,'A-25'); # Dim to 25%
send extended function
Starting in version 2.04, extended commands may be sent to devices
that support the enhanced X10 protocol. If you have one of the
newer (more expensive) LM14A/PLM21 2 way X10 pro lamp modules, you
can set it directly to a specific brightness level using a Preset
Dim extended code.
The 64 extended X10 Preset Dim codes are commanded by appending
"#" to the unit address where "##" is a number between 1 and 63.
ControlX10::CM11::send($serial_port,'A5&P16'); # Dim A5 to 25%
A partial translation list for the most important levels:
&P## % &P## % &P## %
0 0 13 20 44 70
1 2 16 25 47 75
2 4 19 30 50 80
3 5 25 40 57 90
6 10 31 50 61 95
9 15 38 60 63 100
There is another set of Preset Dim commands that are used by some
modules (e.g. the RCS TX15 thermostat). These 32 non-extended
Preset Dim codes can be coded directly, using the following table:
0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 PRESET_DIM1
M N O P C D A B E F G H K L I J
16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 PRESET_DIM2
M N O P C D A B E F G H K L I J
This usage, and the responses assigned to each command, are device
specific. For example, the following commands enable preset value
18:
ControlX10::CM11::send($serial_port,'M4'); # Address thermostat
ControlX10::CM11::send($serial_port,'OPRESET_DIM2'); # Select preset 18
Starting in version 2.07, incoming extended data is also processed.
The first character will be the House Code in the range [A..P].
The next character will be Z, indicating extended data. The
remaining data will be the extended data.
read
This checks for an incoming transmission. It will return "" for no
input. It also tests for a received a "power fail" message (0xa5).
If it detects one, it automatically sends the command/data to reset
the CM11 clock. If the $no_block parameter is FALSE (0, "", or
undef), the read will retry for up to a second at 50 millisecond
intervals. With $no_block TRUE, the read checks one time for
available data.
$data = &ControlX10::CM11::read($serial_port, $no_block);
receive_buffer
This command handles the upload response to an "Interface Poll
Signal" message (0x5a) read from the CM11. The module sends "ready"
(0xc3) and receives up to 10 bytes. The first two bytes are size
and description of the remaining bytes. These are used to decode
the data bytes, but are not returned by the receive_buffer
function. Each of the data bytes is decoded as if it was a send
command from an external CM11 or equivalent external source (such
as an RF keypad).
$data = &ControlX10::CM11::receive_buffer($serial_port);
# $data eq "A2AK" after an external device turned off A2
Multiple house and unit addresses can appear in a single buffer.
if ($data eq "B1BKA2AJ") {
print "B1 off, A2 on\n";
}
dim_level_decode
When the external command includes dim/bright information in
addition to the address and function, the dim_level_decode function
converts that data byte (as processed by the receive_buffer
command) into percent.
$data = &ControlX10::CM11::receive_buffer($serial_port);
# $data eq "A2AMGE" after an external device dimmed A2 to 40%
$percent = &ControlX10::CM11::dim_level_decode("GE");
# $percent == 40
A more complex $data input is possible.
if ($data eq "B1B3B5B7B9BLLE") {
print "House B Inputs 1,3,5,7,9 Brightened to 85%\n";
}
The conversion between text_data and percent makes more sense to
the code than to humans. The following table gives representative
values. Others may be received from a CM11 and will be properly
decoded.
Percent Text Percent Text
0 M7 50 AA
5 ED 55 I6
10 EC 60 NF
15 C7 65 N2
20 KD 70 F6
25 K4 75 DB
30 O7 80 D2
35 OA 85 LE
40 G6 90 PB
45 AF 95 P8
EXPORTS
The send_cm11, receive_cm11, read_cm11, and dim_decode_cm11 functions
are exported by default starting with Version 2.09. They are identical
to the "fully-qualified" names and accept the same parameters. The
export on request tag ":FUNC" is maintained for compatibility (but
deprecated).
use ControlX10::CM11;
send_cm11($serial_port, 'A1'); # send() - address
send_cm11($serial_port, 'AJ'); # send() - function
$data = receive_cm11($serial_port); # receive_buffer()
$data = read_cm11($serial_port, $no_block); # read()
$percent = dim_decode_cm11('GE'); # dim_level_decode()AUTHORS
Bruce Winter bruce@misterhouse.net http://misterhouse.net
CPAN packaging by Bill Birthisel wcbirthisel@alum.mit.edu
http://members.aol.com/bbirthisel
MAILING LISTS
General information about the mailing lists is at:
http://lists.sourceforge.net/mailman/listinfo/misterhouse-users
http://lists.sourceforge.net/mailman/listinfo/misterhouse-announce
To post to this list, send your email to:
misterhouse-users@lists.sourceforge.net
If you ever want to unsubscribe or change your options (eg, switch to
or from digest mode, change your password, etc.), visit your
subscription page at:
http://lists.sourceforge.net/mailman/options/misterhouse-users/$user_id
SEE ALSO
mh can be download from http://misterhouse.net
Win32::SerialPort and Device::SerialPort from CPAN
CM11A Protocol documentation available at http://www.x10.com
perl(1).
COPYRIGHT
Copyright (C) 2000 Bruce Winter. All rights reserved.
This module is free software; you can redistribute it and/or modify it
under the same terms as Perl itself. 30 January 2000.
perl v5.18.2 2000-01-30 CM11(3)