blinkytape-orb 0.0.1 → 0.0.2

checksums.yaml

@@ -1,15 +1,15 @@
 ---
 !binary "U0hBMQ==":
   metadata.gz: !binary |-
-    M2U5ZTcxOWE3OGMxYTllMWY1YTMzNTY4MGZjMzJkYzRmNDdiNjk3Yg==
+    NmMxYTllNTkyNTllOTk2ZTgwMWQxYTgzZGEwODFkNGI0NjRhMGFiYw==
   data.tar.gz: !binary |-
-    MTA2NDAwNjY4YTZjNWM4MjZlNDBkMTcxNjU3NzkxOGEyYzliNDY3Mg==
+    MTg3NDhlZGFiZGM4NzBlNzgyN2MyOTU0ODYwOTlkMjAwNmFjMTlkMA==
 !binary "U0hBNTEy":
   metadata.gz: !binary |-
-    ZWUzZTk1YzEwYWMxMzJiMGJiZTU0NjdjMjFiMjRjOTdmOGU2Zjk3NDkwM2U2
-    MTExY2U4ODdlZDFhYjE4NTNlYTcwMTQ5NWMxOTRiZjY0OWVlMDFhMGRiNjNj
-    NjYzYTY4YTk4ZmQ4ZDc1OTA2N2IxMjZlOTlmMTRiYzg0ZTU4Y2E=
+    ZTUyNDAwYjJiNjI1OWNjYjllYThlMTNmMWVhMGY5NDQwOGJkYTU1MzEyMzg3
+    YTFkNGY1OTAyYmU4MmEyYjc1ODcxY2U1Yzc4NjFkZWFhYmE0MzAwZGMxYjUz
+    MDdlOTAxNGE1Y2JiMDc0MjE4NGIzYzdiZjEzODZjNzlhOTQ3NWU=
   data.tar.gz: !binary |-
-    ZjdjYTNmZGZmYmI3MGE3N2ZmYWUwMDViNWUxMjAzMzlmZmIwYWIyNzFkNDky
-    ZjM1NDM0N2I2ODllNDhlMmM3YTdhNWExNTMwMzgxZjY3NDlhYWMyYzAxMjA4
-    YTdjZTRlNzUzZjljM2MxZjAzNmZhMjQwNjEzOGJkZTlmOTUzMWQ=
+    ZDM2NTlhMTg4YjQ3YWUxODhiMmFkZDU4MTQ4ZWI1NTdkM2M5OGM5MDI2NGJk
+    ZjE2ZjYzMmUxMmUyMjZjMDhmNTNiNzE5MjQ0NzUzOTI3MGViZmUxNjY5NTYy
+    NTIzYzI2MjljOWMzOTM2ZGMwY2NiNWM1NGQ4YjIxMDFkNmRkMjM=

data/LICENSE.md

@@ -0,0 +1,48 @@
+The MIT License (MIT)
+
+Copyright (c) 2016 Jon Tai
+
+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.
+
+
+
+Hardware initialization and interrupt handling arduino code was copied from
+https://github.com/Blinkinlabs/BlinkyTape_Arduino, which has the following
+license:
+
+The MIT License (MIT)
+
+Copyright (c) 2013 Blinkinlabs, LLC
+
+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

@@ -1,12 +1,53 @@
 BlinkyTape Orb
 ==============
 
