Published March 13, 2017 © MIT

Drop of Life

A display to remind me when I can donate blood and save lives, powered by the Red Cross API and Particle.

IntermediateFull instructions provided10 hours1,662

Things used in this project

Hardware components

Particle Photon

Adafruit 0.8" 8x16 LED Matrix FeatherWing Display - Red

OpenBuilds Wire Cable - By the Foot

Hand tools and fabrication machines

3D Printer (generic)

Soldering iron (generic)

Story

Ideation

Giving blood saves lives and it's something I've done regularly since I turned 16. Sadly I will sometimes forget to donate for several months. I built the Drop of Life as a way to gently remind me when I'm eligible to donate blood.

The project uses a Particle Photon Wi-Fi microcontroller to query the Red Cross API for my blood donation eligibility date. A grid of red LED forms a drop that fills up as the date gets closer. It gently glows when I'm able to donate. After a donation, the Red Cross takes care of updating my next eligible date in their API so the drop will empty completely automatically!

Ready to save lives!

Electronics

Project parts

The LED matrix is an 8x16 LED shield by Adafruit. Driving those LEDs from a microcontroller would require a lot of pins so the shield uses a HT16K33 LED matrix driver. You give it an array of data, one byte per row in this case, over I2C and it takes care of lighting the appropriate LEDs. I followed the instructions from Adafruit to assemble the shield.

LED matrix assembled

To connect the shield to the Particle Photon I used a piece of perforated circuit board and 12-pin headers. Only 4 wires are needed between the LED shield and the Photon: ground, 3.3V, I2C clock (SCL) and I2C data (SDA).

Electronic sandwich

Case

I wanted a case that would show the drop shape even with the LEDs off.

I designed a box in Fusion 360 to fit the LED matrix, shield and Photon. In the front, I cut a hole in the shape of a drop, lining up the outline with the position of the LEDs.

The steps to build the case in Fusion 360

I 3D printed the main part of the box and back with usual parameters. I 3D printed a plate to fill the drop-shape hole exactly, using only perimeters to create a swirling effect.

Case printed in white PLA

Everything fit nicely inside with room for a 90-degree angle USB cable to provide power.

Electronics in case

Program

The program does the following:

Load up my Red Cross username and password from permanent storage

Interact with the Red Cross API using Particle webhooks

Display the drop filled to the right level on the LED matrix

The full source code is available on GitHub.

Storage

For storage, I'm using the built-in EEPROM functionality to load and store strings on the Photon across reboots.

struct Storage { 
 uint16_t app; 
 uint8_t username[32]; 
 uint8_t password[32]; 
} storage;
void setup() {
  EEPROM.get(0, storage);
  Particle.function("login", setCredentials);
}
int setCredentials(String arg) {
  // parse arg, update storage.username and storage.password
  EEPROM.put(0, storage);
  return 0;
}

To set the password, I called the "login" function on my device from the Particle Desktop IDE.

Sending my secret password to the device

Red Cross

The easiest way to interact with external APIs on a Particle device is using webhooks. This means publishing an event in the Photon firmware and letting the Particle cloud do the HTTPS request and JSON parsing.

To log in to the Red Cross, I publish an event with the username and password, and subscribe to the response.

String token = "";
Particle.subscribe(
  "hook-response/red_cross/login", 
  setRedCrossToken, 
  MY_DEVICES 
);  
String data = String::format(
  "{\"username\":\"%s\",\"password\":\"%s\"}",
  storage.username,
  storage.password
);
Particle.publish("red_cross/login", data, PRIVATE);
void setRedCrossToken(const char *event, const char *data) { 
  token = data;
}

In the Particle Console, I add a webhook to call the Red Cross login API endpoint in with the username and password in JSON format. The response JSON will contain the token key. Since this is the only piece of data the firmware needs, I use a Response Template to extract that key and return it to the firmware.

Webhook to perform login on the Red Cross API

To get the blood donation eligibility date, I publish a different event and subscribe to the response.

