x10-cm17a 0.9.0

data/ext/cm17a_api/cm17a.h

@@ -0,0 +1,63 @@
+/*
+ * Modifications for dual windows/unix compatibility:
+ *   Copyright 2004 by Jim Weirich (jim@weirichhouse.org)
+ *   All rights reserved.
+ *
+ *   See the MIT-LICENSE file included with the distribution for
+ *   details on redistribution rights.
+ */
+
+/*-
+ * Copyright (C) 1999, 2002 Matt Armstrong
+ * All rights reserved.
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions
+ * are met:
+ * 1. Redistributions of source code must retain the above copyright
+ *    notice, this list of conditions and the following disclaimer.
+ * 2. Redistributions in binary form must reproduce the above copyright
+ *    notice, this list of conditions and the following disclaimer in the
+ *    documentation and/or other materials provided with the distribution.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
+ * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+ * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ * ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
+ * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+ * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
+ * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
+ * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
+ * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
+ * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
+ * SUCH DAMAGE.
+ */
+
+#ifndef CM17A_H
+#define CM17A_H
+
+#ifdef CM17A_WIN32
+# include <windows.h>
+# define X10_DEVICE HANDLE
+# define INVALID_X10_DEVICE INVALID_HANDLE_VALUE
+#else
+# define X10_DEVICE int
+# define INVALID_X10_DEVICE -1
+#endif
+
+enum CM17A_COMMAND {
+    CM17A_ON, CM17A_OFF, CM17A_BRIGHTEN, CM17A_DIM
+};
+
+X10_DEVICE cm17a_open_device(const char * device_name);
+
+void cm17a_close_device(X10_DEVICE fd);
+
+void cm17a_command(
+    X10_DEVICE fd,
+    int house,
+    int device,
+    enum CM17A_COMMAND,
+    int steps);
+
+#endif

data/ext/cm17a_api/cm17a_api.c

@@ -0,0 +1,114 @@
+#include "ruby.h"
+#include "cm17a.h"
+
+#include <stdio.h>
+#include <stddef.h>
+#include <ctype.h>
+#include <stdlib.h>
+#include <assert.h>
+
+#if HAVE_FCNTL_H
+#include <fcntl.h>
+#endif
+#if HAVE_SYS_IOCTL_H
+#include <sys/ioctl.h>
+#endif
+#if HAVE_SYS_TIME_H
+#include <sys/time.h>
+#endif
+#if HAVE_SYS_TYPES_H
+#include <sys/types.h>
+#endif
+#if HAVE_UNISTD_H
+#include <unistd.h>
+#endif
+#if HAVE_TERMIO_H
+#include <termio.h>
+#endif
+
+static X10_DEVICE fd;
+
+static VALUE mX10;
+static VALUE mCm17a;
+static VALUE cCm17aController;
+static VALUE eX10Error;
+
+/*
+ * call-seq:
+ *    X10::Cm17a::Controller.new()
+ *    X10::Cm17a::Controller.new(device_name)
+ *
+ * Create a new CM17A controller on the serial device named
+ * +device_name+.  If no device name is given, then a default device
+ * will be selected (<tt>/dev/ttyS0</tt> for linux and <tt>COM1</tt>
+ * for windows).
+ */
+static VALUE cm17a_init(int argc, VALUE *argv, VALUE self)
+{
+    const char * device_name = DEFAULT_SERIAL_DEVICE;
+    if (argc > 0)
+	device_name = STR2CSTR(argv[0]);
+    fd = cm17a_open_device(device_name);
+    if (fd == INVALID_X10_DEVICE)
+	rb_raise(eX10Error, "Unable to open cm17a device '%s'", device_name);
+    return self;
+}
+
+/*
+ * call-seq:
+ *    controller.command(house, unit, command_code, steps)
+ *
+ * Send a command to the CM17A controller.  The X10 unit to get the
+ * address is given by the +house+ code (0-15) and the +unit+ code
+ * (0-15).  The command must be one of the following constants:
+ *
+ * * <tt>X10::Cm17a::ON</tt> -- Turn the device on.
+ * * <tt>X10::Cm17a::OFF</tt> -- Turn the device off.
+ * * <tt>X10::Cm17a::DIM</tt> -- Dim the device by +steps+ steps.
+ * * <tt>X10::Cm17a::BRIGHT</tt> -- Brighten the device by +steps+ steps.
+ *
+ * Note that the unit code is ignored for the <tt>BRIGHT</tt> and
+ * <tt>DIM</tt> commands.  The bright/dim commands will effect the
+ * last addressed unit.
+ */
+static VALUE cm17a_ruby_command(
+    VALUE self,
+    VALUE rhouse,
+    VALUE rdevice,
+    VALUE rcommand,
+    VALUE rsteps)
+{
+    int house = NUM2INT(rhouse);
+    int device = NUM2INT(rdevice);
+    int command = NUM2INT(rcommand);
+    int steps = NUM2INT(rsteps);
+    cm17a_command(fd, house, device, command, steps);
+    return Qnil;
+}
+
+/*
+ * Close the controller device.
+ */
+static VALUE cm17a_close(VALUE self)
+{
+    cm17a_close_device(fd);
+    return Qnil;
+}
+
+void Init_cm17a_api() 
+{
+    mX10 = rb_define_module("X10");
+    mCm17a = rb_define_module_under(mX10, "Cm17a");
+    cCm17aController = rb_define_class_under(mCm17a, "Controller", rb_cObject);
+
+    eX10Error = rb_eval_string("X10::X10Error");
+
+    rb_define_method(cCm17aController, "initialize", cm17a_init, -1);
+    rb_define_method(cCm17aController, "close",      cm17a_close, 0);
+    rb_define_method(cCm17aController, "command",    cm17a_ruby_command, 4);
+
+    rb_define_const(mCm17a, "ON",       INT2NUM(CM17A_ON));
+    rb_define_const(mCm17a, "OFF",      INT2NUM(CM17A_OFF));
+    rb_define_const(mCm17a, "BRIGHTEN", INT2NUM(CM17A_BRIGHTEN));
+    rb_define_const(mCm17a, "DIM",      INT2NUM(CM17A_DIM));
+}

