Twitter Led Board

Overview

In this project, we connect 16x32 RGB LED board to Raspberry Pi Model B+, and hook it to a Kaa-enabled application that listens to the Twitter feed, filters it by a configurable hash tag or mention, and delivers to Raspberry Pi for displaying. Twitter limits the amount of API calls per account per every 15 minutes, but with our architecture you can make any amount of LED boards display the desired tweet streams. This project was recently presented at the IoT World event as a part of the Kaa IoT platform demo. A brief description of the project is presented in the attached video.

Step 1. Wiring the boards

We have used Adafruit tutorial to wire the Raspberry Pi and the LED board. We recommend using instructions provided in this tutorial, whereas this article will provide only project-specific information.

Using 74AHCT125 quad level shifter

In our case, the LED board was expecting the 5v logic and did not allow for the 3.3v logic provided by Raspberry Pi. We fixed this issue by using 3 quad level shifters. Please note that most of the LED boards work fine with the 3.3v logic and you can skip this step.

You will need a breadboard and a lot of jumper wires:

• 2 Female-Male to wire GND and 5V from RPi to the breadboard
• 1 Male-Male to wire GND from IDC to the breadboard
• 18 Male-Male to enable the shifter logic
• 12 Female-Male to wire RPi and the breadboard
• 12 Male-Male to wire IDC and the breadboard

The complete wiring schema is listed below.

Some additional information about how to connect the LED board using an IDC cable can be found here.

Step 2. LED board driver

We decided to use this library to control the LED board. It has a quite strict license (GPL 2.0), so we decided to use this library as a driver and avoid making any modifications to it. This library allows you to scroll ppm images on the board by invoking a simple command:

sudo library_path/led-matrix -r 16 -D 1 -m your_scroll_speed your_ppm_image

For our application, we download and unpack the driver to /home/pi/display16x32/rpi-rgb-led-matrix.

To finish, validate your installation by using the following command:

sudo /home/pi/display16x32/rpi-rgb-led-matrix/led-matrix -r 16 -D 1 runtext16.ppm

Step 3. Software

Application goals

Our task was to provide the following capabilities for our applications:

• control an unlimited amount of LED boards simultaneously

One of the use cases is to display information in different areas of a shop or even a shopping mall.

• display different tweets on different sets of devices

One of the use cases is to display different ads based on the board’s location or other profile information.

• avoid being rate-limited by Twitter Streaming APIs

Twitter Streaming APIs provide approximately 450 requests per a 15 minutes window. The request count is account-based. Since LED boards do not have dedicated twitter accounts, we cannot query Twitter Streaming APIs from each LED board device with the same application API key.

Application structure

We have used two applications in this project. The first application is called TwitterMonitor and is responsible for monitoring Twitter updates using Streaming APIs. Once new tweets arrive, this application generates a Kaa notification. This application can be deployed to either a desktop or a server.

The second application is called TwitterBoard and is responsible for receiving and displaying Kaa notifications. TwitterBoard transforms the notification text to a ppm file, which is accepted by the LED board driver, and launches the visualization process. If there are no updates for a certain period of time, TwitterBoard displays a prompt text. The prompt text, scroll speed and font colors are configurable via Kaa configurations.

This project structure is especially useful for large-scale deployments. For a single LED board, TwitterMonitor and TwitterBoard may be merged into one application and deployed directly to Raspberry PI.  

Sample code

You can browse the code of this project using the following links to our github repository:

• TwitterMonitor
• TwitterBoard

This code, however, does not contain the Kaa SDK. We will discuss how to get the Kaa SDK in the next section.

Application deployment

TwitterMonitor and TwitterBoard applications require the Kaa SDK to operate. The Kaa SDK automatically generates a lot of useful code that is related to user-defined data structures (configuration schema, notification schema, etc). There are two ways to get the SDK:

• download Kaa Sandbox which has both applications pre-installed.
• set up the Kaa server and provision all data structures using Admin UI guide.

We strongly recommend using Kaa Sandbox for PoC applications. It is the easiest way to get started with Kaa.

Once Kaa Sandbox is started, you can visit the following page:

http://your-sandbox-host:8080/sandbox

You can download both the source code and binary files for the applications there.

We also recommend watching the Kaa Sandbox introduction video provided below.

Application configuration

Both TwitterMonitor and TwitterBoard applications are configurable. You can manage their configuration using Kaa Admin UI or REST API.

Using the TwitterMonitor configuration, you can configure what hash tags should be monitored by the application and its authentication credentials. Using the TwitterBoard configuration, it is also possible to control font color, prompt messages and other visualization properties of the LED board.

Application startup

Once applications are deployed and configured, you can start them by executing the following commands:

sudo java -jar TwitterMonitor.jar

sudo java -jar TwitterBoard.jar  

TwitterBoard may take some time to start. Once started, it should not consume more than 25% of CPU on RPi model B+ and much less on RPi 2.

Future improvements

We are going to introduce the following improvements to this sample project:

• add the ability to control the twitter board from mobile devices.

• rewrite the TwitterBoard app from Java to C to increase performance and save resources on Raspberry PI.