Sep 06

Building Pulse & Bloom - an interactive biofeedback installation at Burning Man 2014

This was my second year attending Burning Man. Many use Burning Man as a week to detach from their workweek and experience a new life of intense leisure. Not me, I come to Burning Man to build.

Pulse & Bloom is a 2014 honorarium installation. The core team of 6 people — Saba Ghole, Shilo Shiv Suleman, Rohan Dixit, Heather Stewart, Luke Iseman, and myself — built 20 interactive lotus flowers made out of steel and rowlux. Each lotus flower ranges from 8 to 18 feet tall, each of which lights up with your pulse. You and another person can put your hands on a couple of Hamsa hands at the base of the lotus flower and your respective heartbeats will light up the flower.

We've gotten some great press coverage at the BBC, The Guardian, The Atlantic's Big Picture twice, CBS News, NBC News, and MSNBC.

As usual, the complete source code for Pulse & Bloom is on GitHub.

Your heartbeat in light

Here are a couple videos of all twenty lotus flowers in full working order.

Each lotus flower is blue until a person or two sits down at its base and places their hand on the pulse sensor. You can see the Hamsa hand and its embedded pulse sensor in this shot of my girlfriend Brittany and me working on keeping the electronics going.

Photo credit Jim Urquhart / Reuters

When a pulse is read, the lotus flower shoots the heartbeat up the stem and into the petals, where it blooms in a brilliant display of amber. When two people's hands are being measured, both of their heartbeats are shown as two distinct colors.

How the electronics are made

There are five stages to making the electronics:

  1. Making the custom circuit boards
  2. Making the custom pulse sensors
  3. Driving the high current LEDs
  4. Writing the firmware
  5. Powering the lotuses

1. Making the custom circuit boards

The circuit board controls all of the lighting, sensors, timing, and debugging sequences. A reliable circuit board couldn't just be an Arduino and a breadboard. I decided to use OSH Park and OSH Stencils to fabricate inexpensive circuit boards. I ultimately went through seven revisions while we worked out the final design of the lotuses. This included adding additional lights, additional sensors, controls for EL wire, and better power management using an external buck converter.

This board has support for multiple high current petal LEDs driven by digital RGB pins (used for fading colors in and out using PWM) and in multiple voltages. The high current petal LEDs runs on 12V, which comes directly off the battery, the ATmega328p chip and stem LEDs run at 5V, and the pulse sensor runs at 3.3V.

To convert 12V to 5V I use a $3 switching voltage regulator from Electrodragon. This requires a +/- connection for both 12V in and 5V out. To convert 5V to 3.3V I used a linear voltage regulator soldered directly on the board, since the current requirements of the pulse sensor were around 20mA. The heat dissipated was negligible compared to the rest of the circuit.

I also added terminal connections for two 5 meter LEDs that wrapped around the tall lotus stem. We attached two 5 meter LED strips around the stems because when two people put their hands on the two pulse sensors, we need an easy way to show both heartbeats without one winning out over the other. When only one person's hand in being measured, both 5 meter light strips show the same color, which makes it that much brighter for a single person.

Lastly, the two pulse sensors terminate their I2C wires directly on the board. I used two separate I2C channels instead of one to cut down on time. I could easily have put both pulse sensors on the same I2C connections, but that would've required both pull-up resistors on the SDA and SCL data lines as well as a rewrite of the timing functions for the sensor.

All of these terminations are made using 2.5mm and 3.5mm pitch screw terminals. In hindsight I would have used female JST-SM mounted connectors and ordered custom wires with JST-SM male connectors. I assumed the lowest common denomenator would be bare tinned wire, but all of the bare wires could easily have been switched over to polarized, latching connectors. This would have reduced over 90% of the field work I had to perform on boards, as their wire would fall out of the screw terminals due to not being screwed in with enough force.

The board was laid out to be as big as a pack of gum. All of the 12V traces are thickened and isolated on the right side of the board. They are rated for 3 amps although they would end up only driving 1 amp on the playa.

These boards are then stenciled with solder paste and populated with their chips and passive components.

An inexpensive hot plate is used to reflow the solder. The chip is in a TQFP package, which has a 0.5mm pitch between pins. This makes it nearly impossible to hand solder. This stencil and reflow technique works well and my yield stayed high at around 95%.

Finally, the board is ready to be populated with screw terminals.

The final board in a dust-proof enclosure.

2. Making the custom pulse sensors

This was both the riskiest piece of the puzzle and also the most fun to build. In order to show your heartbeat on the lotus, I need to have a clear reading of your pulse. There are a fair number of issues with most off-the-shelf heartbeat sensors, including:

  • Cost: While a $50 pulse sensor is nice, it's way out of our budget. We spent $6 in components to make each of our pulse sensors for a total of 40 sensors (two per lotus).
  • Design affordance: There were a fair number of pulse sensors that required an infrared light on one side of your finger and an infrared detector/receiver on the other. This clamping of your finger wasn't something we could get away with in the desert. We needed a sensor you could just touch and hold on one side. It needed to be a simple interface so we wouldn't have to show any instructions.
  • Reliability: When a sensor gets covered in dust, will it still work? Infrared light, thankfully, passes through a layer of dust and can read the changes in blood flow in your finger. Some options were entirely visual and they would have performed quite poorly out on the playa.

The first prototype I built suffered from the design affordance and reliability issues, although it worked pretty well in ideal conditions.

We ended up finding an IC by Silicon Labs called the Si114x, which uses three LEDs — two infrared and one visible — and a small QFN-10 sized light sensor. The original sensor we used was the Modern Device pulse sensor, which also provided firmware and ideas for a board layout. The folks at Modern Device were kind enough to offer advice on how they built their sensor and about how to fix the infrared LED issues we hit. I owe them beers for saving me from many more excruciating hours of trying to build sensors that don't sense.

I built out a small PCB the size of a fingertip.

This tiny IC is a bit tricky to solder as it has no leads and the pins are extremely close together. My yield dropped to about 80%, but 4 out of every 5 pulse sensors I built worked perfectly the first time. If they failed, I would remount them on the hot plate and try wicking away any solder bridges I could find. This worked only about half the time. After that I gave up and now have a plastic cup full of broken pulse sensors.

Finally the sensor is hooked up and a tiny red light is emitted, letting people know where to put their fingers.

3. Driving the high current LEDs

What turned these lotuses from flowers into gems are the high current LEDs mounted in the petals at the top. There are 9 of these high current LEDs per lotus, split into groups of three, each driven by a constant current driver.

If you were to look at one of these LEDs from a few feet away, you would immediately see spots in your eyes. They are extremely bright pinpoints of light. The fact that they are also full color and need a heatsink due to their brightness means that you won't just find these in an easy package ready for plugging in.

Photo credit Jim Urquhart / Reuters

Normally a single LED is powered by a single constant current driver. This driver can drive up to 1A of current at 12V. Because we were only using a single channel of color (blue) in the rest state, which is where the lotus spent most of its time, we could triple the number of LEDs driven by a single constant current driver.

When in use the petals glow amber, which uses two channels (100% red, 50% green) but only for a moment while at peak current. So while the peak current is above what this constant current driver is rated for, it's only at peak and therefore within our tolerance.

Using a Chinese distributor, we bought these Sparkfun high current LEDs for $0.86 each instead of the full $15. However, we also bought 80 of Sparkfun's PicoBucks to use as our constant current driver. While we could have built this ourselves to save money, buying 80 of something at $15 each is still only $1.2k, while building them ourselves would only have saved a few hundred dollars.

We bought 200 high current LEDs, all of which had to have their 6 anode and cathode connections soldered.

In order to connect 9 high current LEDs to the board, we need to drive them in groups of three. Each group has 6 connections: red, green, blue anodes, and red, green, blue cathodes. The wiring diagram for this setup can get a bit rats nesty, but the end result was fairly easy to work with, as the picobuck groups didn't cross.

Finally, a shot of a complete picobuck with the wire connectors in the background.

4. Writing the firmware

The complete source code for Pulse & Bloom is on GitHub. There you can find the firmware used to program the main circuit board's ATmega328p chip, as well as designs for the laser cut cowl that sits over the pulse sensor's Si1143x IC.

The easiest way to read the firmware is to dive into src/pulse.cpp. It has all of the pulse and rest states and handles the high level logic.

The state machine that runs the entire routine is determined by a couple of critical measurements. The program takes a measurement of both pulse sensors and determines whether a finger is covering either of them and whether or not that finger has an active pulse going.

// Modes
void determinePlayerMode();
void determineFingerMode(int sensor1On, int sensor2On);
void resetStem(PulsePlug *pulse);
uint8_t adjustBpm(PulsePlug *pulse);

When there are no fingers on either of the pulse sensors, the program runs the rest state, which is a blue-topped lotus with a small blue snake running up and down the stem. The program is merely waiting for somebody to put their finger on a sensor.

// State: resting
void runResting();
void runRestStem();
void runRestStem(PulsePlug *pulse, int16_t currentLed);
void clearStemLeds(PulsePlug *pulse);
void beginPetalResting();
bool runPetalResting();

The firmware for the pulse sensor originally came from Modern Device's pulse sensor. Before a heartbeat is shown an accurate measurement of a heartbeat needs to be read. In order to determine whether a heartbeat is found and at what speed, a number of light detection measurements are taken and analyzed.

Modern Device's firmware simply finds the high frequency curve (the heartbeat) and the low frequency curve (the light sensors leveling out) and then use a simple peak and valley hueristic to determine the moment a heartbeat begins. This can take up to two or three seconds at first, so a bit of unwinding animation prepares you when you first put your finger on the sensor. I modified the firmware to account for multiple pulses on the same lotus and to have thresholds that worked better for the desert.

When a finger is detected, the stem snake lights shoot backwards up and down the lotus in prep for a heartbeat. This looks seamless as it clears the stem. This way a heartbeat doesn't interrupt the rest state.

// State: end resting
void beginSplittingStem();
void runSplittingStem();
void runSplittingStem(PulsePlug *pulse, int16_t currentLed);

When a heartbeat is detected, it is first shot up the stem. The color is determined by how many pulse sensors are being used. 1 heartbeat shows amber. 2 heartbeats show in white and light red.