data/ext/cm17a_api/extconf.rb

@@ -0,0 +1,17 @@
+require 'mkmf'
+require 'rbconfig'
+
+have_header("fcntl.h")
+have_header("sys/ioctl.h")
+have_header("sys/time.h")
+have_header("sys/types.h")
+have_header("unistd.h")
+have_header("termio.h")
+
+if Config::CONFIG['arch'] =~ /win32/
+  $defs.push "-DCM17A_WIN32"
+  $defs.push '-DDEFAULT_SERIAL_DEVICE=\\"COM1\\"'
+else
+  $defs.push '-DDEFAULT_SERIAL_DEVICE=\\"/dev/ttyS0\\"'
+end
+create_makefile("cm17a_api")

data/lib/x10.rb

@@ -0,0 +1,102 @@
+#!/usr/bin/env ruby
+
+# = X10 Interface
+#
+# This is a really simple X10 framework for controlling X10 devices.
+#
+# == Example:
+#
+#   require 'x10/cm17a'
+#   lamp = X10.device("a1")
+#   lamp.on
+#   sleep(1)
+#   lamp.off
+#
+# == Controllers and Devices
+#
+# An X10 controller is responsible for interfacing to the X10
+# interface device.  An example is the CM17A firecracker module.
+#
+# == Default Controllers
+#
+# blah blah blah.
+#
+class Class			# :nodoc:
+  def x10_controller?
+    false
+  end
+end
+
+# The X10 Module.  This module provides a root namespace for all X10
+# devices and software.  It also provides a few utility methods for
+# use by the X10 controllers and devices.
+module X10
+  
+  # Error thrown for X10 specific failures.
+  class X10Error < RuntimeError; end
+
+  class << self
+    # Create an X10 device at the given address.  THe address should
+    # be a string specifying the device address is standard X10
+    # nomenclature (e.g. a1 ... a16, b1 ... b16, ... p1 ... p16).
+    def device(address)
+      house, unit = parse_address(address)
+      controller.device(house, unit)
+    end
+    
+    # Return the controller currently in use.  
+    def controller
+      @controller ||= discover_single_controller
+    end
+    
+    # Set the controller to be used to create X10 devices.  If there
+    # is only one X10 controller loaded, then that controller will be
+    # used by default.  Otherwise, the controller must be explicitly
+    # set using this method.
+    def controller=(controller)
+      @controller = controller
+    end
+    
+    # Make a canonical X10 device address from the house number and
+    # unit.  House and unit numbers are zero based.
+    def make_address(house, unit)
+      (house + ?a).chr + (unit+1).to_s
+    end
+
+    # Parse a canonical X10 device adderss into house number and unit
+    # number.  House and unit numbers are zero based.
+    def parse_address(address)
+      address = address.downcase
+      if address !~ /^([a-p])(\d+)$/
+	fail X10::X10Error, "Bad X10 device address [#{address}]"
+      end
+      house_letter = $1
+      unit = $2.to_i - 1
+      
+      if unit < 0 || unit > 15
+	fail X10::X10Error, "Bad X10 device address [#{address}]"
+      end
+      
+      house = address[0] - ?a
+      [house, unit]
+    end
+
+    # If there is only one X10 controller class defined in the object
+    # space, then use it by default.
+    def discover_single_controller
+      controllers = []
+      ObjectSpace.each_object(Class) do |c|
+	controllers << c if c.x10_controller?
+      end
+      case controllers.size
+      when 0
+	fail X10::X10Error, "No X10 Controllers Found"
+      when 1
+	controllers.first.new
+      else
+	fail X10::X10Error, "Multiple X10 Controllers Found"
+      end      
+    end
+  end
+
+end

data/lib/x10/cm17a.rb