long eligibility = 0;
Particle.subscribe( 
  "hook-response/red_cross/eligibility", 
  setEligibility, 
  MY_DEVICES 
); 
String data = String::format("{\"token\":\"%s\"}", token.c_str()); 
Particle.publish("red_cross/eligibility", data, PRIVATE);
void setEligibility(const char *event, const char *data) { 
  // parse string into year, month, day
  // ...
  // convert calendar date into timestamp (seconds since 1970)
  tm date; 
  memset(&date, 0, sizeof(tm)); 
  date.tm_year = year - 1900; 
  date.tm_mon = month - 1; 
  date.tm_mday = day; 
  eligibility = mktime(&date); 
}

In the Particle Console, I add a webhook to call the Red Cross user API endpoint. I add the token I got above as a header. The response JSON will contain a lot of data. For now, I’m only interested in the next blood donation eligibility date so I use a Response template of {{history.eligibility.blood}} to get only this value in the firmware.

Webhook to get history of blood donations on the Red Cross API

From this date and today’s date, I calculate the fraction of the 8 weeks in between donations that has passed. This value is used in the display code.

The eligibility date is refreshed once per hour.

Display

I had previously worked with the HT16K33 LED matrix display chip, so I had written some code to talk to it. I published this code as the HT16K33-LED library.

Add the library using the "Browse libraries" button in the Desktop IDE.

To start the display, initialize the I2C connection.

#include "HT16K33-LED.h"
HT16K33 display;
display.begin();

To draw something fill an array with data and send it to the display.

I sketched the blood drop as an 8 by 16 image. To draw it, I created 2 constant arrays in memory and draw lines from the FULL array up until the desired level then draw lines from the EMPTY array. I also realized that the array elements sent to the HT16K33 of the display didn't line up with the rows of the display, so I had to use a custom row mapping.

const uint8_t DROP_FULL[ROWS] = { 
 0b00010000, 
 0b00010000, 
 0b00111000, 
 0b00111000, 
 0b01111100, 
 0b01111100, 
 0b01111110, 
 0b11111110, 
 0b11111111, 
 0b11111111, 
 0b11111111, 
 0b11111111, 
 0b11111111, 
 0b11111111, 
 0b01111110, 
 0b00111100, 
}; 
const uint8_t DROP_EMPTY[ROWS] = { 
 0b00010000, 
 0b00010000, 
 0b00101000, 
 0b00101000, 
 0b01000100, 
 0b01000100, 
 0b01000010, 
 0b10000010, 
 0b10000001, 
 0b10000001, 
 0b10000001, 
 0b10000001, 
 0b10000001, 
 0b10000001, 
 0b01000010, 
 0b00111100, 
}; 
const uint8_t LINE_TO_ROW[ROWS] = { 
 15, 
 13, 
 11, 
 9, 
 7, 
 5, 
 3, 
 1, 
 14, 
 12, 
 10, 
 8, 
 6, 
 4, 
 2, 
 0, 
};
uint8_t lines[ROWS]; 
for (int i = 0; i < ROWS; i++) { 
  uint8_t row = LINE_TO_ROW[i]; 
  lines[row] = (i < ROWS - level) ? DROP_EMPTY[i] : DROP_FULL[i]; 
} 
display.writeDisplay(lines, 0, ROWS);

To be able to easily show the project, it does a demo at boot. It starts empty, then fills over 8 seconds.

After this demo, the level of the drop is 0 (empty) if the last donation was today, 8 at the mid-point in between donations and 16 if the next eligible donation is today or in the past.

Putting it together

It was fun working on this project. It shows the power of the Particle platform and helps nudge me to do something good.

Time to go donate!

Schematics

Code

drop-of-life.ino

/*
 * Drop of Life
 * Julien Vanier <jvanier@gmail.com>
 */

#include "Particle.h"
#include "HT16K33-LED.h"
#include <time.h>
#include <stdlib.h>

PRODUCT_ID(3599);
PRODUCT_VERSION(1);

SYSTEM_THREAD(ENABLED);

constexpr long minutesToMs(long minutes) { return minutes * 60 * 1000; }
constexpr long weekToSeconds(long week) { return week * 7 * 24 * 60 * 60; }

HT16K33 display;
const int ROWS = 16;
const int MAX_LEVEL = ROWS - 1;
const long ELIGIBILITY_UPDATE_INTERVAL = minutesToMs(60);
const long REDCROSS_DONATION_INTERVAL = weekToSeconds(8);