// State: stem rising
bool runStemRising(PulsePlug *pulse, PulsePlug *shadowPulse);

Once the heartbeat reaches the top of the stem, the petals then fill with light.

// State: petal rising
void beginPetalRising();
bool runPetalRising();

After a set delay, the petal slowly lose light while waiting for the next heartbeat.

// State: petal falling
void beginPetalFalling();
bool runPetalFalling();

Lots of debugging messages have been left in the code and are accessible using the Serial pin on the board. Just turn on USE_SERIAL, which is commented out at top. Note that this increases binary code size by about 2.5K. I wrote a lot of logging.

// Debugging
void printHeader();
void blink(int loops, int loopTime, bool half);
int freeRam ();

5. Powering the lotuses

While much of what I built above came out of knowledge I already had, learning how to power this large of an installation off just a battery was all new to me. I'm used to microelectronics that run off a coin cell or AA batteries.

Measuring current and power usage

First, in order to figure out how big of a battery we needed, we had to measure how much power we were taking. I hooked up an ammeter in series with a single lotus to measure the current draw. In rest state, a single lotus drew 0.75A at 12V. In the active pulsing heartbeat state, a single lotus drew 1.5A at 12V. Since a lotus spends 95% of its time at rest, we rounded the average current consumption to 1A.

Twenty lotuses at 1A at 12V meant we needed 240Ah to sustain a 12 hour night. A car battery was recommended, but car batteries can only discharge down to 80% without irreparable harm. However, a marine deep-cycle battery can go down to 20% without harm.

This 150 lb. battery has enough capacity, although we ended up adding a couple 6V batteries in series (to boost them to 12V) and then running them in parallel to offset some of the load.

Dealing with the voltage drop

A big issue we ran into was the voltage drop across the power lines. We placed the batteries on the edge of the installation, which meant some of the lotuses had 20 meters of wire between them and the battery. The voltage drop per 10 meter section is nearly 2V, which means that the voltage reaching the further lotuses was down to 7.5V.

The high current LEDs were not able to be smoothly driven at this low of a voltage, causing them to flicker. We determined that a voltage drop was responsible for the flickering, which got worse the further the lotus sat from the batteries. But when we discovered this the wires had already been trenched 6 inches beneath the playa. A day of work lost, but we sucked it up and ripped out all of the ground wiring to accommodate the battery which had to be moved into the center of the installation.

At the end of each night we had to bike out with a trike and carry all 300 lbs. of batteries back to camp, where they were hooked up to a 1 kW solar array, where they were charged at 48A over 6 hours.

Prototyping the lotuses

Back at American Steel in Oakland, the lotus stems, bases, and petals were ready to be hooked up. These twenty lotus stems were bent by Heather. They range from 6ft to 16ft in length and each weighs 50 lbs.

Such a heavy stem needs a larger base and heavy anchors to stay upright in the wind.

We placed the lily pad over the base to cover it up and then added all of the electronics. Lights, sensors, and circuit boards all had to be mounted.

This is a photo of our first complete lotus flower. Just compare its sheer size to Shilo.

Once we were confident that one lotus would successfully light we left the other 19 lotuses packed away for assembly on the playa.

A dusty scene

We drove out in the biggest rental car I could get my hands on. Our minivan is full of electronics, bicycles, tents, costumes, coolers full of fruit and veggies, dry snacks, and water.

Since we were early arrival, they give you these red bracelets. They say Work hard, don't do stupid shit.

The boards would accumulate dust on them everyday. Our plastic enclosures turned out to be too big for the holes we made in the platform. So we ended up using ziploc bags. These baggies stayed attached, but the only reason they didn't cause any issues is that the boards worked just fine in the dust, as you can see here.

If dust was a real problem for the boards, then I would have spent a whole lot more time making a tight fitting enclosure and a hole for it that protects it both from the elements and from people.

The playa gets covered in dust storms regularly throughout the week. A particularly nasty dust storm is pictured here, eating our poor lotus flowers alive.

Although during the day when its not dust storming the lotuses offer a cozy respite from the heat of the playa.

Photo credit Jim Urquhart / Reuters

The entire process lasted 4 months with 2.5 months of nearly full-time work on my part. I'm thrilled that I get to open-source both the process and the firmware. I hope others who build art installations can use some of my lessons learned here. I'm happy to answer any questions on Twitter.

See you next year on the playa!

Jan 15

Adventures in Wearable Electronics - Making a Light-up Dress

For New Year's Eve 2014, my girlfriend and I went to a dance party where wearable electronics were not only encouraged but also on display from a variety of hobbyists. I decided to use this as an opportunity to combine two of my favorite hobbies: sewing and electronics.

It is my goal to encourage more people to weave wearable electronics into their own clothing. It's the future and we might as well look the part. Plus it's easy to get started and to modify existing code.

The full source code for this dress is available on GitHub.


I attached six addressable LED strands from Sparkfun ($20 each) to the lining of Brittany's dress, and then used a Flora module from Adafruit ($25) to control them. I then used a 3 x AAA battery holder from Adafruit ($2).


I used Adafruit's NeoPixel library to control the LEDs. There were 60 LEDs per 1 meter-long strand. We only needed 40 of the LEDs, but instead of cutting them off, we simply sewed the unused third underneath the strand and cut the software off at 40 LEDs. This way we can repurpose the LED strands when we decide to move them to a new dress.

In order to make the connections between the LED strands and the Flora module, I used 30 AWG wire, which is an extremely thin and light wire. The gauge is 0.01" and is as fine as thread. This allowed me to sew the wire into the fabric. I could have used conductive thread, but this wire wrap has a sheath that prevents it from shorting other wires when they touch. It's also extremely light-weight, so having 18 wires (3 wires per LED strand: power, ground, data) looping around the dress wasn't an issue.

I also want to mention that the code below is hard-coded for six stands. There is a fine line between a hack and a project, and for this, due to my limited time budget, was closer to hack than reusable project. You can easily abstract the code below to account for more or fewer strands, but I was able to ship before midnight on NYE, so I'm considering it a success.

