Smart City Maps

The Story Behind This Project

Vienna is a beautiful city to walk and bike through, especially during those lovely summer days. But like many cities, summer vacation period brings an unwelcome surprise: the city hall decides it's the perfect time to lift roads for maintenance and pavement upgrades. If you've ever tried to navigate a city during construction season, you know the frustration - blocked roads, diverted traffic, and unexpected jams that can turn a simple trip into an hour-long detour depending on the time of day.

As someone who chose to stay in Vienna during those hot summer days while others vacationed, I found myself constantly checking my phone for traffic updates before leaving home. *"Is my usual route blocked today? Should I take the bike or public transportation?"*

That's when it hit me - what if I could see all this information at a glance, beautifully displayed on my wall, updating throughout the day? This became the perfect application for my Smart Dashboard PCB and Seed Studio's fancy 7-color e-paper display: an interactive map of Vienna (or any city in the world) that gives me the data I actually care about before stepping out the door.

Project features:

• ESP32-S2 based microcontroller
• Low power e-paper display (supporting Black, White, Red, Green, Blue, Yellow and Orange)
• Compact design that fits perfectly behind the display

How does it work?

The system consists of a Python service, running on Github's actions (at regular intervals) that generates the image to show, and an ESP32-S2-based firmware that fetches the generated map and displays it on your 7-color e-paper.

Every 10 minutes, Github's Actions launch the map generation script that:

1. Reads which cities need maps

2. Checks if it already knows the city details

• If yes: Uses saved coordinates and timezone
• If no: Asks Geonames API for the coordinates and timezone

3. Retrieves a high-resolution 480x800px map with real-time traffic overlay using predefined styling through the MapBox API

4. Fetches current meteorological conditions and temperature data. Weather condition codes are mapped to locally-stored colored icons for e-paper display characteristics

5. Composes a PNG picture with the map image the local time, through the UTC offset, and adds the weather information, together with the City details (name, country, latitude and longitude)

6. The composite image undergoes Floyd-Steinberg dithering to optimize color representation for the 7-color e-paper display.

7. The system produces multiple file formats:

• Binary payload optimized for ESP32 consumption
• PNG rendering for visual verification and debugging purposes

8. All generated assets are committed to the GitHub repository, making them accessible to client devices through standard HTTP requests.

Further info about how the server works can be found on the Github's Server README

On the display side, when the ESP32 wakes up, it follows this routine:

1. Connect to WiFi (retries 30 times if it fails, then sleeps)

2. Queries NTP servers to obtain local time, which serves as the base for sleep scheduling. Based on current time, the system calculates the next wake interval:

• Active Hours: 30-minute intervals for frequent updates during typical viewing periods
• Overnight Period: 9-hour sleep cycles to conserve battery during low-usage periods

3. Downloads the latest binary image file from the GitHub repository. This approach eliminates the need for local processing, which is way more efficient when it comes to using the ESP32 resources.

4. Initializes the e-paper display controller, loads the binary data into the display buffer, and executes a complete refresh cycle to update the visual content

5. Following successful display update, the device enters deep sleep mode until the next wake up period.

Further info about how the firmware works can be found on the Github's Firmware README

How to build it?

Step 1: Get Your Hardware Ready

1. Connect the e-paper display to the Smart Dashboard using the header connector and the LiPo battery (optional if you want to make your map portable)

2. Choose Your Enclosure

• 3D Print Option: Use the included STL files for a sleek, rounded design

• IKEA Hack: Modify a LOMVIKEN 13x18cm frame for budget-friendly housing

At this point it's better not to enclose all the electronics yet, since you will need access to the boot and reset pushbuttons of the Smart Dashboard, that won't be accessible once enclosed.

Step 2: Set Up the Cloud Magic

The real magic happens in the cloud where the Python server generates beautiful maps with live data.

1. Fork the Repository and get your own copy of the map generation system

2. Edit the config/settings.py file: enterthe APIs (all free) and select your city (in city, country format)

3. Set up you Github's Actions workflow.

Step 3: Program Your Device

1. Now, on the firmware folder, edit the config.h file with your Wifi settings and your repo's name (where you are launching your own Python map-generator).

2. Press the boot button while resetting the Smart Dashboard to enter into flashing mode, then just upload the compiled Firmware.

# Using PlatformIO (recommended)
cd Firmware/
pio run --target upload

3. After it's uploaded, press the reset button and watch the magic happen, but be patient: since the system starts until you see the display start updating can pass more than 30s.

Step 4: Enclose and customize

At this point you can put all the electronics into any enclosure of your choice, using a battery or just powering it via USB-C.

Since the Map are not generated on the device, but in the server, any further style you want to apply can be done without need to re-flash the board.

Additional custom Mapbox styles can be even added by using the style url.

Conclusion

Building a Smart City Map Display combines the satisfaction of hands-on hardware assembly with the power of cloud-based data processing.

Whether you're a maker looking for your next project, a developer interested in IoT applications, or someone who simply loves beautiful maps, this project offers something special. The combination of cloud automation and a good-looking display that's both technically impressive and aesthetically pleasing.

Ready to bring your city to life? Let's start building! 🚀