@@ -0,0 +1,30 @@
+#!/usr/bin/env ruby
+
+require 'x10'
+require 'cm17a_api'
+
+require 'x10/cm17a_device'
+
+module X10
+
+  module Cm17a
+
+    # The Controller object is the low level interface to the CM17A
+    # Firecracker controller. Client software generally uses the
+    # device level interface rather than the controller directly.
+    class Controller
+
+      # Create an X10::Cm17a::Device on this controller at the given
+      # X10 house and unit address.
+      def device(house, unit)
+	X10::Cm17a::Device.new(house, unit, self)
+      end
+
+      # Yes, this class represents a X10 controller.
+      def self.x10_controller?
+	true
+      end
+    end
+
+  end
+end

data/lib/x10/cm17a_device.rb

@@ -0,0 +1,142 @@
+#!/usr/bin/env ruby
+
+module X10
+
+  module Cm17a
+    
+    # A CM17A device that responds to on/off and adjust (brightness)
+    # commands.
+    #
+    # Typical use:
+    #
+    #  lamp = X10.device("a2")   # Create the device
+    #  lamp.on                   # Turn the lamp on
+    #  lamp.adjust(-0.5)         # Dim the lamp
+    #  lamp.off                  # Turn the lamp off
+    #
+    class Device
+      attr_reader :address, :controller
+      
+      # Create a new X10 device using a CM17A protocol controller.
+      # Such a device can handle on/off commands and simple dim
+      # controls.
+      #
+      # Normally device objects are created through the X10 framework
+      # and not directly by the client software.
+      def initialize(house, unit, controller)
+	@house = house
+	@unit = unit
+	@controller = controller
+	@address = X10.make_address(house, unit)
+      end
+      
+      # Turn the device on.
+      def on
+	@controller.command(@house, @unit, X10::Cm17a::ON, 0)
+	@level = 1.0 if @on == false
+	@on = true
+      end
+      
+      # Turn the device off.
+      def off
+	@controller.command(@house, @unit, X10::Cm17a::OFF, 0)
+	@level = 0.0
+	@on = false
+      end
+      
+      # Adjust the brightness level.
+      #
+      # The level adjustment is given as a number between 0 and 1.  An
+      # adjustment amount of 1 will adjust a completely dim device
+      # into a completely bright device.  An adjustment of 0.5 will be
+      # one half of full range.
+      #
+      # Negative adjustment amounts dim the device.  Positive
+      # adjustments brighten the device.
+      def adjust(amount)
+	steps = steps_for(amount)
+	while steps > 0
+	  step = (steps > 6 ? 6 : steps)
+	  if amount > 0
+	    brighten(step)
+	  else
+	    dim(step)
+	  end
+	  steps -= step
+	end
+	if @level
+	  @level += amount
+	  @level = 0.0 if @level < 0
+	  @level = 1.0 if @level > 1
+	end
+      end
+      
+      private
+      
+      # -- Questionable Methods --------------------------------------
+
+      # The following methods are provided as private methods.  They
+      # are used in testing, but I am uncertain whether they should be
+      # part of the public interface, due to the uncertaintity of
+      # there implementation.
+
+      # Is the device on?
+      #
+      # Since the CM17A protocol is write only, we can't really sense
+      # the on/off state of the device, so we remember the last
+      # commanded state.  This approach has the following
+      # disadvantages:
+      #
+      # * The on/off state is indeterminate until the first command is
+      #   issued.  Asking for the on/off state before the first
+      #   command will throw an X10::X10Error exception.
+      # * If there is more than one device object controlling a single
+      #   physical device, then the on/off state can be invalidated by
+      #   second device object.
+      def on?
+	fail X10::X10Error, "On/Off state is unknown" if @on.nil?
+	@on
+      end
+      
+      # Is the device off?
+      #
+      # See also the discussion in the on? method.
+      def off?
+	! on?
+      end
+      
+      # Return the current brightness level between 0 (very dim) and
+      # 1.0 (very bright) of the device.
+      #
+      # Again, since the CM17A protocol is write only, the same
+      # caveats that apply to on? and off? are also applicable here.
+      #
+      # Furthermore, the real brightness level is a mystery.  The
+      # protocol docs say that stepping the brighteness level changes
+      # it by approximately 5%.  However, there seems to be only 10 or
+      # so steps from completely dim to completely bright.
+      def level
+	fail X10::X10Error, "Level is unknown" if @level.nil?
+	@level
+      end
+      
+      # -- Helper Commands -------------------------------------------
+
+      # Brightness steps for the given amount. 
+      def steps_for(amount)
+	(amount * 10).round.abs
+      end
+      
+      # Send a dim command for the given number of steps.
+      def dim(steps)
+	@controller.command(@house, @unit, X10::Cm17a::DIM, steps)
+      end
+      
+      # Send a brighten command for the given number of steps.
+      def brighten(steps)
+	@controller.command(@house, @unit, X10::Cm17a::BRIGHTEN, steps)
+      end
+
+    end
+  end
+end