CM11(3)

📦
version 2.09 · 3 versions
, in alpine 3.22

💅 CM11(3) — the perl X10 controller page, bestie edition

ok so this is a section 3 manual page from the User Contributed Perl Documentation set, and it's literally about talking to an X10 "ActiveHome" controller. buckle up 🎀

✨ NAME ✨

ControlX10::CM11 — a Perl extension for the X10 'ActiveHome' Controller. that's it, that's the vibe 🫶

🌸 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

like, that's the whole teaser trailer right there 😌

💖 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. and this module is the translator bestie — it takes your cute little human-readable commands (eg. 'A2', 'AJ') and turns them into the Interface Communication Protocol that the CM11A actually speaks. no cap, it's giving bilingual icon 🔥

📨 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 (yes, it handles all the awkward small talk for you ✨). 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 — and heads up, that 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]. slay 🔥

  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. fancy, honestly 👑

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's another set of Preset Dim commands 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 ⏰ (it's a whole self-care routine, honestly).

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. no waiting around 💅

  $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 😭 (it's giving "trust the process"). 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) — so like, it still works, but it's lowkey on thin ice 💀

  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 (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.

ok and for the cute sign-off: this whole page comes to you courtesy of perl v5.40.2, dated 2024-02-21, page CM11(3) 💅✨ go forth and dim your lamps, bestie 🫶🌸
📦 where this page comes from