ruby-blinkstick 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 85096144b5f714b5b78ef9d96a9ec8704cc01773d70939eb40580039840ccd06
+  data.tar.gz: b376b8f3977442266b3073228f907207768753ed5c67760358b3f675190851e6
+SHA512:
+  metadata.gz: 119497122ba34c45749af7168fe0575354ca2ebbe441a0bf959e912991d32ea56631b6eca2a7c470c6f412548aededbdf12327195bff3d1530cbdd13e1fadfd4
+  data.tar.gz: 2c465dfb6b3e0db1948609c1dc973144aad7db58d74cd1613852b7dc2b3467d3cd861070fb2f279b0f4dc11e822c939f6c327eaf9cb40ccd9c3efe579a41d5f0

data/CAPABILITIES.md

@@ -0,0 +1,64 @@
+# Capabilities
+
+0.0.1 is a placeholder and supports nothing. This table is the checklist for the implementation.
+
+What the BlinkStick Nano and Square can do, and what this gem supports so far. Back to the
+[README](README.md).
+
+This file is updated whenever a feature lands.
+
+Key: **yes** supported, **no** not yet, **n/a** the device does not have it, **unverified** the
+device may have it but it has not been confirmed on hardware.
+
+## Device features
+
+Features built into the BlinkStick firmware.
+
+| Feature | Nano | Square | Supported since | Notes |
+|---|---|---|---|---|
+| List attached sticks | no | no | not yet | Enumerate every attached stick |
+| Open the first stick or one by serial | no | no | not yet | Open the first stick found, or a stick by its serial |
+| Name a stick and open it by name | no | no | not yet | Store a name, read it back, open and list sticks by name. Stored in info block 1 |
+| Several sticks open at once | no | no | not yet | |
+| Serial and firmware version | no | no | not yet | Read from the device info |
+| Manufacturer and product strings | no | no | not yet | Read from the device info |
+| Set all LEDs | no | no | not yet | Set every LED to one colour, or turn them off |
+| Set one LED | no | no | not yet | Set a single LED by index, using report 5 |
+| Set every LED at once | no | no | not yet | Write a whole frame in one report |
+| Read LED values back | no | no | not yet | Read the whole frame or a single LED |
+| Info blocks 1 and 2 | no | no | not yet | Read and write the info blocks. 32 bytes each, stored in EEPROM |
+| Set one LED directly (report 5) | no | no | not yet | `[5, channel, index, R, G, B]`, RGB order (the frame is GRB). Works in modes 2 and 3. The channel byte is ignored and the index is not range checked |
+| Read device mode (report 4) | no | no | not yet | `[4, mode]`. Both read mode 2 |
+| Set device mode (report 4) | no | no | not yet | Stored in EEPROM, blocks about 50 ms, skipped when the mode is unchanged, takes effect without a replug. 2 to 3 to 2 verified on both |
+| Mode 2, WS2812 | no | no | not yet | The mode both are in, and the one every LED feature here needs. Probably the factory default |
+| Mode 3, WS2812 mirror | no | no | not yet | Changes only report 1, whose colour goes to every LED. Reports 5 and 6 behave as in mode 2 |
+| Modes 0 and 1, normal and inverse | n/a | n/a | n/a | For the BlinkStick Pro's RGB outputs. Upstream reports a Nano in mode 1 going dark until replugged. Setting the mode refuses them |
+| Set LED 0, or every LED in mode 3 (report 1) | no | no | not yet | `[1, R, G, B]`, RGB order. Used by other BlinkStick software. Setting LED 0 or all LEDs does the same job in either mode |
+| Report 10 | n/a | unknown | no | Square only, 2 bytes, reads 00 00. Undocumented; waiting on the manufacturer |
+| LED count setting (report 0x81) | n/a | n/a | n/a | BlinkStick Flex only |
+| 16, 32 and 64 LED frames (reports 7 to 9) | n/a | n/a | n/a | For longer strips |
+
+## Host features
+
+Features this gem adds in software. They work the same on every supported device.
+
+| Feature | Supported since | Notes |
+|---|---|---|
+| Model detection | not yet | From the serial and USB release number |
+| Colour from hex or `r,g,b` | not yet | Parse a colour from hex, with or without the `#`, or `r,g,b` |
+| Brightness limit | not yet | Cap the brightness of every colour written |
+| Blink, pulse and morph | not yet | Cancellable |
+| CSS colour names | not yet | All 148 from CSS Color Level 4 |
+| List CSS colour names | not yet | Sorted, for shell completion |
+| Colour as hex | not yet | Lower case `#rrggbb` |
+| Random colour | not yet | Any colour, or a vivid one |
+| Inverse colours | not yet | Invert a colour or the whole frame. Not the firmware inverse mode |
+| Reconnect after unplug | not yet | Automatic, repaints the last frame |
+
+## Platforms
+
+| Platform | Supported since |
+|---|---|
+| macOS | not yet |
+| Linux | not yet |
+| Windows | no |

data/CHANGELOG.md