void setup() {
  // To ensure that the first random color in `loop` is never the same.



void loop() {
  for (int i=0; i<2; i++) {
    hulahoop(randomColor(), random(20,60));

  sparkle(randomColor(), random(30,70));

  raindrops(randomColor(), random(20,60));

  spiral(randomColor(), random(15,30));

Above we have the code for setup and loop, the two main Arduino routines. Notice that I am repeating the hula hoop routine, since it's pretty quick and looks good on repeat.

I also want to note that every single routine gets its own random color and random delay. This bit of randomness is something I weave into all of my wearable electronics, since it goes just a bit further than off-the-shelf components and shows that there was some intelligence behind the routine.

By giving a random delay to each routine I am actually changing the speed of the routine. Sometimes the raindrops would fall quickly, sometimes the hula hoop would have a slow fall and rise. It's all part of making mesmerizing patterns.

Hula hoop

For the hula hoop routine, I chose to use cylons at equal positions that move up and down the strand. To make the transition from one LED to the next, I use a cylon, which is a fancy way of saying that the LEDs immediately above and below the active LED are also on, but at a reduced brightness.

In this case the cylon is 5 LEDs wide. 100% brightness for the middle/active LED, 1/18th brightness for the two adjacent LEDs, and 1/36th brightness for the two LEDs further out from there.

So what you see to the left are actually 5 LEDs turned on per-strand, although they get quite dim as you get further from the active LED. You can adjust the dimness of the adjacent LEDs by adjusting the weight parameter.

void hulahoop(unsigned long color, byte wait) {
  // weight determines how much lighter the outer "eye" colors are
  const byte weight = 18;  
  // It'll be easier to decrement each of these colors individually
  // so we'll split them out of the 24-bit color value
  byte red   = (color & 0xFF0000) >> 16;
  byte green = (color & 0x00FF00) >> 8;
  byte blue  = (color & 0x0000FF);

  // Start at closest LED, and move to the outside
  for (int i=0; i<=LED_COUNT-1; i++) {
    led_a.setPixelColor(i, red, green, blue);
    led_b.setPixelColor(i, red, green, blue);
    led_c.setPixelColor(i, red, green, blue);
    led_d.setPixelColor(i, red, green, blue);
    led_e.setPixelColor(i, red, green, blue);
    led_f.setPixelColor(i, red, green, blue);
    // Now set two eyes to each side to get progressively dimmer
    for (int j=1; j<3; j++) {
      byte redWJ = red/(weight*j);
      byte greenWJ = green/(weight*j);
      byte blueWJ = blue/(weight*j);
      if (i-j >= 0) {
        led_a.setPixelColor(i-j, redWJ, greenWJ, blueWJ);
        led_b.setPixelColor(i-j, redWJ, greenWJ, blueWJ);
        led_c.setPixelColor(i-j, redWJ, greenWJ, blueWJ);
        led_d.setPixelColor(i-j, redWJ, greenWJ, blueWJ);
        led_e.setPixelColor(i-j, redWJ, greenWJ, blueWJ);
        led_f.setPixelColor(i-j, redWJ, greenWJ, blueWJ);
      if (i-j <= LED_COUNT) {
        led_a.setPixelColor(i+j, redWJ, greenWJ, blueWJ);
        led_b.setPixelColor(i+j, redWJ, greenWJ, blueWJ);
        led_c.setPixelColor(i+j, redWJ, greenWJ, blueWJ);
        led_d.setPixelColor(i+j, redWJ, greenWJ, blueWJ);
        led_e.setPixelColor(i+j, redWJ, greenWJ, blueWJ);
        led_f.setPixelColor(i+j, redWJ, greenWJ, blueWJ);

  // Now we go back to where we came. Do the same thing.
  for (int i=LED_COUNT-2; i>=1; i--) {
    led_a.setPixelColor(i, red, green, blue);
    led_b.setPixelColor(i, red, green, blue);
    led_c.setPixelColor(i, red, green, blue);
    led_d.setPixelColor(i, red, green, blue);
    led_e.setPixelColor(i, red, green, blue);
    led_f.setPixelColor(i, red, green, blue);
    // Now set two eyes to each side to get progressively dimmer
    for (int j=1; j<3; j++)
      byte redWJ = red/(weight*j);
      byte greenWJ = green/(weight*j);
      byte blueWJ = blue/(weight*j);

      if (i-j >= 0) {
        led_a.setPixelColor(i-j, redWJ, greenWJ, blueWJ);
        led_b.setPixelColor(i-j, redWJ, greenWJ, blueWJ);
        led_c.setPixelColor(i-j, redWJ, greenWJ, blueWJ);
        led_d.setPixelColor(i-j, redWJ, greenWJ, blueWJ);
        led_e.setPixelColor(i-j, redWJ, greenWJ, blueWJ);
        led_f.setPixelColor(i-j, redWJ, greenWJ, blueWJ);
      if (i-j <= LED_COUNT) {
        led_a.setPixelColor(i+j, redWJ, greenWJ, blueWJ);
        led_b.setPixelColor(i+j, redWJ, greenWJ, blueWJ);
        led_c.setPixelColor(i+j, redWJ, greenWJ, blueWJ);
        led_d.setPixelColor(i+j, redWJ, greenWJ, blueWJ);
        led_e.setPixelColor(i+j, redWJ, greenWJ, blueWJ);
        led_f.setPixelColor(i+j, redWJ, greenWJ, blueWJ);


This is by far the easiest routine to program yet the one that brought the most attention. It simply flashes a random LED across all of the LED strips.

void sparkle(unsigned long color, uint8_t wait) {
  for (int i=0; i < LED_COUNT * STRIP_COUNT; i++) {
    int strip = floor(random(STRIP_COUNT));
    int led = floor(random(LED_COUNT));
    switch (strip) {
      case 0:
        led_a.setPixelColor(led, color);;
      case 1:
        led_b.setPixelColor(led, color);;
      case 2:
        led_c.setPixelColor(led, color);;
      case 3:
        led_d.setPixelColor(led, color);;
      case 4:
        led_e.setPixelColor(led, color);;
      case 5:
        led_f.setPixelColor(led, color);;


This is by far the most difficult of the routines. This one sends down cylons (5 LEDs, with the center LED being the brightest and the adjacent LEDs becoming decreasingly bright, so as to give the impression of smoother animation).

But you should notice that the next raindrop starts when the previous raindrop is half-way down the dress. In order to make it seamless, at the beginning of the routine I actually start another LED at the half-way mark, referred to in the below code as e_alt. This means that there is no point at which the dress looks spent and is waiting for the routine to start over.

void raindrops(unsigned long color, byte wait) {
  // weight determines how much lighter the outer "eye" colors are
  const byte weight = 18;  
  // It'll be easier to decrement each of these colors individually
  // so we'll split them out of the 24-bit color value
  byte red = (color & 0xFF0000) >> 16;
  byte green = (color & 0x00FF00) >> 8;
  byte blue = (color & 0x0000FF);
  double sludge = 0.5;
  double a_offset = 0;
  double b_offset = 3;
  double c_offset = 1;
  double d_offset = 2;
  double e_offset = 4;
  double f_offset = 5;

  // Start at closest LED, and move to the outside
  for (int i=0; i<LED_COUNT*(STRIP_COUNT-1)*sludge+LED_COUNT*10; i++) {
    double n = i % (int)(LED_COUNT*(STRIP_COUNT+1)*sludge-LED_COUNT*sludge);
    double led_count = (double)LED_COUNT;

    bool a_on = (sludge*a_offset*led_count) <= n && 
                n <= (sludge*a_offset*led_count+led_count);
    bool b_on = (sludge*b_offset*led_count) <= n && 
                n <= (sludge*b_offset*led_count+led_count);
    bool c_on = (sludge*c_offset*led_count) <= n && 
                n <= (sludge*c_offset*led_count+led_count);
    bool d_on = (sludge*d_offset*led_count) <= n && 
                n <= (sludge*d_offset*led_count+led_count);
    bool e_on = (sludge*e_offset*led_count) <= n && 
                n <= (sludge*e_offset*led_count+led_count);
    bool e_alt= (sludge*a_offset*led_count) <= n && 
                n <= (sludge*a_offset*led_count+led_count*sludge);
    bool f_on = (sludge*f_offset*led_count) <= n && 
                n <= (sludge*f_offset*led_count+led_count);

    if (!a_on && !b_on && !c_on && !d_on && !e_on && !f_on) {

    int a = n-a_offset*LED_COUNT*sludge;
    int b = n-b_offset*LED_COUNT*sludge;
    int c = n-c_offset*LED_COUNT*sludge;
    int d = n-d_offset*LED_COUNT*sludge;
    int e = n-e_offset*LED_COUNT*sludge;
    if (e_alt) {
      e = a+(LED_COUNT/2);
    int f = n-f_offset*LED_COUNT*sludge;

    if (a_on) led_a.setPixelColor(a, red, green, blue);
    if (b_on) led_b.setPixelColor(b, red, green, blue);
    if (c_on) led_c.setPixelColor(c, red, green, blue);
    if (d_on) led_d.setPixelColor(d, red, green, blue);
    if (e_on || e_alt) led_e.setPixelColor(e, red, green, blue);
    if (f_on) led_f.setPixelColor(f, red, green, blue);

    // Now set two eyes to each side to get progressively dimmer
    for (int j=1; j<3; j++) {
      byte redWJ = red/(weight*j);
      byte greenWJ = green/(weight*j);
      byte blueWJ = blue/(weight*j);

      if (a-j >= 0 && a_on) 
        led_a.setPixelColor(a-j, redWJ, greenWJ, blueWJ);
      if (b-j >= 0 && b_on) 
        led_b.setPixelColor(b-j, redWJ, greenWJ, blueWJ);
      if (c-j >= 0 && c_on) 
        led_c.setPixelColor(c-j, redWJ, greenWJ, blueWJ);
      if (d-j >= 0 && d_on) 
        led_d.setPixelColor(d-j, redWJ, greenWJ, blueWJ);
      if (e-j >= 0 && e_on) 
        led_e.setPixelColor(e-j, redWJ, greenWJ, blueWJ);
      if (f-j >= 0 && f_on) 
        led_f.setPixelColor(f-j, redWJ, greenWJ, blueWJ);

      if (a-j <= LED_COUNT && a_on) 
        led_a.setPixelColor(a+j, redWJ, greenWJ, blueWJ);
      if (b-j <= LED_COUNT && b_on) 
        led_b.setPixelColor(b+j, redWJ, greenWJ, blueWJ);
      if (c-j <= LED_COUNT && c_on) 
        led_c.setPixelColor(c+j, redWJ, greenWJ, blueWJ);
      if (d-j <= LED_COUNT && d_on) 
        led_d.setPixelColor(d+j, redWJ, greenWJ, blueWJ);
      if (e-j <= LED_COUNT && e_on) 
        led_e.setPixelColor(e+j, redWJ, greenWJ, blueWJ);
      if (f-j <= LED_COUNT && f_on) 
        led_f.setPixelColor(f+j, redWJ, greenWJ, blueWJ);


This routine is better in theory than in practice. The idea is to have a quick succession of LEDs light up in a spiral pattern. This would work a bit better with more LED strands wrapped around the dress.

In this case, I'm simply looping through the strands and lighting up successive LEDs. But the nice thing about this routine is that it has a dramatic crescendo to the top, at which point the hula hoop routine begins and it looks like the action started at the bottom and quickly worked its way up to the top, only to smoothly fall back down. It's a mesmerizing effect.

void spiral(unsigned long color, byte wait) {
  const byte weight = 18;  
  byte red = (color & 0xFF0000) >> 16;
  byte green = (color & 0x00FF00) >> 8;
  byte blue = (color & 0x0000FF);

  for (int level=LED_COUNT-1; level >= 0; level--) {
    for (int strip=0; strip < STRIP_COUNT; strip++) {

      switch (strip) {
        case 0:
          led_f.setPixelColor(level, red/weight, green/weight, blue/weight);
          led_a.setPixelColor(level, color);
          led_b.setPixelColor(level, red/weight, green/weight, blue/weight);
        case 1:
          led_a.setPixelColor(level, red/weight, green/weight, blue/weight);
          led_b.setPixelColor(level, color);
          led_c.setPixelColor(level, red/weight, green/weight, blue/weight);
        case 2:
          led_b.setPixelColor(level, red/weight, green/weight, blue/weight);
          led_c.setPixelColor(level, color);
          led_d.setPixelColor(level, red/weight, green/weight, blue/weight);
        case 3:
          led_c.setPixelColor(level, red/weight, green/weight, blue/weight);
          led_d.setPixelColor(level, color);
          led_e.setPixelColor(level, red/weight, green/weight, blue/weight);
        case 4:
          led_d.setPixelColor(level, red/weight, green/weight, blue/weight);
          led_e.setPixelColor(level, color);
          led_f.setPixelColor(level, red/weight, green/weight, blue/weight);
        case 5:
          led_e.setPixelColor(level, red/weight, green/weight, blue/weight);
          led_f.setPixelColor(level, color);
          led_a.setPixelColor(level, red/weight, green/weight, blue/weight);

Random Colors

Since randomness is the spice that gives this dress its mesmerizing qualities, it's important to have a good list of colors to use.

unsigned long COLORS[] = {

unsigned long randomColor() {
  return COLORS[random(sizeof(COLORS)/sizeof(unsigned long))];

Dancing to 2014

And what good is a beautiful light-up dress without a well lit dance partner? Here I am decked out in blue EL wire. I spent the better part of three hours sewing this wire into the edges of one of my jackets. But while hand-sewing can take half a day, the result is a great fit and a capable match for Brittany's dress.

The full source code for this dress is available on GitHub.

Jan 02

Building a living photo frame with a Raspberry Pi and a motion detector

Every hardware hacker has a start, and this one is mine. My girlfriend bought me a Raspberry Pi for my birthday, and so I became determined to build something with it for her birthday two months later.

As you can see above, I built a photo frame that has a few interesting parts. For one, the software which runs the photo frame, which I explore below, keeps the photos fresh from Instagram and Flickr. It then displays a random photo for a configurable six seconds. Secondly, there is a motion detector, built using a PIR sensor, which only turns the monitor on when somebody walks by.

This photo frame is easy to build, but it does take a bit of know-how. Mainly, you should feel comfortable soldering wires and mounting the screen and Raspberry Pi to a board or other object. The hard part for me was figuring out how to turn the monitor on and off through the command line.

Everything else is gravy, from configuring wifi and autoboot/auto-login on the device to attaching and setting up the motion detecting PIR sensor. You can also use the eLinux guide to Raspberry Pi and its handy RPi Hardware Basic Setup wiki.


Raspberry Pi

I chose to use a Raspberry Pi for its simple wifi integration so that photos could be automatically updated. I didn't want to have to load photos on to an SD card which could then be read by an Arduino.

Connecting the monitor was also trivial on a Raspberry Pi, where an Arduino, Maple, or Beagle Bone would require sourcing a connection between the monitor's composite input and an output from the device.

Raspberry Pi, $29 on Adafruit.

Make note of the fact that you actually don't see any of my connections on the top of the board (pictured below). In the below photo, where the Raspberry Pi is flipped vertically to show off the electrical connections, the monitor's composite cable and the motion detecting PIR sensor's red wires are soldered underneath.

This way the photo frame looks cleaner. If I had connected the monitor using the yellow composite cable, it would have to be with a male-to-male composite adapter, since both the Raspberry Pi and the monitor have a male RCA connection. This would jut out about 2 inches below the device, resulting in a messy look for the frame.

3.5" LCD Monitor

3.5" LCD Monitor, $45 on Adafruit

Note that if you do not plan to solder the composite cable's two wires, you will need the ugly male-to-male adapter, sold for $1.50 on Adafruit.

There are a number of different sized LCD monitors:

1.5" LCD, $40
2" LCD, $40
2.5" LCD, $45
4.3" LCD, $50
7" LCD, $75
10" LCD, $150

4GB SD Card with Raspbian (Raspberry Pi + Debian)

4GB SD Card, $10 on Adafruit

This tiny SD card comes pre-loaded with Raspbian. If you prefer to use your own SD card and want to bootload it, just follow eLinux's Easy SD Card Setup wiki.

Miniature Wifi on USB

USB Wifi, $11 on Adafruit

Unless you're planning to use an ugly ethernet cable, this tiny wifi USB device works perfectly. It's easy to setup as well. I followed Adafruit's tutorial for setting up wifi on a Raspberry Pi.

Passive Infrared Motion Sensor

PIR sensor, $10 on Adafruit

This is a simple and inexpensive component that is responsible for turning the monitor on and off. The accuracy is great, as it never misses a beat, yet I haven't found it to accidentally trigger in the night unless we walk by. It also has two adjustable dials on the back that allow you to control its sensitivity and delay before firing. Ladyada covers how it works.

Soldering Iron

Aoyue 937+, $60 on Amazon

In order to connect the PIR motion detector and the composite cables, without resorting to the ugly male-to-male adapter, you will need to use a soldering iron. I chose the Aoyue 937+ Digital Soldering Station. Works great and I'm quite happy with it. I should have bought more tips, though.


This is where you get creative. You effectively just need an enclosure, but I found that picture frames offer the greatest aesthetics-to-enclosure ratio. You just need something that can hold a Raspberry Pi and monitor taped to it. I used double-sided mounting tape as an adhesive, although the wires are being held up by the frame itself.


Raspberry Pi setup

You'll want to make sure you're setup with the following:

  • Auto-login, so your Raspberry Pi doesn't sit at a login prompt.
  • Auto-wifi, so you can download images automatically whenever your Raspberry Pi is turned on.
  • Disabled sleep, so your photo frame doesn't shut off when you don't want it to.

Downloading personal photos from Flickr

You'll need to register your Flickr API app, which is a quick process. That way you can get a Flickr API key that you can then use to walk the photos from your account. You will also need your Flickr user id.

There are two Python library dependencies for this code:

pip install flickrapi
pip install requests

Once those are installed, save this script as

#!/usr/bin/env python

import flickrapi
import requests

FLICKR_KEY = "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
USER_ID = "25704617@N04"

def make_url(photo):
    # url_template = "http://farm{farm-id}
    #                 {server-id}/{id}_{secret}_[mstzb].jpg"
    photo['filename'] = "%(id)s_%(secret)s_z.jpg" % photo
    url = ("http://farm%(farm)" 
           % photo)
    return url, photo['filename']

def main():
    print " ---> Requesting photos..."
    flickr = flickrapi.FlickrAPI(FLICKR_KEY)
    photos = flickr.walk(user_id=USER_ID)
    for photo in photos:
        url, filename = make_url(photo.__dict__['attrib'])
        path = '/home/pi/photoframe/flickr/%s' % filename
            image_file = open(path)
            print " ---> Already have %s" % url
        except IOError:
            print " ---> Downloading %s" % url
            r = requests.get(url)      
            image_file = open(path, 'w')

if __name__ == '__main__':

Downloading extra photos from Flickr by tag name

Part of the fun of this photo frame is that not only do all of my photos get shown randomly, but I introduced a hodgepodge of random photos by downloading photos from a specific Flickr tag. In this case, I added koala photos, which makes for a pleasant randomness.

Save the following command as or whatever you like as a tag.

FLICKR_TAG=koala && \
wget '$FLICKR_TAG' -O- \
| grep -Po 'http://[^.]+\.staticflickr[^"]+(_b.jpg|_z.jpg)' \
| wget -P /home/pi/photoframe/$FLICKR_TAG -nc -i-

Automatic downloading of new photos

In order to have the photos refreshed, you'll need to have them download in the background. Add these two lines to your crontab with crontab -e if you're using both the Flickr photo downloader and the Flickr tag downloader.

0 * * * * python /home/pi/photoframe/
30 * * * * /home/pi/photoframe/


Now that we have the photos downloaded and refreshed at a regular interval, we need to get the slideshow running. We'll use a simple app called the Linux framebuffer imageviewer. Stick this command into a

fbi -noverbose -m 640x480 -a -u -t 6 /home/pi/art/**/*

The option for time is set to 6 seconds, and it uses autozoom to automagically pick a reasonable zoom factor when loading images. The -u option randomizes the order.

Detecting movement

The slideshow is now running at fullscreen with a randomized assortment of Flickr photos, both your own and from favorite tags. But it's running even when you're not there! let's use the PIR (motion) sensor to turn off the monitor after no movement has been detected for 60 seconds.

Save this file as

#!/usr/bin/env python

import sys
import time
import RPi.GPIO as io
import subprocess

SHUTOFF_DELAY = 60 # seconds
PIR_PIN = 25       # 22 on the board
LED_PIN = 16

def main():
    io.setup(PIR_PIN, io.IN)
    io.setup(LED_PIN, io.OUT)
    turned_off = False
    last_motion_time = time.time()

    while True:
        if io.input(PIR_PIN):
            last_motion_time = time.time()
            io.output(LED_PIN, io.LOW)
            print ".",
            if turned_off:
                turned_off = False
            if not turned_off and time.time() > (last_motion_time + 
                turned_off = True
            if not turned_off and time.time() > (last_motion_time + 1):
                io.output(LED_PIN, io.HIGH)

def turn_on():"sh /home/pi/photoframe/", shell=True)

def turn_off():"sh /home/pi/photoframe/", shell=True)

if __name__ == '__main__':
    except KeyboardInterrupt:

Turning the monitor on and off

There are two ways to turn the monitor on and off. Use the tvservice command to turn off the monitor port.

pi@raspberrypi ~/photoframe $ chmod 0744 
pi@raspberrypi ~/photoframe $ cat 
tvservice -o

pi@raspberrypi ~/photoframe $ chmod 0744 
pi@raspberrypi ~/photoframe $ cat 
tvservice -c "PAL 4:3" && fbset -depth 8 && fbset -depth 16

This method actually turns off the port, which works great except when you're connected to an HDMI monitor and it shuts off when the port is turned off. When you walk into the room, the port is turned back on but the monitor is off, so it doesn't come right back up. In this case, simply switch virtual terminals to blank out the screen using the chvt command.

pi@raspberrypi ~/photoframe $ chmod 0744 
pi@raspberrypi ~/photoframe $ cat 
chvt 2

pi@raspberrypi ~/photoframe $ chmod 0744 
pi@raspberrypi ~/photoframe $ cat 
chvt 7

Fixing the monitor edges

By default, the image won't stretch to the edges of your monitor without cajoling.

Here's the before photo:

And here's with margin correction on the monitor:

To fix this, take a look at using RPiconfig. All you need to do is edit /boot/config.txt directly on the Raspberry Pi. The values you need to set are:

overscan_left=-6    # number of pixels to skip on left
overscan_right=-6   # number of pixels to skip on right
overscan_top=24     # number of pixels to skip on top
overscan_bottom=24  # number of pixels to skip on bottom

These are my values, but every monitor is different. In order to figure out the values, I would set the values using a binary search (set high then low then halfway between the two and repeat with the new halfway point being the high/low on the correct side), and then rebooting. Eventually I found optimal values.

Note that the values will be different from the boot screen to the photo viewer. Obviously, I optimized for the photo viewer, but that means the top and bottom of the boot screen is cut off. Not much better you can expect from a tiny $50 LCD monitor.

Also, if you need to rotate or flip the display, it's easy.

display_rotate=0        Normal
display_rotate=1        90 degrees
display_rotate=2        180 degrees
display_rotate=3        270 degrees
display_rotate=0x10000  horizontal flip
display_rotate=0x20000  vertical flip

Automatic start of the photo frame software

You'll want the software to start automatically on boot, so create a new init.d file at /etc/init.d/flickrd, and add the motion sensor and slideshow scripts to that new file:

sudo python /home/pi/photoframe/

Then set the permissions with:

sudo chmod 755 /etc/init.d/flickrd

and finally register the script to be run at startup:

sudo update-rc.d flickrd defaults

Don't forget to run the script as root, since you'll need permissions to turn the monitor on and off.


Everything above should leave you with a photo slideshow that automatically updates your photos, displays them zoomed in and fullscreen in random order, shutting off the monitor when nobody is around.

If you used the code above with no issues, congratulations! You're in a minority that can work with hardware and get everything right on the first try. For everybody else, we have to troubleshoot. Here are the issues that I ran into.

Test your LED

Just getting the Raspberry Pi to respond to my commands was tricky enough, so I wrote this basic program to just blink the onboard LED. This is the Hello, World of the Raspberry Pi.

import RPi.GPIO as GPIO
import time

LED_PIN = 18
def blink(pin):
    print " ---> On"
    print " ---> Off"

# to use Raspberry Pi board pin numbers
# set up GPIO output channel
for _ in range(0,3):

SSH'ing into your Raspberry Pi

You shouldn't have to rely on an external keyboard and a tiny screen to debug your Raspberry Pi. I suggest using Pi Finder to locate the IP address, if it's on your local network.

You can also use arp -a to find it.

Getting additional help

Turn to Stack Exchange's new Raspberry Pi section. It's still in beta as of early 2014, but there's a whole lot of great questions.

Nov 13

Backbonification: migrating a large JavaScript project from DOM spaghetti to Backbone.js

We've all done it. Our code base has one huge monolithic file, packed full of JavaScript spaghetti. It's unwieldy, hard-to-debug, and has little to no separation of concerns. It is a nightmare to bring new engineers up to speed.

This blog post is about decomposing NewsBlur's single-file 8,500 line JavaScript application into its component parts: 8 models, 12 views, 3 routers, 3 collections. This post explores patterns, techniques, and common pitfalls in migrating from vanilla JavaScript to Backbone.js. It covers moving routers, models, and views, and the process used to migrate a living app.

NewsBlur is a free RSS feed reader and is open-source. The benefit of being open-source is that you can see all of the changes I made in this migration by looking through the commit history.

As a bit of background, I worked on Backbone.js in its infancy, when Jeremy Ashkenas and I worked on DocumentCloud's many open-source projects.

The Presentation

This post was written concurrently with a presentation. Depending on your style, you can either read on or flip through this deck. Both have the same content, but this post expands on every concept in the presentation.

There's no need to go through the presentation. Just read on for the whole kaboodle.

Pre-reqs: Libraries

There are only two libraries you need to be intimately familiar with in order to make the most of your Backbone transition: Underscore.js and Backbone.js. That means not only being comfortable with reading the source code of these two libraries, but also knowing all of the methods exposed so you can reach into your grab-bag of tricks and pull out the appropriate function.


Underscore.js is another DocumentCloud library that makes your code more readable and compact by providing useful functions that massage, filter, and jumble data.

One popular use of Underscore is creating short pipelines that take a large collection of models and filters it based on conditions. That much is easy. But there are other uses that are beneficial to know.

You should be comfortable with all enumerable methods. Think about all of your model collections as reduce-able, filterable, and selectable.

Here are two examples of Underscore.js at work:

// Get ids of all active feeds
_.pluck( {
    return feed.get('active');
}), 'id');
// Returns: [42, 36, 72, ...]

// Count fetched/unfetched feeds
var counts = this.feeds.reduce(function(counts, feed) {
    if (feed.get('active')) {
        if (!feed.get('not_yet_fetched') || feed.get('has_exception')) {
            counts['fetched_feeds'] += 1;
        } else {
            counts['unfetched_feeds'] += 1;
    return counts;
}, {
    'unfetched_feeds': 0,
    'fetched_feeds': 0
// Returns: {'unfetched_feeds': 3, 'fetched_feeds': 42}


The star of the show is Backbone.js. The entire backbone.js file is fewer than 1,500 lines long, and that's with 228/1478 lines of whitespace (15%) and 389/1478 lines of comments (26%).

This is a basic example of the layout of the four main classes: models, views, collections, and routers. A fifth meta-class called Events is mixed in to each of these classes.

How to start

The first step is no easy task. Take your existing design and visually decompose it into its component views. Each view will be represented by either a single model or a combination of models. In fact, you can even have a view not be backed by a model at all.

Take the NewsBlur UI for example. It's a standard three-pane view, with feeds, stories, and story detail:

Notice that there are multiple views inside other views. Some views are meant to be simple wrappers around other, more functional views.

On the left there is a list of feeds inside a list of folders. These folders and feeds can be embedded inside each other, creating a recursive structure that can be easily assembled by Backbone.js. Each feed view also contains an unread count, a feed title, a favicon, and a feed menu. All of these views are generated by their respective parents. Your job at this stage is to simply figure out what those views are so you can create the appropriate models, views, and controllers (routers).

Here's another example, coming from the DocumentCloud workspace, the original Backbone.js site:

A bit simpler than NewsBlur, this is a classic dual-pane view, with an organizer on the left and a detail pane on the right. Notice that there is a view collection, the document list, that holds numerous document views. It's important to consider each view as granular as possible and then bring them together in collections that are simply views of model collections.

Moving routers

You have routers, even if you don't realize it yet. Not only that, but you probably have multiple routers. Routers are the smallest part of a Backbone.js project, but are vital because they serve as the entry point for execution.

Anytime a URL is involved, your router should be handling it. You can also have multiple routers in a project. Before version 0.5.0 routers used to be called controllers, if that shines a light on their purpose.

If an out-of-band AJAX call is necessary, and it doesn't correspond to a specific model, then the router is a great place to put it.

There's a lot written on conventions for writing your router. I suggest going directly to the source: the original router from the DocumentCloud workspace. This is the first router ever written and should give you as canonical an idea as possible for what your router should and can include.

// Main controller for the journalist workspace. Orchestrates subviews.
dc.controllers.Workspace = Backbone.Router.extend({

  routes : {...},

  // Initializes the workspace, binding it to body.
  initialize : function() {
        pushState : true, 
        root : dc.account ? '/' : '/public/'

  // Create all of the requisite subviews.
  createSubViews : function() {  = new dc.ui.Paginator(); = new dc.ui.Navigation();    = new dc.ui.Toolbar();  = new dc.ui.Organizer();  = VS.init(this.searchOptions());
    this.sidebar      = new dc.ui.Sidebar();
    this.documentList = new dc.ui.DocumentList();

    if (!dc.account) return;   = new dc.ui.UploadDialog();   = new dc.ui.AccountDialog();

  // Render all of the existing subviews and place them in the DOM.
  renderSubViews : function() {
    var content   = $('#content');
    this.panel.add('document_list', this.documentList.render().el);

    if (!dc.account) return;

    this.sidebar.add('account_badge', this.accountBadge.render().el);


The router is used for laying out all of the workspace-level subviews. Each of these subviews is then responsible for laying out specific instances of documents, collections, toolbar items, search facets, etc.

Moving models

Before you can even start playing with Backbone models, you'll need to get your data in a format that Backbone can vivify. Your server should be sending arrays of dictionaries, each array consisting of a single parent model. This may cause versioning on your server end due to having to change the format of your API's response.

Versioning: Objects as dicts vs. arrays

Perhaps you were giving data in a format that made it easy for you to key into the dictionary to retrieve a model, like so:

    64: {
        'id': 64,
        'title': "The NewsBlur Blog"
    128: { ... }

However, in order to vivify these models, Backbone expects an array of dictionaries. We can modify the backend to provide models in this format, by adding a v=2 query paramter:

        'id': 64,
        'title': "The NewsBlur Blog"
    { ... }

Backbone reads through and finds all id attributes and hashes them into the _byId object on the model. You can do this client-side instead of versioning your API, but that would require you to write a custom parse method.

You can then override your collections fetch method to add in the version information. This transparently handles appending a version parameter to your requests.

fetch: function(options) {
    var data = {
        'v': 2

    options = _.extend({
        data: data,
        silent: true
    }, options);
    return, options);

Notice, by the way, the last line is how you call super() in JavaScript. This is a clear demonstration of over-riding methods in Backbone and then calling super at the appropriate time.


If your models were simple JavaScript object literals (dictionaries), then you were using one of these styles to work with attributes:

// JavaScript:


var attr = 'title';

However, Backbone uses a get method to retrieve an attribute from a model:

// Backbone.js:

The trick here is that during a large-scale refactor, you want to change as few things as possible. In this case, you can pass a Backbone model's model.attributes to old Javascript methods. Then when done, clean up by looking for .attributes.

var iconSrc = $.favicon(socialFeed.attributes);
this.$('.NB-header-icon').attr('src', iconSrc);

This way you do not have to immediately rewrite all of your model attribute getters until you have tested the modified parts of your code.

Populating a collection that has side-effects

Looking at feeds and folders above, in order to populate the list of folders you need the feed models. But when populating the feed models, their view is bound to the reset event, which will try to render the feeds, but there are no folders yet!

Pass {silent: true} to the initial reset for feeds, then manually trigger the reset event after the dependencies are met.

Listening for events on a collection's models

Any event that is triggered on a model in a collection will also be triggered on the collection directly, for convenience. This allows you to listen for changes to specific attributes in any model in a collection.

// Bind to all models
Documents.bind('reset',  this.reset);
Documents.bind('add',    this._addDocument);
Documents.bind('remove', this._removeDocument);

// Bind to specific attributes on the collection's models
Documents.bind('change:pages', this._renderPageCount);

The Documents collection contains all of the documents on the page, but you could also create specialized collections with a subset of those models that respond to change events without having to filter the change event on the bigger collection to only apply to those specific models.

Seeing changed attributes

In this case, a model is updated from elsewhere, so it needs to be refreshed on the page. Use model.hasChanged() and model.previousAttributes() to see what's changed.

However, before you may have iterated over all new values and compared to existing values. Backbone has this built in.

// The collection is selective about changing attributes
this.bind('change', this._onModelChanged);
_onModelChanged : function(doc) {
    if (doc.hasChanged('access') && doc.isPending())
// The view is also selective about changing attributes.
// Re-renders the tile if an server-backed attribute changes.
_onDocumentChange : function() {
    if (this.model.hasChanged('selected')) return;

You can short-circuit the change event if you are looking for a specific attribute. But sometimes you want the change event fired only once yet you're looking to do different things based on which attribute has been changed. So instead of relying on each attribute's individual change event, you can wait for the bundled change event.

Naturally, you may be wondering what gets fired first? Each individual change event or the bundled change event? Well, to figure that out we just turn to the Backbone.js source code:

// Call this method to manually fire a `"change"` event for this model and
// a `"change:attribute"` event for each changed attribute.
// Calling this will cause all objects observing the model to update.
change: function(options) {
  for (var i=0, l=triggers.length; i < l; i++) {
    this.trigger('change:' + triggers[i], this, 
                 current[triggers[i]], options);
  this.trigger('change', this, options);

Notice that the individual change attributes are guaranteed to fire before the bundled change event. This goes to show that the source code for Backbone.js is not as thorny and cumbersome to read as other libraries may have led you to believe about all libraries. Backbone.js's source code is easy to follow and is written as close to plain english as possible

Intermediary models

Sometimes an active item needs a bit more meta-data than the non-active counterpart. Take the feed list, for instance. When a feed becomes selected, it needs to be referred to by many other components, each of which needs to know about the active feed. Storing a reference to this model, say ActiveFeed, then allows you to add view-specific meta-data that would be helpful in other views.

NEWSBLUR.Models.Feed.prototype.setSelected = function() {; = this;

NEWSBLUR.Views.FeedList.prototype.findSelected = function() {
    return _.pluck(, '$el');

If you are operating in a loop, then you'll definitely want to cache a reference to a model like this.

Moving views

This part of the process is a bit more involved than moving models or simply constructing routers. This is where most of the cleanup is involved.

Writing Templates

The first thing that needs to be changed is how DOM fragments are constructed. In NewsBlur's case, we're moving from JavaScript element creation to interpolated templates.

Old style: Manual DOM element creation

This style is simply a wrapper around a variety of document.createElement calls, where $.make will take attributes and add them correctly to the newly created element, as well as appending each of the children in a easy-to-read function.

openSocialCommentReplyForm: function($comment) {
    var profile = this.model.userProfile;
    var $form = $.make('div', { className: '...' }, [
        $.make('img',   { className: '...',   src: profile.get('url') }),
        $.make('div',   { className: '...' }, profile.get('username')),
        $.make('input', { className: '...',   type: 'text' }),
        $.make('div',   { className: '...' }, 'Post')
    $('.story-comment-reply-form', $comment).remove();

    $('.comments', $form).bind('keydown', 'enter, return', 
        _.bind(this.saveSocialCommentReply, this, $comment));
    $('.comments', $form).bind('keydown', 'esc', function() {
        $('.NB-story-comment-reply-form', $comment).remove();
    $('input', $form).focus();


While it's easy to read and write, it is not fast. This method is an order of magnitude slower than the better methods described below, each of which use string interpolation to inject data into the template.

Template option #1: inline strings

This is the option that I eventually chose, if only because it was the simplest, could be easily cached by the browser, and was inline with the view code.

render: function() {
    var $feed = $(_.template('\
    <<%= listType %> class="feed">\
      <img class="feed-favicon" src="<%= $.favicon(feed) %>">\
      <span class="feed-title">\
        <%= feed.get("feed_title") %>\
      <div class="feed-exception-icon"></div>\
      <div class="feed-manage-icon"></div>\
    </<%= listType %>>\
    ', {
        feed      : this.model,
        listType  : this.options.type == 'feed' ? 'li' : 'div',


    return this;

Notice that this.setElement is used on the new $feed. The reason for this is because of listType changing the top-level element depending on the location of the feed. In some cases it's part of a list, and in other cases it's a stand-alone feed title. In order to make it semantically correct, different top-level tags are needed, so you can't just use this.$el.html(), otherwise there will still be a top-most div wrapping your view (which can be customized by setting this.tagName).

Also, note that a better way to create these multi-line strings is to use the heredoc (multiline) strings in CoffeeScript. However, the template string still goes inline, which means you do not have to do any asset pre-compiling, which can be more or less difficult depending on your framework.

Template option #2: inline templates

These templates are just <script> tags that go in your HTML templates. The downside to this method is that your JavaScript templates are not cached by the browser and have to be downloaded as part of every page load.

<script type="text/html" id="feed-template">
    <<%= listType %> class="feed">
      <img class="feed-favicon" src="<%= $.favicon(feed) %>" />
      <span class="feed-title">
        <%= feed.get("feed_title") %>
      <div class="feed-exception-icon"></div>
      <div class="feed-manage-icon"></div>
    </<%= listType %>>


render: function() {
    this.template = this.template || $('#feed-template').html();
    var $feed = _.template(this.template, {
        feed      : this.model,
        listType  : this.options.type == 'feed' ? 'li' : 'div',
    return this;

Not recommended, but easy enough to do without a pre-compiler or asset pipeline.

Template option #3: JSTs

This is the recommended method, but it requires you to have a pre-compiler that works in both development and production, referring to your templates individual in development and as a concatenated file in production. Not a big deal to implement, but many asset packagers do not handle JavaScript templates and allow you to wrap them in the appropriate interpolater, such as Underscore.js' _.template.

window.JSTs['feed'] = _.template('<script type="text/html" id="feed-template">'+
                                 '<<%= listType %> class="feed"><img class="feed-favicon" '+
                                 'src="<%= $.favicon(feed) %>" /><span class="feed-title">'+
                                 '<%= feed.get("feed_title") %></span>'+
                                 '<div class="feed-exception-icon"></div>'+
                                 '<div class="feed-manage-icon"></div>'+
                                 '</<%= listType %>></script>');
render: function() {
    var $feed = JSTs['feed']({
        feed      : this.model,
        listType  : this.options.type == 'feed' ? 'li' : 'div',
    return this;

If you are on Ruby on Rails, you can use Jammit, another DocumentCloud project, to automatically handle JavaScript templates. Alternatively, node-jst and sprockets are worth a look.

Event delegation

The most common view change you'll make is moving from event binding to event delegation.

// From:
$(".feed", $feedList).bind('click', function(e) { ... });

// To:
NEWSBLUR.Views.FeedView = Backbone.View.extend({
    events: {
        "click" : "open"

One of the biggest benefits you'll receive by moving to Backbone.js is going from event binding to event delegation. If you're not already familiar with what this is, it is simply attaching all events to the top-level view element and then bubbling any events that happen to a child element up to the parent, where it is caught and delegated to the appropriate method.

This also means that you won't have events bound all over the DOM. And when you destroy views, you know where all of the events are bound and will not have as much work to do in order to prevent memory leaks from events bound to missing elements.

Delegating the same object from multiple views

Sometimes an object on your page can be better represented by different views attached to the same element.

NEWSBLUR.Views.FeedView = Backbone.View.extend({
    initialize: function() { = new NEWSBLUR.Views.FeedMenuView({el: this.el});

NEWSBLUR.Views.FeedMenuView = Backbone.View.extend({
    events: {
        "click" : "open"

In this case it's important to remember that both of these views will be listening for bubbling events. That means that it is possible to create a race condition if you do not know the order these views are instantiated. You will want to be careful in that the separated views do not step on each other's toes.

In this instance the feed title view and the feed menu view are attached at the same place but serve completely different purposes. The feed title view is the "parent" of the menu view, even though they exist at the same level in the DOM hierarchy.

Which element to use

If your top-level element is complicated and you are creating it as part of your render, then you can use setElement instead of $(this.el).html().

var $feed = _.template('<li class="feed"> ... </li>', {

// Would include a surrounding <div>
// $(this.el).html($feed)

But you can't just perform a setElement, because you need to replace the $el if it is on the page:


This is meant for switching between element types. For example, a view that will sometimes go into a list as a list item, but then also be displayed solo, then you will want to control the tagName or just include it as part of your template and use setElement.

View collections

Models should not know about views. So in order to keep track of views, a parent view should encapsulate them and store references.

findFeedInFeedList: function(feedId) {
    var $feeds = $('.feed', $feedList).map(function() {
        var dataId = $(this).data('id');
        if (dataId == feedId) {
            return this;

    return $feeds;

[turns into a view collection on FeedListView]

Recursive subviews

This is a typical case where you want to have a recursive subview that can contain more of itself. In this case, we have feeds and folders, and both can be children of folders. To accomplish this hierarchy, we just have to descend down the chain, rendering each subview and keeping track of each child view.

NEWSBLUR.Views.Folder = Backbone.View.extend({
    render: function() {
        var depth = this.options.depth;
        var $feeds = {
            if (item.isFeed()) {
                var feed = new NEWSBLUR.Views.Feed({
                    model: item.feed, 
                    depth: depth
                return feed.el;
            } else {
                var folder = new NEWSBLUR.Views.Folder({
                    model: item,
                    collection: item.folders,
                    depth: depth + 1
                return folder.el;

        var $folder = this.renderFolder();
        return this;

Traversing a view

When moving from story to story or feed to feed, you want to move in the order of what's on screen. The order is handled by the collection, but keeping track of the active model is something you have to do manually.

// Go to the next feed. Old style:

// New style:
Feeds.activeFeed =;
Feeds.activeFeed.set('selected', true);

The method can be a complicated method that walks your recursive hierarchy. But that's hidden away and you can just call that method idempotently.

Action hierarchy

Views handle their own actions, but what about cross-view actions? One view modifies another view. Propagate that up to the Router or parent view that is drawing the views. Have the parent talk to the necessary models, changing appropriate data.

Once the data is changed, the correct views will update, based on their triggers and bindings.

For instance, if you are deleting a feed, the context menu view, which knows which $feed is being deleted, sends that info to the model, which then scans its own views and triggers the removal on the correct one. Finally, an AJAX request is made (this is optimistic) in the Router.

NEWSBLUR.Views.FeedMenu = Backbone.View.extend({
    deleteFeed: function() {

NEWSBLUR.Models.Feed = Backbone.Model.extend({
    removeFeedFromFolder: function(folder) {
        this.feedViews.chain().select(function(feedView) {
            return feedView.folder == folder;
        }).each(function(feedView) {

No need for a model to back a view

Some views just don't have models. They control a visual element on the page but have no corresponding server model. The closest object they have to a model is the page itself or the user.

This means you need to keep a reference to the view. You can't just rely on the model to update the view. Other times you do have a model. If the model for the view would change depending on the model, you can just render a new view with the correct model and replace it on the page.

Common pitfalls

TypeError: 'undefined' is not an object (evaluating 'func.bind')

This error comes from trying to bind to a method that doesn't exist. But you don't get the name or line of the error, so the only way to debug it is to set a breakpoint and work your way up the stack.

_.bindAll(this, 'render', 'open', 'methodRemovedAndWillThrowTypeError');

Firing a change event while still setting up models and views

Add {silent: true} to a model.set() call if you're not ready to handle the change events.

Selectively re-render/toggle Classes based on specific change events.

Sometimes an attribute change merely results in a changed class on the element, not a full render. One technique you can use is to bind to the bundled change event and then selectively look for attributes that only result in a class change.

onChange: function() {
    var onlyClasses = _.all(_.keys(this.model.changed), function(change) {
        return _.contains(['selected', 'has_exception'], change);

    if (onlyClasses) {


Here, we're checking that every changed attribute is one that results in a class change. Otherwise, do the full render.

Cleanup of ghost views

When removing a view, you need to both remove it from the DOM and then unbind it. The model still has bindings to the destroyed view.

// Parent view:

// View:
initialize: function() {
    this.model.bind('change', this.render);

destroy: function() {
    this.model.unbind('change', this.render);

This has changed in the latest version of Backbone.js, but it's not yet released (the coming version 1.0), so you have to manually destroy both the views and view's event bindings.

The disappearing view

Before Backbone, views would not automatically update from beneath you. Now that views are tied to models, check to see if you are modifying a view post-render, just as inserting a special sub-view that the parent view doesn't know about. Because when the view re-renders, it won't know to re-insert the subview.


A couple resources that I like are:

As always, make sure to read the source of Backbone.js to see if you can just figure out what's happening under the hood.

I'm @samuelclay on GitHub, where you can follow me to watch the development of the NewsBlur front-end, back-end, iOS and Android apps. And I'm @samuelclay on Twitter where you can ask me further questions about Backbone.js.

Jan 09

Old-style Mac OS X Leopard Exposé in Snow Leopard

Progress is progress, except when it gets in the way of your workflow. Let's compare these two screenshots:

Old-style Leopard Exposé

New-style Snow Leopard Exposé

Notice how much more pleasant the old-style Exposé is? Introduced in Mac OS X 10.3 Panther, and virtually unchanged until OS X 10.6 Snow Leopard, it featured proportional windows. By just looking at the size of the window relative to the other windows, you can get a fair idea of what the application is.

The proportional windows went out the window with the new Exposé. Now it features an inexplicable grid, with windows resized to all different dimensions relative to their original size.

Old-style Exposé in Snow Leopard

The great news is that you can get the old-school Exposé back. The beta builds of Snow Leopard included a new that used the old-style exposé. By installing the old, you get the new Dock features of Snow Leopard, while preserving the legendary Exposé.


  1. Download the Snow Leopard beta-build of
  2. Save to your Desktop and unzip.

Run the following commands in

sudo chown -R root ~/Desktop/;
sudo chgrp -R wheel ~/Desktop/;
sudo killall Dock && \
sudo mv /System/Library/CoreServices/ ~/Desktop/ && \
sudo mv ~/Desktop/ /System/Library/CoreServices/

Easy to do and indispensible now that you have it back. Hat-tip to miknos at MacRumors for the original find.

Note that you will have to repeat this process every time you upgrade your Mac OS to a new patch release (10.6.6 -> 10.6.7).

@samuelclay is on Twitter.

Use Google Reader? I built NewsBlur, a new feed reader with intelligence.

Nov 03

What Happened to NewsBlur: A Hacker News Effect Post-Mortem

Last week I submitted my project, NewsBlur, a feed reader with intelligence, to Hacker News. This was a big deal for me. For the entire 16 months that I have been working on the project, I was waiting for it to be Hacker News ready. It's open-source on GitHub, so I also had the extra incentive to do it right.

And last week, after I had launched premium accounts and had just started polishing the classifiers, I felt it was time to show it off. I want to show you what the Hacker News effect has been on both my server and my project.

Hacker News As the Audience

When I wasn't writing code on the subway every morning and evening, I would think about what the reaction on Hacker News would be. Would folks find NewsBlur too buggy? Would they be interested at all? Let me tell you, it's a great motivator to have an audience in mind and to constantly channel them and ask their opinion. Is a big-ticket feature like Google Reader import necessary before it's Hacker News ready? It would take time, and time was the only currency which I could pay with. In my mind, all I had to do was ask. ("Looks cool, but if there's no easy way to migrate from Google Reader, this thing is dead in the water.")

Kurt Vonnegut wrote: "Write to please just one person. If you open a window and make love to the world, so to speak, your story will get pneumonia." (From Vonnegut's Introduction to Bagombo Snuff Box.)

Let's consider Hacker News as that "one person," since for all intents, it is a single place. I wasn't working to please every Google Reader user: the die-hards, the once-in-a-seasons, or the twitter-over-rss'ers. For the initial version, I just wanted to please Hacker News. I know this crowd from seeing how they react to any new startup. What's the unique spin and what's the good use of technology, they would ask. What could make it better and is it good enough for now?

If you're outsourcing tech and just applying shiny visuals to your veneer, the Hacker News crowd sniffs it out faster than a beagle in a meat market. So I thought the best way to appeal to this crowd is to actually make decisions about the UI that would confuse a few people, but enormously please many people. From comments on the Hacker News thread, it looks like I didn't wait too long.

How the Server Handled the Traffic

Have I got some graphs to show you. I use munin, and god-love-it, it's fantastic for monitoring both server load and arbitrary data points. I watch the load on CPU, load average, memory consumption, disk usage, db queries, IO throughput, and network throughput (both to external users and to internal private IPs).

I also have a whole suite of custom graphs to watch how many intelligence classifiers users are making, how many feeds and subscriptions users are adding, the rate of new users, premium users, old users returning, new users sticking around, and load times of feeds (rolling max, min, and average).

Used to be that when a thundering herd of visitors came to NewsBlur, I'd have to watch the server nervously, as CPU would smack 400% (on a 4-core machine), the DB would thrash on disk, and inevitably some service or another would become overrun.

Let's see the CPU over the past week:

CPU - Past week

Spot the onslaught? NewsBlur's app server is only responsible for serving web requests, queueing feeds to be updated, and calculating unread counts. Needless to say, even with nearly a thousand new users, I offloaded so much of the CPU-intensive work to the task servers that I didn't have a single problem in serving requests.

This is a big deal. The task server was overwhelmed (partially due to a bug, but partially because I was fetching tens of thousands of new feeds), but everybody who wanted to see NewsBlur still could. Their web requests, and loading each feed, were near instantaneous. It was wonderful to watch it happen, knowing that everybody was being served.

CPU - Past year

Clearly, bugs have been fixed, and CPU-intensive work has been offloaded to task servers.

Load average - Past week

The load of the server went up and stayed up. Why did it not fall back down? Because the app server is calculating unread counts, it has more work to do even after the users are gone. This will become a pain point when one app server is not enough for the hundreds of concurrent users NewsBlur will soon have. But luckily, app servers are the easiest to scale out, since each user will only use one app server at a time, so the data only has to be consistent on that one server, as it propagates out to the other app servers (which may become db shards, too).

# of feeds and subscriptions - Past week

Economies of scale. The more feeds I have, the more likely a subscription to a feed will be on a feed that already exists. I want that yellow line to run off into space, leaving the green line to grow linearly. It's fewer feeds to fetch.

Memory - Past week

Memory doesn't move, because I'm being CPU bound. I'm not actually moving all that much more data around. I use gunicorn to rotate my web workers, so NewsBlur's few memory leaks can be smoothed over.

MongoDB Operations - Past week

I use MongoDB to serve stories. All indexes, no misses (there's a graph for this I won't bother showing). You can extrapolate traffic through this graph. Sure, you don't know average feeds per user, but you can take a guess.

My Way of Building NewsBlur

In order to build all of the separate pieces, I broke everything down into chunks that could be written down and crossed off. Literally written down. I have all of my priorities from the past 7 months. It's both a motivator and estimator. I've learned how to estimate work load far better than back in May, when these priorities start. I finish more of what I tried to start.

The way it works is simple: write down a priority for the month it's going to be built in, number it, then cross it off if it gets built before the end of the month. You get to go back and see how much you can actually do, and what it is you wanted to build. This means I'm setting myself up for a pivot every month, when I re-evaluate what it is I'm trying to build.

Google Reader as a Competitor

Lastly, what more could you ask for? A prominent competitor, known to every Gmail user as the empty inbox link. Feed reading is a complicated idea made simple by having most users already exposed to a product that fulfills the feed reading need. By improving over that experience, users can directly compare, instead of having to learn NewsBlur on top of learning how to use RSS and track every site you read.

If your space has a major competitor and the barrier to entry is an OAuth import away, then consider yourself lucky. Anybody can try your product and become paid customers in moments. It's practically a Lotus123 to Excel import/export, except you don't need to buy the software before you try it out.

Going Forward

I'm half-way to being profitable. I only need 35 more premium subscribers. But so far, people are thrilled about the work I'm doing. Here are some tweets from a sample of users:

I'm e-mailing blogs, chatting with folks who have a blog influence, and most importantly, continuing to launch new features and fix old ones. Thanks to Hacker News, I get to appeal to a graceful and sharp audience. And good looking.

I'm on Twitter as @samuelclay, and I'd love to hear from you.

Aug 22

There are Two Paper Towel Rolls

It's almost time to restock, but the shelf can only hold 5 rolls, so you might as well restock at an appropriate time. But you have to choose which of the two remaining rolls is going in the business end of the side-gripping dispenser.

I can choose the larger of the two rolls. The Mega-Roll. Or I can choose the standard size, which is visibly puny compared to the bigger choice. If you know the answer, it seems obvious, and that's because it's an obvious answer.

But it's not so obvious if you start thinking about why choose one in the first place. The larger roll is larger, but does that mean it should go first simply because it is preferable? The assumption is that you don't like changing rolls often and you don't think larger rolls look or work any differently than their smaller counter-part.

And maybe the smaller roll has preference, just to get it out of the way for more Megas when it's time to buy more. You need to remember to buy more. What causes you to remember to buy more? Absence or a dwindling stock. Once you get down to having one left, and it gets placed into service, you commit to memory that you need to stock up next time you remember. It's a modified version of The Game that you play with yourself, except that by remembering, you win.

The smaller roll goes in first, so that at exhaustion the larger roll has a longer opportunity for you to remember to buy more. Nothing shocks you more than an absence.

Jul 18

Migrating Django from MySQL to PostgreSQL the Easy Way

I recently moved NewsBlur from MySQL to PostgreSQL for a variety of reasons, but most of all I want to use connection pooling and database replication using Slony, and Postgres has a great track record and community. But all of my data was stored in MySQL and there is no super easy way to move from one database backend to another.

Luckily, since I was using the Django ORM, and with Django 1.2's multi-db support, I can use Django's serializers to move the data from MySQL's format into JSON and then back into Postgres.

Unfortunately, If I were to use the command line, every single row of my models has to be loaded into memory. Issuing commands like this:

python dumpdata --natural --indent=4 feeds > feeds.json

would take a long, long time, and it wouldn't even work since I don't have even close to enough memory to make that work.

Luckily, the dumpdata and loaddata management commands are actually just wrappers on the internal serializers in Django. I decided to iterate through my models and grab 500 rows at a time, serialize them and then immediately de-serialize them (so Django could move from database to database without complaining).

import sys
from django.core import serializers

def migrate(model, size=500, start=0):
    count = model.objects.using('mysql').count()
    print "%s objects in model %s" % (count, model)
    for i in range(start, count, size):
        print i,
        original_data =  model.objects.using('mysql').all()[i:i+size]
        original_data_json = serializers.serialize("json", original_data)
        new_data = serializers.deserialize("json", original_data_json, 
        for n in new_data:


This assume that you have both databases setup in your like so:

    'mysql': {
        'NAME': 'newsblur',
        'ENGINE': 'django.db.backends.mysql',
        'USER': 'newsblur',
        'PASSWORD': '',
    'default': {
        'NAME': 'newsblur',
        'ENGINE': 'django.db.backends.postgresql_psycopg2',
        'USER': 'newsblur',
        'PASSWORD': '',

Note that I changed my default database to the Postgres database, because otherwise some management commands would still try to run on the default MySQL database. This is probably resolved and I didn't do something right, but when I migrated, I changed Postgres to be the default database.

I just run the short script in the Django console and wait however long it takes. This script prints out which set it's working on, so you can at least track the progress, which might take a long, long time, but is much less prone to crashing like dumpdata and loaddata.

A word of warning to those with large datasets. Instead of iterating straight through the table, see if you have a handier index already built on the table. I have a table with a million rows, but there are a few indices which can quickly find stories throughout the table, rather than having to order and offset the entire table by primary key. Adapt the following code to suit your needs, but notice that I use an index on the Feed column in the Story table.

import sys
from django.core import serializers

def migrate_with_model(primary_model, secondary_model, offset=0):
    secondary_model_data = secondary_model.objects.using('mysql').all()
    for i, feed in enumerate(secondary_model_data[offset:].iterator()):
        stories = primary_model.objects.using('mysql').filter(story_feed=feed)
        print "[%s] %s: %s stories" % (i, feed, stories.count())
        original_data = serializers.serialize("json", stories)
        new_data = serializers.deserialize("json", original_data, 
        for n in new_data:

migrate_with_model(primary_model=Story, secondary_model=Feed)

This makes it much faster, since I only have to sort a few hundreds records rather than the entire Story table and its million rows.

Also of note is that while all of the data made it into the Postgres tables, the sequences (counts) were all off. Many were at 0. To remedy this easily, just use the count of the table itself and store it in the sequence table, like so:

select setval('rss_feeds_tag_id_seq', max(id)) from rss_feeds_tag;
select setval('analyzer_classifierauthor_id_seq', max(id)) from analyzer_classifierauthor;            
select setval('analyzer_classifierfeed_id_seq', max(id)) from analyzer_classifierfeed;              
select setval('analyzer_classifiertag_id_seq', max(id)) from analyzer_classifiertag;               
select setval('analyzer_classifiertitle_id_seq', max(id)) from analyzer_classifiertitle;             
select setval('analyzer_featurecategory_id_seq', max(id)) from analyzer_featurecategory;

I just made a quick text macro on the table names. This quickly set all of the sequences to their correct amounts.

This post has been translated to Spanish by Maria Ramos.

Jun 28

NewsBlur: Most Watched This Week

It's always nice to see that after working on a project for 13 months, people are finally starting to use it. The source behind NewsBlur is available on GitHub: And recently, in response to a Hacker News thread about why RSS readers sucks, I linked to NewsBlur and explained my rationale:

I think I created a very nice feed reading experience with NewsBlur:

It shows the original site, allows you to read as you normally would, but keeps track of the stories you're scrolling past.

It also allows you to filter stories based on what you like and dislike about them: words/phrases in the title, tags and categories, authors, and the publisher themselves. There is a slider that allows you to show/hide stories based on this filter. It's very fast, too.

I am writing an iPhone app so you can use NewsBlur everywhere. It's just a hobby project, and people have so far been impressed. But I would love for NewsBlur to become a useful tool that people choose to use.

I wrote it because I was also dissatisfied with readers, especially Google Reader. I also knew Python (Django!), JavaScript, and wanted to put them together to test my abilities.

Currently, I am writing the iPhone app that will allow NewsBlur to be useful to a significant portion of Internet users who read RSS. Everybody that I have talked to says they are waiting for a good mobile version before they sink in time and curation into NewsBlur. Let's hope I am not underestimating when I say 1-2 months.

Mar 24

Code Snippet: jQuery Edit In Place

There are many solutions to the edit-in-place problem, but I wanted to make an easy solution that wasn't as complicated as some of the other edit-in-place JavaScript scripts, like jEditable.


  1. Detects surroundings and keeps the input container as either a block or inline display.
  2. Highlights text if it is the original text. If the text has changed, the entire text is not highlighted on edit.
  3. Easy customizable and styleable.


Test Input: Click here to change this text.

JavaScript Code

(function($) {
        edit_in_place: function(opts, callback) {
            var self = this;
            var defaults = {
                'input_type': 'text'
            var options = $.extend({}, defaults, opts);

            return this.each(function() {
                var $this = $(this);
                var $input;
                var original_value = $this.html().replace(/<br.*?>/g, '\n');
                var original_display = $this.css('display');

                $this.bind('click', function() {
                    var starting_value = $this.html().replace(/<br.*?>/g, '\n');

                    if (options['input_type'] == 'text') {
                        $input = $.make('input', { type: 'text', name: 'eip_input', value: starting_value });
                    } else if (options['input_type'] == 'textarea') {
                        $input = $.make('textarea', { name: 'eip_input' }, starting_value);

                    var $form = $.make('div', { className: 'eip-container' }, [
                        $.make('button', { className: 'eip-submit' }, 'OK'),
                        $.make('button', { className: 'eip-cancel' }, 'Cancel')

                    $this.css({'display': 'none'});
                    if (original_value == starting_value) {

                    var restore_input = function(input) {
                        return function($this, $form) {
                            $this.css({'display': original_display});
                            if (input) {
                                $this.html(input.replace(/[\n\r]+/g, "<br /><br />"));
                                $.isFunction(callback) &amp;&amp;, input);
                        }($this, $form);

                    setTimeout(function() {
                        $(document).one('click.edit_in_place', function() {
                        $ {
                            if ( == 'eip-cancel') {
                            } else if ( == 'eip-submit') {
                            return false;
                    }, 10);



        make: function(){
            var $elem,text,children,type,name,props;
            var args = arguments;
            var tagname = args[0];
                if (typeof args[1]=='string'){
                    text = args[1];
                }else if(typeof args[1]=='object' &amp;&amp; args[1].push){
                  children = args[1];
                    props = args[1];
                if(typeof args[2]=='string'){
                    text = args[2];
                }else if(typeof args[1]=='object' &amp;&amp; args[2].push){
                  children = args[2];
            if(tagname == 'text' &amp;&amp; text){
                return document.createTextNode(text);
                $elem = $(document.createElement(tagname));
                    for(var propname in props){
                      if (props.hasOwnProperty(propname)) {
                            if($':input') &amp;&amp; propname == 'value'){
                            } else {
                                $elem.attr(propname, props[propname]);
                    for(var i=0;i&lt;children.length;i++){
                return $elem;


To use this code, simply use this HTML, CSS, and small JavaScript snippet:

<div class="eip">
    Test Input: <span class="eip-text">Click here to change this text.</span>

And this CSS:

.eip {
    font-family: Helvetica;
    font-size: 16px;

.eip .eip-text {
    font-weight: bold;
    padding: 2px 3px;
    border: 1px solid white;

.eip .eip-container {
    display: inline;

.eip input {
    font-family: Helvetica;
    font-size: 16px;
    font-weight: bold;
    padding: 2px;
    border: 1px solid #A0A0A0;
    display: inline;
    width: 250px;

And this simple piece of JavaScript, which includes a callback function that has the same scope as the original selectors:

$(document).ready(function() {
    $('.eip .eip-text').edit_in_place({}, function() {
        var $this = $(this);
        $this.animate({'backgroundColor': 'orange'}, {'duration': 300, 'queue': false, 'complete': function() {
            $this.animate({'backgroundColor': 'white'}, {'duration': 300, 'queue': false});

Note that I am animating background colors in this small JavaScript snippet. To animate colors, you need John Resig's excellent jQuery.color.js.

Samuel Clay is the founder of NewsBlur, a trainable and social news reader for web, iOS, and Android. He is also the founder of Turn Touch, a startup building hardware automation devices for the home. He lives in San Francisco, CA, but misses Brooklyn terribly. In another life in New York, he worked at the New York Times on DocumentCloud, an open-source repository of primary source documents contributed by journalists.

Apart from NewsBlur, his latest projects are Hacker Smacker, a friend/foe system for Hacker News, and New York Field Guide, a photo-blog documenting New York City's 90 historic districts. You can read about his past and present projects at

Follow @samuelclay on Twitter.

You can email Samuel at He loves receiving email from new people. Who doesn't?