NYC Ferry Schedule Ticker Clock

New York, New York, it’s a wonderful town. The Bronx is up, and the Battery’s down! The people ride in a hole in the ground… and sometimes, on the water. (Lyrics from New York, New York, On The Town, 1949)

In this project, I iterated on the concept of a subway clock and created a version that displays the current schedule of the NYC ferry— for those who ride in style!

This product was created for my boyfriend who takes the ferry from the same stop every day to get to work. The design incorporates a perpetual scroll display that shares the next 3 departure times from his stop (North Williamsburg). He can glance over at the ferry times in the morning and determine which ferry to catch, and whether to walk, bike, or skateboard to catch his ferry. Using this clock reduces the likelihood that he will be distracted when looking up the schedule on the NYC Ferry's mobile app. It's a great way to start the day for anyone who relies on the ferry schedule with regularity :) 

This project shares "looks like" and "works like" images, instructions, and code, as well as some things to avoid if you're hoping to achieve the end design. A massive thank you goes out to @beckathwia who helped troubleshoot and provided code guidance, and everyone who provided the open-source code that allowed me to get this far.

Now, let's dive in!

The materials that I used for this project are as follows:

1. Arduino ESP32
2. Arduino UNO and a solderless breadboard
3. 1 16x32 LED RGB matrix
4. A 5V / 2A power cable
5. jumper wires
6. soldering equipment
7. Acrylic sheets for the encasement (I used this!)
8. A laser cutter

If you're interested in recreating this project, take a look at some of the other compatible hardware options that work with this display. I needed a wifi compatible board, so I used the ESP32, but it only has 3.3V power and the display needs 5V; so I ended up incorporating an UNO to make the display work.

Circuit diagram above is from Adafruit RGB LED Matrix Basics.

Initially, I had planned to use an ESP32 to run my RGB matrix display and make my API call. However, because of the power requirements of the display, I switched to an Arduino UNO and a breadboard to provide the extra grounding required.

I used the Adafru.it RGB Matrix tutorial to get my display set up and working. I followed the pinout guides and wiring in the Connecting with Jumper Wires tutorial for the RGB matrix in order to create my circuit, making sure to adjust as specified in the tutorial for the UNO. Then I ran the test code examples to make sure my circuit was working and to get familiar with how to program the display.

After testing that my circuit was working, I began to customize the text on the display.

👉 In general, staring at an LED display for hours on end at all times of day/night can be hard on the eyes, so the first thing I’d recommend doing while you’re tweaking your code is changing your text to red which is less abrasive. 👈

The following libraries are required for this project. When you install them, make sure to install their dependencies too :) 

1. RGB Matrix Panel x Adafruit (all the functions I needed to control my display)
2. Adafruit GFX. Adafruit GFX library has a bunch of fonts that you can import and use to customize your display. You can futz with the cursor’s starting position depending on the height of the font. 

The Adafruit Protomatter library is designed to make the LED matrix display work with the ESP32. As I mentioned, I had some issues with voltage and also connecting the ESP32 and the display, so ultimately I didn't use this library. But maybe you'll have better luck :)

For my code, I used the scroll_text_16x32 sketch from the RGB matrix panel example, and customized from there.

1. Thinking ahead to the information I wanted my ferry clock to display, I hardcoded in an example message so that I could make aesthetic adjustments to accommodate the desired text.
2. I tried out some different fonts for the text using the GFX library mentioned above, ultimately landing on FreeSans 9pt 7b.
3. Out of the box, text on the display zooms by very quickly, so incorporating a scroll delay was important for legibility. I introduced the delay as a variable upfront and then called it directly in my loop(), working from the code in this forum post.
4. I adjusted the position of the cursor for optimal legibility of the text on the display.
5. I changed the color of my text to blue, to go with the case that I designed for it.

This sketch allowed me to finish a "looks like" prototype, which served as a guide for me when it came to incorporating real data from the NYC ferry schedule.

The New York City Ferry Service uses GTFS (General Transit Feed Specification), which is a standard format for sharing transit system data. You can read more about GTFS here. This makes it possible for us to get an up-to-date ferry schedule by making an API call.

In order to work with GTFS directly, you need to spin up a server to manage the rate/volume of data when you make your query. (Follow Robert Boscacci's subway clock tutorial for steps.)

However, after digging around on the internet, I found Transit.Land-- an open data platform that collects GTFS and other open data feeds from transit providers around the world. Transitland makes all of this data queryable via REST APIs. There are feeds from over 2,500 operators in over 55 countries, including the NYC ferry!

I read through the Transit.Land documentation, and started to decode the the key/value pair data for ferry stops and ferry routes from the source feeds. I created an account on Interline.co to get a secure API key. Armed with my API key, I started to get to work on the program for my ESP32.

Writing the API call and parsing the JSON data was the most complicated part of this project, and required a lot of research. I watched this video, read through ArduinoJSON's deserialization documentation, and read this tutorial on GET requests, and got a lot of help from @Beckathwia.

We looked at Transitland's REST API documentation for departures. This outlined how to specify which date we were looking for, and all of the other parameters necessary to include in the call.

I discovered that the returned payload only includes the next 20 departure times from any given stop. If you don't specify a time, it gives the first 20 departure times for that day. So, I needed to pass in the current time in order to get the upcoming departure times. We did this (thanks @Beckathwia) via concatenation. Here's a helpful guide.

I used Network Time Protocol to get the current time (more info here), and we defined variables for the base URL, and the current time above the setup(), and then concatenated them together in the loop():

The final code attached here calls the API, parses the returned JSON file, and then prints to the Serial monitor the departure time of the next ferry departing from the station that is specified in the API call parameters.

What this code does not do yet is use Software Serial to connect the ESP32 to the UNO to pass the data along to be displayed on the matrix.

For this design, I went with a tab and slot box because I always find it beneficial to be able to revisit my circuits if I want to improve them in the future, and a tab and slot design avoids the need for glue.

I created a simple vector design for my box in Adobe Illustrator before I learned about MakerCase, which is a web tool that instantly creates box templates for laser cutters from a set of input dimensions. I recommend using MakerCase instead of DIYing it unless you're hoping to make something really custom :)

The file for the encasement I created is attached if you'd like to use it! I had initially planned to include 2 rotary switches in my design, to allow the user to rotate through routes and stops, so there are some holes in the top panel to accommodate those. There is an exit hole in the back panel for the power cord. Everything else (my UNO and all of my cables) fits snugly inside behind the display which serves as the front of the box.

I cut the pieces out of a pearlescent blue acrylic which gives off the feeling of waves. It might not be an accurate depiction of what the East River water looks like, but hey, it's aspirational ;)

I have 2 steps left in this project

1. I need to link up my ESP32 and my UNO, so that the ESP32 can call the API, get the next 3 departure times, and pass them as a message via Software Serial to the UNO to display on the matrix.
2. Solder my circuits! Right now my display circuit is sitting nicely inside my acrylic box, but it's not permanent, and I can easily change that by soldering my ESP32 to a perf board, and soldering my UNO.

Thank you so much for sticking around and reading through my project! It's still an early prototype and there are probably better ways to execute it, so if you have any thoughts, feedback, or code revisions, I'd be really grateful!