@@ -0,0 +1,13 @@
+# Changelog
+
+All notable changes to this project are recorded here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and the project uses
+[semantic versioning](https://semver.org/).
+
+## [Unreleased]
+
+## [0.0.1] - 2026-10-28
+
+### Added
+
+- Reserved the `ruby-blinkstick` gem name. This release defines `Blinkstick::VERSION` and nothing else.

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Keith Bawden
+
+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,63 @@
+# ruby-blinkstick
+
+[![CI](https://github.com/bawdo/ruby-blinkstick/actions/workflows/ci.yml/badge.svg)](https://github.com/bawdo/ruby-blinkstick/actions/workflows/ci.yml)
+[![Gem](https://img.shields.io/gem/v/ruby-blinkstick)](https://rubygems.org/gems/ruby-blinkstick)
+[![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/bawdo/ruby-blinkstick/badge)](https://scorecard.dev/viewer/?uri=github.com/bawdo/ruby-blinkstick)
+[![codecov](https://codecov.io/gh/bawdo/ruby-blinkstick/branch/main/graph/badge.svg)](https://codecov.io/gh/bawdo/ruby-blinkstick)
+
+Drive BlinkStick Nano and Square USB LEDs from Ruby.
+
+This gem is unofficial. It is not made by, or affiliated with, Agile Innovative, the makers
+of BlinkStick.
+
+## Status
+
+`0.0.1` reserves the gem name and does nothing else. The implementation will port
+[go-blinkstick](https://github.com/bawdo/go-blinkstick). See [CAPABILITIES.md](CAPABILITIES.md)
+for the features it will cover.
+
+## Install
+
+```sh
+gem install ruby-blinkstick
+```
+
+Or in a Gemfile:
+
+```ruby
+gem "ruby-blinkstick"
+```
+
+The gem is called `ruby-blinkstick` because `blinkstick` was already taken on rubygems.org, so
+you `require "blinkstick"` and use the `Blinkstick` module.
+
+## Requirements
+
+- Ruby 3.4 or later.
+
+## Linux
+
+BlinkStick devices are owned by root by default, so opening one needs a udev rule. Install the
+one shipped with this gem:
+
+```sh
+sudo cp udev/60-blinkstick.rules /etc/udev/rules.d/
+sudo udevadm control --reload-rules
+sudo udevadm trigger
+```
+
+Then unplug and replug the stick (or reboot). This grants access to whoever is logged in at the
+desktop (via systemd-logind's `uaccess`), not a udev group, so no group membership or new login
+session is needed beyond replugging the device.
+
+The rule only grants the `hidraw` node, which is all this gem uses. If you use a tool that talks
+to the stick through libusb (such as the official Python `blinkstick` package), add this line to
+the rule as well:
+
+```
+SUBSYSTEM=="usb", ATTR{idVendor}=="20a0", ATTR{idProduct}=="41e5", TAG+="uaccess"
+```
+
+## Licence
+
+MIT. See [LICENSE](LICENSE).

data/lib/blinkstick/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Blinkstick
+  VERSION = "0.0.1"
+end

data/lib/blinkstick.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+require_relative "blinkstick/version"
+
+# 0.0.1 is a placeholder that reserves the gem name and does nothing.
+module Blinkstick
+end

data/udev/60-blinkstick.rules

@@ -0,0 +1,13 @@
+# Grants the logged-in desktop user access to BlinkStick hidraw nodes, so
+# this gem can open them without root or a udev group. It does not grant
+# raw USB access; see README.md#linux if another tool needs that.
+#
+# Install:
+#   sudo cp udev/60-blinkstick.rules /etc/udev/rules.d/
+#   sudo udevadm control --reload-rules
+#   sudo udevadm trigger
+#
+# Then unplug and replug the stick (or reboot). See README.md#linux for
+# details.
+
+KERNEL=="hidraw*", ATTRS{idVendor}=="20a0", ATTRS{idProduct}=="41e5", TAG+="uaccess"

metadata

@@ -0,0 +1,53 @@
+--- !ruby/object:Gem::Specification
+name: ruby-blinkstick
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+platform: ruby
+authors:
+- Keith Bawden
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies: []
+description: Drive BlinkStick Nano and Square USB LEDs from Ruby. Unofficial, and
+  not affiliated with Agile Innovative. 0.0.1 is a placeholder that reserves the gem
+  name.
+email:
+- keith@arrix.com.au
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CAPABILITIES.md
+- CHANGELOG.md
+- LICENSE
+- README.md
+- lib/blinkstick.rb
+- lib/blinkstick/version.rb
+- udev/60-blinkstick.rules
+homepage: https://github.com/bawdo/ruby-blinkstick
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://github.com/bawdo/ruby-blinkstick
+  changelog_uri: https://github.com/bawdo/ruby-blinkstick/blob/main/CHANGELOG.md
+  bug_tracker_uri: https://github.com/bawdo/ruby-blinkstick/issues
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.4'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: Drive BlinkStick Nano and Square USB LEDs from Ruby.
+test_files: []