ruby_home

ruby_home is an implementation of the HomeKit Accessory Protocol (HAP) to create your own HomeKit accessory in Ruby. HomeKit is a set of protocols and libraries to access devices for home automation. A non-commercial version of the protocol documentation is available on the HomeKit developer website.

To use ruby_home, you will need to install libsodium:

At least version 1.0.9 is required.

For OS X users, libsodium is available via homebrew and can be installed with:

brew install libsodium

For Debian users, libsodium is available via apt:

sudo apt-get install libsodium-dev

Add this line to your application's Gemfile:

gem 'ruby_home'

And then execute:

$ bundle

Or install it yourself with:

$ gem install ruby_home

Create a fan with an on/off switch:

require 'ruby_home'

accessory_information = RubyHome::ServiceFactory.create(:accessory_information)
fan = RubyHome::ServiceFactory.create(:fan)

fan.on.after_update do |updated_value|
  if updated_value
    puts "Fan switched on"
  else
    puts "Fan switched off"
  end
end

RubyHome.run

The following example services are available:

• Air quality sensor
• Carbon dioxide sensor
• Carbon monoxide sensor
• Contact sensor
• Humidity sensor
• Leak sensor
• Light sensor
• Motion sensor
• Occupancy sensor
• Smoke sensor
• Temperature sensor

• Air purifier
• Battery service
• Door
• Fan
• Fan V2
• Garage door opener
• Heater cooler
• Humidifier dehumidifier
• Lightbulb
• Lock mechanism
• Outlet
• Security system
• Switch
• Television
• Thermostat
• Window
• Window covering

The configuration options can be set by using the configure helper:

RubyHome.configure do |c|
  c.discovery_name = 'My Home'
end

The following is the full list of available configuration options:

RubyHome tries to provide sane defaults for all services. Customization of any of the options is possible.

require 'ruby_home'

accessory_information = RubyHome::ServiceFactory.create(:accessory_information,
  firmware_revision: '4.3.18421',
  manufacturer: 'Fake Company',
  model: 'BSB001',
  name: 'Kickass fan bridge',
  serial_number: 'AB1-UK-A123456',
  category_identifier: :fan
)

fan = RubyHome::ServiceFactory.create(:fan,
  on: false,
  rotation_speed: 50,
  rotation_direction: 1,
  firmware_revision: '105.0.21169',
  manufacturer: 'Fake Company',
  model: 'LWB006',
  name: 'Kickass fan',
  serial_number: '123-UK-A12345'
)

fan.on.after_update do |updated_value|
  if updated_value
    puts "Fan switched on"
  else
    puts "Fan switched off"
  end
end

RubyHome.run

If you have a service with characteristics that can be changed outside of Ruby Home, you'll want to keep Ruby Home in sync with these modifications. Otherwise, the characteristics current value won't correspond with reality. The simplest way to do this is a background job that periodically polls the devices current status and updates the corresponding characteristics value if it's changed.

Given a fan which can be switched on / off with a remote control, which has a JSON API endpoint at http://example.org/fan_status.json that returns its current status { "on": true } or { "on": false }, we can spawn a thread that keeps polling the fans current status and if it's changed update our fan service "on" characteristic.

require 'json'
require 'open-uri'
require 'ruby_home'

fan = RubyHome::ServiceFactory.create(:fan)

Thread.new do
  def fetch_fan_status
    json = JSON.load(open("http://example.org/fan_status.json"))
    json["on"]
  end

  loop do
    sleep 10 # seconds

    current_fan_status = fetch_fan_status

    unless fan.on == current_fan_status
      fan.on = current_fan_status
    end
  end
end

RubyHome.run

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.

Bug reports and pull requests are welcome on GitHub at https://github.com/karlentwistle/ruby_home.