int level = 0;

void setup() {
  Serial.begin();
  setupStorage();
  setupDisplay();
}

void loop() {
  processCloud();
  processRedCross();
  processDisplay();
}

void processCloud() {
  static bool didConnect = false;
  if (!didConnect && Particle.connected()) {
    registerStorage();
    registerRedCross();
    registerDisplay();
    didConnect = true;
  }
}

/* Persistent storage in the EEPROM */

const uint16_t DROP_OF_LIFE_APP = ('D'<<8 | 'L');
struct Storage {
  uint16_t app;
  uint8_t username[32];
  uint8_t password[32];
} storage;

void setupStorage() {
  loadStorage();
}

void registerStorage() {
  Particle.function("login", setCredentials);
}

void loadStorage() {
  EEPROM.get(0, storage);
  if (storage.app != DROP_OF_LIFE_APP) {
    storage.app = DROP_OF_LIFE_APP;
    storage.username[0] = '\0';
    storage.password[0] = '\0';
    storeStorage();
  }
}

void storeStorage() {
  EEPROM.put(0, storage);
}

int setCredentials(String arg) {
  Serial.println("Set credentials");
  int comma = arg.indexOf(",");
  if (comma < 0) {
    return -1;
  }
  String username = arg.substring(0, comma);
  String password = arg.substring(comma + 1);
  username.getBytes(storage.username, sizeof(storage.username));
  password.getBytes(storage.password, sizeof(storage.password));
  storeStorage();
  return 0;
}

/* Red Cros API interactions */

String token;

#define EVENT_RC_LOGIN "red_cross/login"
#define EVENT_RC_ELIGIBILITY "red_cross/eligibility"

time_t eligibility = 0;

void registerRedCross() {
  Particle.subscribe(
    System.deviceID() + "/hook-response/" EVENT_RC_LOGIN,
    setRedCrossToken,
    MY_DEVICES
  );
  Particle.subscribe(
    System.deviceID() + "/hook-response/" EVENT_RC_ELIGIBILITY,
    setEligibility,
    MY_DEVICES
  );
}

void processRedCross() {
  static bool didLogin = false;
  static long lastUpdate = -ELIGIBILITY_UPDATE_INTERVAL;

  if (!Particle.connected()) {
    return;
  }

  if (!didLogin) {
    if (loginToRedCross()) {
      didLogin = true;
    }
  }

  if (didLogin && (millis() - lastUpdate > ELIGIBILITY_UPDATE_INTERVAL)) {
    if (updateEligibility()) {
      lastUpdate = millis();
    }
  }

  setLevelFromEligibility();
}

void setLevelFromEligibility() {
  long now = Time.now();
  if (eligibility != 0 && now != 0) {
    if (eligibility < now) {
      level = MAX_LEVEL;
    } else {
      level = MAX_LEVEL - ((eligibility - now) * MAX_LEVEL / REDCROSS_DONATION_INTERVAL);
    }
  }
}

void setRedCrossToken(const char *event, const char *data) {
  Serial.println("Got token");
  token = data;
}

bool loginToRedCross() {
  if (storage.username[0] == '\0' || storage.password[0] == '\0') {
    return false;
  }
  String data = String::format(
    "{\"username\":\"%s\",\"password\":\"%s\"}",
    storage.username,
    storage.password
  );
  Particle.publish(EVENT_RC_LOGIN, data, PRIVATE);
  return true;
}

bool updateEligibility() {
  if (token.length() == 0) {
    return false;
  }
  String data = String::format("{\"token\":\"%s\"}", token.c_str());
  Particle.publish(EVENT_RC_ELIGIBILITY, data, PRIVATE);
  return true;
}

void setEligibility(const char *event, const char *data) {
  Serial.println("Got eligibility date " + String(data));
  // convert string into time
  String dateStr = data;
  int dash1 = dateStr.indexOf("-");
  int dash2 = dateStr.indexOf("-", dash1+1);
  if (dash1 < 0 || dash2 < 0) {
    return;
  }
  int year = dateStr.substring(0, dash1).toInt();
  int month = dateStr.substring(dash1 + 1, dash2).toInt();
  int day = dateStr.substring(dash2 + 1).toInt();

  tm date;
  memset(&date, 0, sizeof(tm));
  date.tm_year = year - 1900;
  date.tm_mon = month - 1;
  date.tm_mday = day;

  eligibility = mktime(&date);
}

