Pi Lights Control

This gem provides an executable and a library for sending radio frequency commands from a Raspberry Pi connected with a 433.920 MHz transmitter to one or more sets of Home Collection Remote Control Christmas Lights (Product #151-3478-6). I have only tested it with the C9 light set, it might work with the C6 light set too.

The gem should be compatible with any Raspberry Pi that has GPIO pins. It has been tested with a 433.920 MHz FS1000A module (pictured below) for Arduino/Raspberry Pi compatible devices. It will not build on MacOS as epoll is only supported on Linux.

Installation

Add this line to your application's Gemfile:

gem 'pi-lights-control'

And then execute:

$ bundle

Or install it yourself as:

$ gem install pi-lights-control

Usage

You can use this gem in two ways, as a Ruby library or as an executable.

Executable Usage

Using the executable from the command line allows you to quickly test the library. After installing the gem, the pi-lights-control binary will be available in your gem bin path.

$ pi-lights-control
NAME
    pi-lights-control - Control Home Collection Lights over GPIO and RF Transmitter

SYNOPSIS
    pi-lights-control [global options] command [command options] [arguments...]

GLOBAL OPTIONS
    --help        - Show this message
    -p, --pin=arg - GPIO pin number for RF Transmitter. Mandatory. (default: none)

COMMANDS
    help    - Shows a list of commands or help for one command
    off     - Turn lights off
    on      - Turn lights on
    program - Run a lights program
    sync    - Sync multiple light sets

The --pin argument is mandatory as all the commands need to know which pin to control. The off, on commands should be self-explanatory.

The sync command will send a code that resets all lights to the same state.

The program command has multiple sub-commands:

$ pi-lights-control help program
NAME
    program - Run a lights program

SYNOPSIS
    pi-lights-control [global options] program blink_steady
    pi-lights-control [global options] program combination
    pi-lights-control [global options] program fast_blink
    pi-lights-control [global options] program fast_fade
    pi-lights-control [global options] program slow_blink
    pi-lights-control [global options] program slow_fade
    pi-lights-control [global options] program steady
    pi-lights-control [global options] program step_fade

DESCRIPTION
    Sends a command to run a specific lights program

COMMANDS
    blink_steady - Blink Steady
    combination  - Combination
    fast_blink   - Fast Blink
    fast_fade    - Fast Fade
    slow_blink   - Slow Blink
    slow_fade    - Slow Fade
    steady       - Steady
    step_fade    - Step Fade

Remember to send the --pin argument!

Library API

Alternatively, you can build applications that integrate this library.

Command Class

The Command class sets up a single GPIO pin as the output control for a transmitter. It is initialized with the Pin number (defaulting to board numbering). It also supports BCM pin numbering.

c = PiLightsControl::Command.new(12) # => :board numbering
c = PiLightsControl::Command.new(10, { numbering: :bcm }) # => :bcm numbering

The Command class will default to repeating codes six times, as that was a reliable count used in testing. You can however change it:

c = PiLightsControl::Command.new(12)
c.repeat_count = 8

Turning the lights on or off can be accessed using simple commands:

c = PiLightsControl::Command.new(12)
c.power_on
c.power_off

Synchronizing lights will cause any light sets that receive the command to reset to a default state, ensuring all lights are in a "fresh slate".

c = PiLightsControl::Command.new(12)
c.sync_lights

There are eight different programs that can be configured for the lights.

c = PiLightsControl::Command.new(12)
c.program(:combination) # Cycles through the other 7 programs
c.program(:steady) # Lights are continuously on
c.program(:slow_blink) # Lights are on 1/2 second, then off 1/2 second
c.program(:fast_blink) # Lights blink on/off much faster
c.program(:slow_fade) # Lights fade from off to on at a slow rate
c.program(:fast_fade) # Lights fade from off to on at a fast rate
c.program(:blink_steady) # Lights blink twice, then are steady for a second or two
c.program(:step_fade) # Lights fade from off to on but at discrete brightness steps instead of a continuous increase/decrease

(Secret: The default remote actually sends 16 different codes! However codes 9–16 trigger the same eight programs as codes 1–8.)

Development

After checking out the repo, run bin/setup to install dependencies. Then, run rake spec to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.

To install this gem onto your local machine, run bundle exec rake install. To release a new version, update the version number in version.rb, and then run bundle exec rake release, which will create a git tag for the version, push git commits and tags, and push the .gem file to rubygems.org.

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/openfirmware/pi-lights-control. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the Contributor Covenant code of conduct.

License

The gem is available as open source under the terms of the MIT License.