-Ruby code to interface with a [BlinkyTape controller board](http://blinkinlabs.myshopify.com/collections/frontpage/products/blinkytape-control-board)
-running the custom firmware in the `arduino` directory of this repository. See
-the [Blinkinlabs arduino instructions](http://blinkinlabs.com/blinkytape/arduino/)
+The code in this repository makes a [BlinkyTape controller board](http://blinkinlabs.myshopify.com/collections/frontpage/products/blinkytape-control-board)
+act like an ambientdevices Ambient Orb and allows controlling it from Ruby over
+USB. Controlling the Orb from other languages should be simple—it only requires
+sending a few ASCII characters over the serial interface.
+
+Ambient Orbs are great for displaying background information such as stocks,
+the weather, or whether or not the `master` branch of your repository is
+passing tests.
+
+## Custom Firmware for BlinkyTape controller board
+
+A BlinkyTape has multiple individually-addressable LEDs connected to it. It can
+recieve commands over the serial interface. The default firmware expects 3
+bytes per pixel (values for red, green, and blue), followed by a `255` byte to
+display everything. This protocol is required for compatibility with BlinkyTape
+software such as [PatternPaint](http://blinkinlabs.com/blinkytape/patternpaint/).
+
+On the other hand, the Ambient Orb accepts a color and animation, encoded as
+ASCII. After recieving an update, the Orb continues to animate (pulse) on its
+own. Like on the BlinkyTape, the button is used to cycle through several
+brightness levels.
+
+The `arduino` directory in this repository contains custom firmware for the
+BlinkyTape that makes it act more like an Ambient Orb. There are some
+differences:
+
+ * Only 6 colors and 4 pulse speeds are accepted (vs. 37 and 10,
+   respectively)
+ * As a result, the serial protocol is simplified to 1 ASCII character per
+   update
+ * Brightness can be controlled via the serial protocol as well as via the
+   hardware button (it's unclear if the Orb allowed this as well)
+ * Animations were recreated from memory without comparing them side by side
+   with the Orb, so timing and transitions may vary.
+
+See the [Blinkinlabs arduino instructions](http://blinkinlabs.com/blinkytape/arduino/)
 for how to install the firmware. The firmware can be made to work on an Arduino
 Uno R3 with some modifications, mainly around the button handling.
 
+## Ruby Gem
+
+The `blinkytape-orb` gem is a thin wrapper around the serial protocol
+(described below). It also does automatic device detection if you only have one
+Orb connected.
+
+Here's how you might use it:
+
 ```ruby
 require 'blinkytape-orb'
 
@@ -43,3 +84,79 @@ sleep(3)
   sleep(10)
 end
 ```
+
+# Serial Protocol
+
+The custom firmware accepts a single ASCII character per update. Regular
+updates encode both a color and pulse speed. Some characters are set aside to
+allow controlling brightness.
+
+## Regular Updates (Color and Pulse Speed)
+
+The two lowest bits encode the pulse speed:
+
+* `00` - No pulsing
+* `01` - Slow pulsing
+* `10` - Medium pulsing
+* `11` - Fast pulsing
+
+The next three bits encode the color:
+
+* `000` - Red
+* `001` - Orange
+* `010` - Yellow
+* `011` - Green
+* `100` - Blue
+* `101` - Purple
+
+To make the protocol easier to type by hand in a serial monitor, commands are
+"shifted up" by 65 (ASCII "A"). For example, green and medium pulsing would be
+encoded as `01110` (14), but this is sent as 79 (65+4), which is "O".
+
+This encoding can be done easily in Ruby:
+
+```ruby
+('A'.ord + (color * 4) + pulse).chr
+```
+
+In other words, "A" is red with no pulsing, followed by "B" for slow pulsing,
+"C" for medium pulsing, and "D" for fast pulsing. "E" is orange with no
+pulsing, "F" is orange with slow pulsing, etc.
+
+## Brightness Updates
+
+There are three settings encoded in two bits:
+
+* `00` - Dim
+* `01` - Medium
+* `10` - Bright
+
+These are "shifted up" by 97 (ASCII "a"). So "a" is dim, "b" is medium, and "c"
+is bright. The Ruby one-liner for encoding is:
+
+```ruby
+('a'.ord + brightness).chr
+```
+
+# Hardware Setup
+
+I stuck the [BlinkyTape controller board](http://blinkinlabs.myshopify.com/collections/frontpage/products/blinkytape-control-board)
+on the plastic base of the Orb with a small styrofoam riser (poor man's 3D
+printer) and some double-sided tape. The [adafruit NeoPixel 12-LED ring](https://www.adafruit.com/product/1643)
+easily fits on the plastic base and in the hole in the bottom of the glass part
+of the orb. The ring rests on slightly higher styrofoam risers, above the
+controller board. I got the JST connector version of the controller board,
+snipped off the connector, and soldered the wires directly to the NeoPixel
+ring. The glass orb simply rests on the plastic base since there isn't anything
+for the base to screw into anymore. (The wires kind of help keep the base
+attached to the glass.) I considered getting a NeoPixel 7-LED jewel to sit in
+the center of the ring, but the 12 LEDs are plenty bright even in daylight.
+
+![Hardware, Side View](https://raw.githubusercontent.com/jtai/blinkytape-orb/master/hardware/photos/hardware-side.jpg)
+![Hardware, Top View](https://raw.githubusercontent.com/jtai/blinkytape-orb/master/hardware/photos/hardware-top.jpg)
+
+adafruit makes NeoPixel LEDs in a variety of form factors. I built another
+"Orb" using the [8-LED strip](https://www.adafruit.com/products/1426) that has
+no enclosure—it is just attached to the underside of my monitor and lights up
+the monitor stand. The setup is relatively cheap, easy to assemble, and small
+enough to install just about anywhere.

data/arduino/blinkytape_orb.ino

@@ -13,8 +13,8 @@
 // visuals
 #define PULSE_MAX_VAL 255
 #define PULSE_MIN_VAL 160
-#define PULSE_DURATION_SLOW 3000
-#define PULSE_DURATION_MED 1500
+#define PULSE_DURATION_SLOW 6000
+#define PULSE_DURATION_MED 3000
 #define PULSE_DURATION_FAST 0
 
 #define CHANGE_MIN_VAL 64
@@ -27,6 +27,8 @@
 // state
 CRGB leds[NUM_LEDS];
 
+byte prev_command;
+byte command;
 bool initialized;
 
 uint8_t hue;
@@ -38,10 +40,46 @@ bool buttonDebounced;
 uint8_t brightness;
 
 
+void checkSerial() {
+  if (Serial.available() > 0) {
+    command = Serial.read();
+  }
+
+  // handle brightness changes immediately
+  // if command was a brightness change or an invalid command,
+  // swallow it to prevent rushing through the next fade
+  switch (command) {
+    case 97:
+      brightness = BRIGHTNESS_MIN;
+      FastLED.setBrightness(brightness);
+      command = prev_command;
+      break;
+    case 98:
+      brightness = BRIGHTNESS_MED;
+      FastLED.setBrightness(brightness);
+      command = prev_command;
+      break;
+    case 99:
+      brightness = BRIGHTNESS_MAX;
+      FastLED.setBrightness(brightness);
+      command = prev_command;
+      break;
+    default:
+      if (command - 65 >= 24) { // swallow garbage values
+        command = prev_command;
+      }
+      break;
+  }
+}
+
 void fade(uint8_t new_val, long duration) {
   if (val == new_val) {
+    checkSerial();
+
     // setBrightness() requires a call to delay() periodically
+    // without this line, we can't change the brightness when we're not pulsing
     FastLED.delay(duration);
+
     return;
   }
   
@@ -76,8 +114,10 @@ void fade(uint8_t new_val, long duration) {
     }
     FastLED.show();
 
-    // check to see if we've been given a new command, if so, hurry things along
-    if (Serial.available() > 0) {
+    // check to see if we've been given a new hue or pulse command
+    // if so, hurry things along
+    checkSerial();
+    if (command != prev_command) {
       FastLED.delay(change_delay_ms);
     } else {
       FastLED.delay(delay_ms);
@@ -93,6 +133,8 @@ void setup() {
   FastLED.addLeds<NEOPIXEL, DATA_PIN>(leds, NUM_LEDS);
   FastLED.setCorrection(LED_CORRECTION);
 
+  prev_command = 122; // initialize to invalid command so any valid command will trigger action
+  command = 122;
   initialized = false;
 
   val = PULSE_MAX_VAL;
@@ -123,72 +165,55 @@ void loop() {
     fade(PULSE_MIN_VAL, pulse_duration / 2);
   }
 
-  if (Serial.available() > 0) {
-    byte c = Serial.read();
-    c -= 65; // align to ASCII "A"
-    switch (c) {
-      case 32:
-        brightness = BRIGHTNESS_MIN;
-        FastLED.setBrightness(brightness);
+  if (command != prev_command) {
+    fade(CHANGE_MIN_VAL, CHANGE_DURATION / 2);
+
+    prev_command = command;
+    initialized = true;
+
+    byte c = command - 65; // align to ASCII "A"
+
+    switch ((c & B00011100) >> 2) {
+      case 0:
+        hue = HUE_RED;
         break;
-      case 33:
-        brightness = BRIGHTNESS_MED;
-        FastLED.setBrightness(brightness);
+      case 1:
+        hue = HUE_ORANGE;
         break;
-      case 34:
-        brightness = BRIGHTNESS_MAX;
-        FastLED.setBrightness(brightness);
+      case 2:
+        hue = HUE_YELLOW;
+        break;
+      case 3:
+        hue = HUE_GREEN;
+        break;
+      case 4:
+        hue = HUE_BLUE;
+        break;
+      case 5:
+        hue = HUE_PURPLE;
         break;
-      default:
-        if (c < 24) { // filter out garbage values
-          fade(CHANGE_MIN_VAL, CHANGE_DURATION / 2);
-    
-          switch (c & B00000011) {
-            case 0:
-              pulse = false;
-              pulse_duration = CHANGE_DURATION;
-              break;
-            case 1:
-              pulse = true;
-              pulse_duration = PULSE_DURATION_SLOW;
-              break;
-            case 2:
-              pulse = true;
-              pulse_duration = PULSE_DURATION_MED;
-              break;
-            case 3:
-              pulse = true;
-              pulse_duration = PULSE_DURATION_FAST;
-              break;
-          }
-      
-          switch ((c & B00011100) >> 2) {
-            case 0:
-              hue = HUE_RED;
-              break;
-            case 1:
-              hue = HUE_ORANGE;
-              break;
-            case 2:
-              hue = HUE_YELLOW;
-              break;
-            case 3:
-              hue = HUE_GREEN;
-              break;
-            case 4:
-              hue = HUE_BLUE;
-              break;
-            case 5:
-              hue = HUE_PURPLE;
-              break;
-          }
-    
-          initialized = true;
-    
-          fade(PULSE_MIN_VAL, CHANGE_DURATION / 2);
-        }
+    }
+
+    switch (c & B00000011) {
+      case 0:
+        pulse = false;
+        pulse_duration = CHANGE_DURATION;
+        break;
+      case 1:
+        pulse = true;
+        pulse_duration = PULSE_DURATION_SLOW;
+        break;
+      case 2:
+        pulse = true;
+        pulse_duration = PULSE_DURATION_MED;
+        break;
+      case 3:
+        pulse = true;
+        pulse_duration = PULSE_DURATION_FAST;
         break;
     }
+
+    fade(PULSE_MIN_VAL, CHANGE_DURATION / 2);
   }
 
   fade(PULSE_MAX_VAL, pulse_duration / 2);

data/lib/blinkytape-orb.rb

@@ -57,7 +57,7 @@ class BlinkyTapeOrb
 
     logger.info("updating with color=#{color}, pulse=#{pulse}")
 
-    send((65 + (color * 4) + pulse).chr)
+    send(('A'.ord + (color * 4) + pulse).chr)
   end
 
   def setBrightness(brightness)
@@ -67,7 +67,7 @@ class BlinkyTapeOrb
 
     logger.info("setting brightness=#{brightness}")
 
-    send((65 + 32 + brightness).chr)
+    send(('a'.ord + brightness).chr)
   end
 
   private

data/lib/blinkytape-orb/version.rb

@@ -1,3 +1,3 @@
 class BlinkyTapeOrb
-  VERSION = '0.0.1'
+  VERSION = '0.0.2'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: blinkytape-orb
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.0.2
 platform: ruby
 authors:
 - Jon Tai
@@ -33,12 +33,14 @@ extra_rdoc_files: []
 files:
 - .gitignore
 - Gemfile
+- LICENSE.md
 - README.md
 - arduino/blinkytape_orb.ino
 - blinkytape-orb.gemspec
+- hardware/photos/hardware-side.jpg
+- hardware/photos/hardware-top.jpg
 - lib/blinkytape-orb.rb
 - lib/blinkytape-orb/version.rb
-- spec/lib/.blinkytape-orb_spec.rb.swp
 - spec/lib/blinkytape-orb_spec.rb
 - spec/spec_helper.rb
 homepage: https://github.com/jtai/blinkytape-orb
@@ -65,6 +67,5 @@ signing_key:
 specification_version: 4
 summary: Ruby code to interface with BlinkyTape controller board running custom firmware
 test_files:
-- spec/lib/.blinkytape-orb_spec.rb.swp
 - spec/lib/blinkytape-orb_spec.rb
 - spec/spec_helper.rb