Introduction: @H2G2Bag - Twitter Display Using ESP8266-01

By Sharon Mitchell
About: "I see things that aren't there yet"

This project is a derivative from the (much) earlier:

https://www.instructables.com/id/H2G2-Towelday-Adaf...

and:

https://blog.adafruit.com/2014/04/23/upcycled-towe...

and came about because the British Science Festival 2016

https://www.britishsciencefestival.org/

was to be held in my hometown of Swansea, UK.

Swansea Hackspace were asked to participate in the Uplands After Dark segment of this event, this presented a great opportunity to create an "audience participation" piece for promotional purposes and I finally had the excuse I needed to play about with an ESP8266-01 microcontroller.

PLEASE NOTE: THIS ISN'T A SEWING 'IBLE, AND I WON'T GO INTO HOW I MADE THE BAG IN THIS INSTRUCTABLE.

THIS PROJECT BUILDS UPON AN EARLIER EXISTING PROJECT AND IS CONCERNED WITH ESP8266/TWITTER STREAMING API.

The bag displays Tweets sent to Twitter user @H2G2Bag; Client code running on the ESP8266 periodically polls a webserver for a fresh batch of tweets to display, (currently every 60s) if there are none or in case of an error, we default to displaying a message inviting viewers to tweet the user @H2G2Bag with their message, followed with a Babelfish animation. If there are fresh Tweets, we get a batch (currently 10) and display :

<twitter_user> <message they sent us>

followed by a sentinel Babelfish, before going 'round again.

Display is through an Adafruit Neomatrix, an 8 x 8 grid of WS2812 LEDs.

The bag is totally portable, both ESP and Neomatrix running off a rechargeable LiPo (but see schematics, you need a Buck converter as chip and LEDs require different voltage). Wireless connectivity is needed for the client code to talk to the server and get back a JSON response, I use a 4G-WiFi bridge (which fits neatly inside the service flap pocket, a space previously occupied by the Arduino from the first iteration of this project!), but you could just as easily set a smartphone to access point mode and use your phone's data plan. Don't forget to put your credentials in any source you run.

All code, as usual on my GitHub page.

Step 1: Bill of Materials/Requirements

1) A dedicated Twitter account to collect from (in this case I setup @H2G2Bag).

Visit:

https://apps.twitter.com/

to manage your application, (give it a name, add a description..) as Twitter has implemented tokens allowing users to bypass the token acquisition dance usually associated with OAuth.

You will need your App's tokens in any copies of the source code you run.

Read:

https://dev.twitter.com/overview/documentation

especially the parts about the Streaming API, which this project uses.

Disappointingly, Twitter don't offer any kind of sandbox environment for developers to play about with, and any code you run must implement a backoff strategy. i.e constantly hammering Twitter's servers WILL get you rate limited.

2) A means of display: I used an Adafruit Neomatrix (and Arduino libraries to support this), sewn to the front flap of a messenger-style bag.

3) ESP8266-01 microcontroller: runs client code to poll server, signals matrix, sits inside bag.

4) Rechargeable LiPo battery (this will supply between 3-4.2v), the greater the capacitance in mAh the longer you can keep running.

5) Project requires WiFi access.

6) PHP and MySQL enabled webserver (a PHP collector script hooks up to the Twitter Stream, JSON received gets parsed by a second script and certain payload data is stored in a database. [I had no idea Tweets were so huge!--it's not just the 140char message!] When the client polls, a database lookup/retrieval is performed, this project utilises ADOdb for this:

http://adodb.org/dokuwiki/doku.php

which I'm really pleased to see is still going strong!

7) Additionally, in developing this project I found access to the following useful:

CP2102 USB-TTL UART bridge (to program and debug the ESP), breadboard, wire, bench PSU (to power lights separately from the ESP which itself takes 3.3v from the UART bridge connected to USB port), soldering iron and solder, heatshrink, crimping tool and open barrel crimp housings, JST connectors.

Step 2: Database

Because this project uses Twitter Streaming API (and doesn't periodically poll a REST endpoint) it makes sense to separate the collection function from the processing and display, when working with streams we need to think asynchronously.

Processed Tweets from the stream are stored in a single database table, allocating an internal auto-incrementing ID to each new database record (in this case a Tweet).

I parse the JSON object coming from Twitter and store the timestamp of the Tweet, the Twitter username who initiated the message, and the message body [the 140char as per Twitter]. I also add a log timestamp.

Twitter has included in each Tweet payload the field tweet_id_str

which is the string representation of the unique

tweet_id

which can be very large and makes Javascript ill, apparently, so we store that string of ID in lieu of any numerical value (recommended).

We get other messages on the pipe, e.g. new follows, but I include logic to weed these out.

So the database table looks like:

mysql> describe tweets;
+------------------+--------------+------+-----+---------+----------------+

| Field | Type | Null | Key | Default | Extra | +------------------+--------------+------+-----+---------+----------------+

| db_id | int(11) | NO | PRI | NULL | auto_increment |

| log_at | varchar(255) | YES | | NULL | |

| tweet_at | varchar(255) | YES | | NULL | |

| user_screen_name | varchar(30) | YES | | NULL | |

| tweet_text | varchar(140) | YES | | NULL | |

| tweet_id_str | varchar(255) | YES | | NULL | | +------------------+--------------+------+-----+---------+----------------+

6 rows in set (0.00 sec)

Step 3: Programming the ESP8266 Microcontroller

I found this resource useful for getting started with the ESP.

http://swansea.hackspace.org.uk/Tutorials/ESP8266B...

This project additionally requires the Adafruit Neomatrix Arduino library, as that is what I'm using for display of messages, but Your Mileage May Vary depending on what you have for display purposes (e.g. LCD screen).

Step 4: Wiring

Step 5: Debugging and Re-programming

Because the ESP8266 needs GPIO0 low (pulled to GND in a circuit) in order to enter flash/programming mode, I have fabricated a port out of hook-up wire, to enable this once the wiring is soldered, heatshrunk and in the bag.

This is because GPIO0 is usually (in run mode) our data line to the LED matrix. So it's dual-purpose.

See white wires in picture.

Likewise I have included in my wiring "squid" a debug port taking GND, RX and TX from the ESP out to a JST connector which we can hook-up the CP2102 USB-ttl UART bridge so we can reprogram it / read the Serial port in the field.

Step 6: Field Test

This video isn't the greatest, the light levels are too high, but you can just about see the H2G2Bag receiving and displaying the Tweet:

https://drive.google.com/file/d/0ByRvXJ_jf_YDcWJtU...

Note to self: don't try and record tweet display on same device you're Tweeting from: there wasn't time to switch app from Twitter to Camera and select Video mode!

LED Contest

Participated in the
LED Contest