rf_rgb 0.8.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 5159ee522b80b0230b43725004ea8f67ad0adbcc
+  data.tar.gz: cb0e2ccab51300a5a69cb7ff004921c277f54fc9
+SHA512:
+  metadata.gz: 0bf1c0a4fe75adce0180ad4dc7a80906c97185499098563f713cb62574097219120831e4b8c71ee2ef924fc50b833dd22a3d08576225a634d5b8354920a8aebc
+  data.tar.gz: 622e71c6041b93d56b351f1d66b2539a9c37a7f7ffb3dde64128b8ca72c068066e3f13e7fee2faabbcb39c539d0c135d8dc619bfc6da440ec4653f44a32f2bfc

data/.gitignore

@@ -0,0 +1,14 @@
+/.bundle/
+/.yardoc
+/Gemfile.lock
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/
+
+# rspec failure tracking
+.rspec_status
+
+.idea/

data/.rspec

@@ -0,0 +1,2 @@
+--format documentation
+--color

data/.ruby-version

@@ -0,0 +1 @@
+2.4.1

data/.travis.yml

@@ -0,0 +1,5 @@
+sudo: false
+language: ruby
+rvm:
+  - 2.3.3
+before_install: gem install bundler -v 1.15.1

data/Gemfile

@@ -0,0 +1,4 @@
+source "https://rubygems.org"
+
+# Specify your gem's dependencies in rf_rgb.gemspec
+gemspec

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2017 Michael Dungan
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,101 @@
+# RfRgb
+
+### What it is
+Some code to allow for interacting with Topre Realforce RGB keyboards. The software provided by
+the manufacturer only supports Windows.
+
+### What it isn't
+This isn't intended to be a full replacement for the Realforce software - just some basic classes that can
+be used as building blocks.
+
+## Requirements
+1. Ruby 2.3+. Earlier versions of Ruby may work, but are not supported.
+1. [libusb](http://libusb.info) 1.0.0 or greater. The old version 0.1 is not supported.
+
+## Installation
+
+Add this line to your application's `Gemfile`:
+
+```ruby
+gem 'rf_rgb'
+```
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself with:
+
+    $ gem install rf_rgb
+
+## Usage
+
+```ruby
+keyboard = nil
+begin
+ # .new without an arg will automatically find and initialize the first Realforce RGB keyboard it finds.
+ # Keyboard cannot be used at this point, as it's owned by this program until .release_to_os is called.
+  keyboard = RfRgb::Keyboard.new
+  
+  keyboard.effect_rainbow_wave
+  # keyboard.effect_shooting_star("\xff\x00\xff", RfRgb::Protocol::INTERVAL_6)
+  # keyboard.effect_pressed_key("\xaa\xee\xff")
+  # keyboard.disable_effect
+  keyboard.brightness = RfRgb::Protocol::BRIGHTNESS_LOW
+  keyboard.actuation_height = RfRgb::Protocol::HEIGHT_22
+  keyboard.swap_caps_ctrl
+  keyboard.save
+ensure
+  keyboard&.release_to_os
+end
+```
+
+OR
+
+```ruby
+RfRgb::Keyboard.run_and_release do |keyboard|
+  keyboard.effect_rainbow_wave
+  keyboard.brightness = RfRgb::Protocol::BRIGHTNESS_LOW
+  keyboard.actuation_height = RfRgb::Protocol::HEIGHT_22
+  keyboard.swap_caps_ctrl
+  keyboard.save
+end
+```
+
+See `lib/rf_rgb/keyboard.rb` for effects and arguments, and
+`lib/rf_rgb/protocol.rb` for any needed constants.
+
+On Ubuntu Linux at least, some udev configuration was necessary to be able to run as a non-root user,
+and prevent `usbhid` from taking the device over. If you're in that boat, try this:
+
+1. create `/etc/udev/rules.d/99-topre.rules` with the following content:
+    ```
+    SUBSYSTEM=="usb", ATTRS{idVendor}=="0853", ATTRS{idProduct}=="013a", MODE="0666", GROUP="plugdev"
+    ATTRS{idVendor}=="0853", ATTRS{idProduct}=="013a", RUN="/bin/sh -c 'echo -n $kernel >/sys/bus/usb/drivers/usbhid/unbind'"
+    ```
+1. Add your user to the `plugdev` group: `sudo usermod -a -G plugdev $USER`
+1. (Probably) log out and back in, so the new group is applied to your user
+1. Unplug and re-plug the keyboard into a USB slot.
+
+## Protocol Notes
+
+When commands are sent from the host to the OUT endpoint, there is a response that can
+be read from IN endpoint #3, but this module ignores these responses completely at
+time of writing.
+
+Some effects have a User 1-3 setting in the Windows UI. It's not clear what these
+are actually for, and are ignored in this module for now.
+
+## 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](https://rubygems.org).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/xxx/rf_rgb.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,6 @@
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task :default => :spec

data/bin/console

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+
+require "bundler/setup"
+require "rf_rgb"
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+# require "pry"
+# Pry.start
+
+require "irb"
+IRB.start(__FILE__)

data/bin/setup

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/lib/rf_rgb/keyboard.rb

@@ -0,0 +1,136 @@
+module RfRgb
+  class Keyboard
+    VENDOR_ID = 0x0853
+    PRODUCT_ID = 0x013a
+    ENDPOINT = 0x04
+    INTERFACE = 0
+
+    attr_reader :device, :handle
+
+    def self.all
+      context = LIBUSB::Context.new
+      context.debug = LIBUSB_DEBUG
+      context.devices(idVendor: VENDOR_ID, idProduct: PRODUCT_ID)
+    end
+
+    def self.first
+      all.first
+    end
+
+    def self.run_and_release(device = RfRgb::Keyboard.first, &block)
+      keyboard = nil
+      begin
+        keyboard = new(device)
+        yield keyboard
+      ensure
+        keyboard&.release_to_os
+      end
+    end
+
+    def initialize(device = RfRgb::Keyboard.first)
+      @device = device
+      @handle = initialize_device(device)
+    end
+
+    def save
+      send_message RfRgb::Protocol.save_changes
+    end
+
+    def release_to_os
+      return unless @handle
+      @handle.release_interface(INTERFACE)
+      @handle.close
+    end
+
+    def disable_effect
+      reset_effect
+      send_message RfRgb::Protocol.disable_effects
+    end
+
+    def effect_rainbow_wave
+      reset_effect
+      send_message RfRgb::Protocol.rainbow_wave
+    end
+
+    def effect_pressed_key(rgb_hex)
+      reset_effect
+      send_message RfRgb::Protocol.pressed_key_lighting(rgb_hex)
+    end
+
+    def effect_pressed_key_with_backlight(rgb_hex)
+      reset_effect
+      send_message RfRgb::Protocol.pressed_key_lighting_with_backlight(rgb_hex)
+    end
+
+    def effect_shooting_star(rgb_hex, interval)
+      reset_effect
+      send_message RfRgb::Protocol.shooting_star(rgb_hex, interval)
+    end
+
+    def effect_demo_mode
+      reset_effect
+      send_message RfRgb::Protocol.demo_mode
+    end
+
+    def effect_random_lights
+      reset_effect
+      send_message RfRgb::Protocol.random_lights
+    end
+
+    def effect_color_bar
+      reset_effect
+      send_message RfRgb::Protocol.color_bar
+    end
+
+    # There's more to key locking than just this, but the way it's done is odd
+    # and is among the lowest of priorities on this project.
+    def lock_keys
+      send_message RfRgb::Protocol.key_lock
+    end
+
+    def unlock_keys
+      send_message RfRgb::Protocol.key_unlock
+    end
+
+    def brightness=(new_brightness)
+      send_message RfRgb::Protocol.change_brightness(new_brightness)
+    end
+
+    def actuation_height=(new_height)
+      send_message RfRgb::Protocol.change_actuation_height_all(new_height)
+    end
+
+    def swap_caps_ctrl
+      send_message RfRgb::Protocol.swap_caps_ctrl
+    end
+
+    def unswap_caps_ctrl
+      send_message RfRgb::Protocol.unswap_caps_ctrl
+    end
+
+    private
+
+    # I don't know what this actually does, but the Windows software
+    # sends this message before any effect change.
+    def reset_effect
+      send_message RfRgb::Protocol.reset_effect
+    end
+
+    def initialize_device(device)
+      handle = device.open
+      handle.auto_detach_kernel_driver = true
+      handle.set_configuration(1) rescue nil
+      handle.claim_interface(INTERFACE)
+      # handle.clear_halt endpoint0
+      handle
+    end
+
+    def send_message(data)
+      @handle.interrupt_transfer(
+        endpoint: ENDPOINT,
+        dataOut: data,
+        timeout: 10_000
+      )
+    end
+  end
+end

data/lib/rf_rgb/protocol.rb

@@ -0,0 +1,96 @@
+module RfRgb
+  module Protocol
+    BRIGHTNESS_HIGH   = "\x00".freeze
+    BRIGHTNESS_MEDIUM = "\x01".freeze
+    BRIGHTNESS_LOW    = "\x02".freeze
+
+    # Actuation heights
+    HEIGHT_15 = "\x00".freeze
+    HEIGHT_22 = "\x01".freeze
+    HEIGHT_30 = "\x02".freeze
+
+    # Only the Shooting Star effect uses these.
+    INTERVAL_0 = "\x00".freeze # slowest, ~12 seconds
+    INTERVAL_1 = "\x01".freeze
+    INTERVAL_2 = "\x02".freeze
+    INTERVAL_3 = "\x03".freeze
+    INTERVAL_4 = "\x04".freeze
+    INTERVAL_5 = "\x05".freeze
+    INTERVAL_6 = "\x06".freeze
+    INTERVAL_7 = "\x07".freeze
+    INTERVAL_8 = "\x08".freeze
+    INTERVAL_9 = "\x09".freeze # fastest, ~1 second
+
+    # I'm not actually clear on the point of users, but here they are.
+    USER_0 = "\x00".freeze
+    USER_1 = "\x01".freeze
+    USER_2 = "\x02".freeze
+    USER_3 = "\x03".freeze
+
+    def self.reset_effect
+      "\xaa\xaa\x60".force_encoding(Encoding::BINARY).freeze
+    end
+
+    def self.save_changes
+      "\xaa\xaa\x04".force_encoding(Encoding::BINARY).freeze
+    end
+
+    def self.pressed_key_lighting(rgb_hex, user = :user0)
+      # byte number 6 (just before rgb) determines user. 0x00-0x03
+      "\xaa\xaa\x62\x00\x04\x00#{rgb_hex}".force_encoding(Encoding::BINARY).freeze
+    end
+
+    # Backlight color can't be changed AFAICT. Always white.
+    def self.pressed_key_lighting_with_backlight(rgb_hex, user = :user0)
+      "\xaa\xaa\x63\x00\x04\x00#{rgb_hex}".force_encoding(Encoding::BINARY).freeze
+    end
+
+    def self.rainbow_wave
+      "\xaa\xaa\x61".force_encoding(Encoding::BINARY).freeze
+    end
+
+    def self.shooting_star(rgb_hex, interval, user = USER_0)
+      "\xaa\xaa\x64\x00\x05\x00#{interval}#{rgb_hex}".force_encoding(Encoding::BINARY).freeze
+    end
+
+    def self.demo_mode
+      "\xaa\xaa\x66".force_encoding(Encoding::BINARY).freeze
+    end
+
+    def self.random_lights
+      "\xaa\xaa\x67".force_encoding(Encoding::BINARY).freeze
+    end
+
+    def self.color_bar
+      "\xaa\xaa\x68".force_encoding(Encoding::BINARY).freeze
+    end
+
+    def self.disable_effects
+      "\xaa\xaa\x69".force_encoding(Encoding::BINARY).freeze
+    end
+
+    def self.key_lock
+      "\xaa\xaa\x82\x00\x01\x01".force_encoding(Encoding::BINARY).freeze
+    end
+
+    def self.key_unlock
+      "\xaa\xaa\x82\x00\x01\x00".force_encoding(Encoding::BINARY).freeze
+    end
+
+    def self.change_brightness(new_brightness)
+      "\xaa\xaa\x42\x00\x01#{new_brightness}".force_encoding(Encoding::BINARY).freeze
+    end
+
+    def self.change_actuation_height_all(new_height)
+      "\xaa\xaa\x20\x00\x01#{new_height}".force_encoding(Encoding::BINARY).freeze
+    end
+
+    def self.swap_caps_ctrl
+      "\xaa\xaa\x84\x00\x01\x01".force_encoding(Encoding::BINARY).freeze
+    end
+
+    def self.unswap_caps_ctrl
+      "\xaa\xaa\x84\x00\x01\x00".force_encoding(Encoding::BINARY).freeze
+    end
+  end
+end

data/lib/rf_rgb/version.rb

@@ -0,0 +1,3 @@
+module RfRgb
+  VERSION = '0.8.0'.freeze
+end

data/lib/rf_rgb.rb

@@ -0,0 +1,9 @@
+require 'libusb'
+require 'rf_rgb/keyboard'
+require 'rf_rgb/protocol'
+require 'rf_rgb/version'
+
+module RfRgb
+  # 0 is silent, 4 is spewy.
+  LIBUSB_DEBUG = ENV['LIBUSB_DEBUG'] || 3
+end

data/rf_rgb.gemspec

@@ -0,0 +1,38 @@
+# coding: utf-8
+lib = File.expand_path("../lib", __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require "rf_rgb/version"
+
+Gem::Specification.new do |spec|
+  spec.name          = "rf_rgb"
+  spec.version       = RfRgb::VERSION
+  spec.authors       = ["mpd"]
+  spec.email         = ["mpd@jesters-court.net"]
+
+  spec.summary       = %q{Some classes to interact with Topre Realforce RGB keyboards.}
+  spec.description   = %q{Some classes to allow for read and writing key colors and actuation heights on Topre Realforce RGB keyboards}
+  spec.homepage      = "https://github.com/xxx/rf_rgb"
+  spec.license       = "MIT"
+
+  # Prevent pushing this gem to RubyGems.org. To allow pushes either set the 'allowed_push_host'
+  # to allow pushing to a single host or delete this section to allow pushing to any host.
+  if spec.respond_to?(:metadata)
+    spec.metadata["allowed_push_host"] = "https://rubygems.org"
+  else
+    raise "RubyGems 2.0 or newer is required to protect against " \
+      "public gem pushes."
+  end
+
+  spec.files         = `git ls-files -z`.split("\x0").reject do |f|
+    f.match(%r{^(test|spec|features)/})
+  end
+  spec.bindir        = "exe"
+  spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  spec.add_dependency "libusb", "~> 0.6"
+
+  spec.add_development_dependency "bundler", "~> 1.15"
+  spec.add_development_dependency "rake", "~> 10.0"
+  spec.add_development_dependency "rspec", "~> 3.0"
+end

metadata

@@ -0,0 +1,117 @@
+--- !ruby/object:Gem::Specification
+name: rf_rgb
+version: !ruby/object:Gem::Version
+  version: 0.8.0
+platform: ruby
+authors:
+- mpd
+autorequire: 
+bindir: exe
+cert_chain: []
+date: 2017-07-19 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: libusb
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.6'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.6'
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.15'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.15'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+description: Some classes to allow for read and writing key colors and actuation heights
+  on Topre Realforce RGB keyboards
+email:
+- mpd@jesters-court.net
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- ".rspec"
+- ".ruby-version"
+- ".travis.yml"
+- Gemfile
+- LICENSE.txt
+- README.md
+- Rakefile
+- bin/console
+- bin/setup
+- lib/rf_rgb.rb
+- lib/rf_rgb/keyboard.rb
+- lib/rf_rgb/protocol.rb
+- lib/rf_rgb/version.rb
+- rf_rgb.gemspec
+homepage: https://github.com/xxx/rf_rgb
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.6.12
+signing_key: 
+specification_version: 4
+summary: Some classes to interact with Topre Realforce RGB keyboards.
+test_files: []