/* Display */

void setupDisplay() {
  display.begin();
}

void registerDisplay() {
  Particle.function("demo", startDemo);
}

const uint8_t DROP_FULL[ROWS] = {
  0b00010000,
  0b00010000,
  0b00111000,
  0b00111000,
  0b01111100,
  0b01111100,
  0b01111110,
  0b11111110,
  0b11111111,
  0b11111111,
  0b11111111,
  0b11111111,
  0b11111111,
  0b11111111,
  0b01111110,
  0b00111100,
};

const uint8_t DROP_EMPTY[ROWS] = {
  0b00010000,
  0b00010000,
  0b00101000,
  0b00101000,
  0b01000100,
  0b01000100,
  0b01000010,
  0b10000010,
  0b10000001,
  0b10000001,
  0b10000001,
  0b10000001,
  0b10000001,
  0b10000001,
  0b01000010,
  0b00111100,
};

const uint8_t LINE_TO_ROW[ROWS] = {
  15,
  13,
  11,
  9,
  7,
  5,
  3,
  1,
  14,
  12,
  10,
  8,
  6,
  4,
  2,
  0,
};

/* run demo once at startup */
int demoLevel = 0;
long demoTime = 0;

int startDemo(String) {
  demoLevel = 0;
  demoTime = millis();
  return 0;
}

void processDisplay() {
  if (demoLevel >= 0) {
    runDemo();
  } else {
    displayDrop(level);
  }
}

void runDemo() {
  static const long DEMO_DELAY = 1000;
  displayDrop(demoLevel);
  if (millis() - demoTime > DEMO_DELAY) {
    demoLevel++;
    demoTime = millis();
  }

  if (demoLevel >= MAX_LEVEL + 15) {
    demoLevel = -1;
  }
}

void displayDrop(uint8_t level) {
  uint8_t lines[ROWS];
  for (int i = 0; i < ROWS; i++) {
    uint8_t row = LINE_TO_ROW[i];
    lines[row] = (i < ROWS - level) ? DROP_EMPTY[i] : DROP_FULL[i];
  }
  display.writeDisplay(lines, 0, ROWS);
  updateBrightness(level);
}

void updateBrightness(uint8_t level) {
  static const int defaultBrightness = 9;
  static int brightness = 9;
  static const long FADE_INTERVAL = 300;
  static int fadeDirection = 1;
  static const int maxFadeBrightness = 14;
  static const int minFadeBrightness = 6;
  static long fadeTime = 0;

  if (level < MAX_LEVEL) {
    brightness = defaultBrightness;
  } else {
    if (millis() - fadeTime > FADE_INTERVAL) {
      brightness += fadeDirection;
      if (brightness >= maxFadeBrightness) {
        fadeDirection = -1;
      } else if (brightness <= minFadeBrightness) {
        fadeDirection = 1;
      }
      fadeTime = millis();
    }
  }
  display.setBrightness(brightness);
}

Credits

Julien Vanier

10 projects • 64 followers

Drop of Life

Things used in this project

Hardware components

Hand tools and fabrication machines

Story

Ideation

Electronics

Case

Program

Storage

Red Cross

Display

Putting it together

Custom parts and enclosures

Case

Drop

Back lid

Schematics

Circuit

Code

drop-of-life.ino

Photon code, Fritzing diagram and 3D models

Credits

Julien Vanier

Comments

Embed the widget on your own site

Drop of Life

Drop of Life

Things used in this project

Hardware components

Hand tools and fabrication machines

Story

Ideation

Electronics

Case

Program

Storage

Red Cross

Display

Putting it together

Custom parts and enclosures

Case

Drop

Back lid

Schematics

Circuit

Code

drop-of-life.ino

Photon code, Fritzing diagram and 3D models

Credits

Julien Vanier

Comments

Related channels and tags