Banned Book Library

Screenshot of the main web page for Banned Book Library next to an image of a smart LED light bulb

This repo contains code for a custom ESP32 firmware to run on smart light bulbs. It was specifically designed for the following smart light bulb:

https://www.athom.tech/blank-1/color-bulb

This bulb comes with the Tasmota open source firmware pre-installed. This makes it easy to flash custom firmware to the device. It runs on an ESP32C 4MB.

What is the Banned Book Library?

This firmware will turn your smart LED light bulb into an open and unencrypted WiFi access point. It runs a small web server which is used to host digital copies of banned or challenged books. The light bulbs can then be installed wherever is convenient. As long as the light switch is on, the access point will be available and banned books can be available. Think of it as a cyberpunk digital dead drop.

This firmware comes pre-loaded with several books that are out of copyright and in the public domain, as an example.

The firmware image is only 4MB large and only 2MB is usable for storage. Some of that space is used for the HTML files and web server images. This means you will have less than 2MB to store ebooks.

Warning

This firmware may brick your device. I can't guarantee it will work on whatever device you flash it on. I know it worked on the light bulb linked above at the time that I purchased it. The vendor could change the hardware or software at any time and it may no longer work. Use at your own risk.

Check Compatibility

This firmware was designed for a smart light bulb which came pre-installed with Tasmota 14.3.0(tasmota32). This version included a safeboot partition. If you browse to the Tasmota Information page for your device, you can validate that the partitions look like this:

Partition safeboot	832 KB (used 90%)
Partition app0*	 2880 KB (used 69%)
Partition fs	 320 KB

You should see a medium-sized safeboot partition, a large app0 partition and a small fs partition. If you see any other partition layout then installation of the Banned Book Library firmware may fail and brick your device.

Building

Prerequisites

• git
• docker
• python3

Get the code

First, clone the repository to your local machine or otherwise download the code.

Password

The Banned Book Library has an administrative web interface used to flash firmware, control the light bulb color temperature, etc. To set the password, edit the file:

/library/data/password.txt

This file should contain only the plaintext password to be used for administering the bulb. Do NOT include any newlines or non-printable characters in this file! Doing so could make your administration page unavailable.

Web Server Config

First, you'll want to put the ebook files in the /library/data/html/books directory.

Then, you must update the /config.toml file to reflect the added books and the general description you want to use on the main page.

Example`:

[main]
description = "Welcome to the Banned Book Library! This is a WiFi-enabled electronic dead drop. It is completely offline and only accessible via WiFi.\n\nEach of these books has been challenged in Oregon."
[[books]]
title = "Annie on My Mind"
author = "Nancy Garden"
filename = "Alice Walker - The Color Purple.epub"
[[books.reasons]]
reason = "1988 - Cedar Mill Community Library - Challenged because the book portrays lesbian love and sex as normal."
[[books.reasons]]
reason = "1993 - Bend High School - Challenged because \"it encourages and condones homosexuality.\""
[[books]]
title = "The Color Purple"
author = "Alice Walker"
filename = "Nancy Garden - Annie on My Mind.epub"
[[books.reasons]]
reason = "1995 - Junction City High School - Challenged due to \"inappropriate language, graphic sexual scenes, and [its] negative image of black men.\""

Once the configuration file is updated, you must run the update_config.py script. This will generate the proper library.html file from the template version.

python update_config.py

Build

Finally, run the build.sh script from inside the root directory. This requires an Internet connection. It will download ESP32 components and Arduino libraries. It will also setup a Docker container to build the ESP32 firmware images. Finally, it will build the images using the Docker container and store them in the firmware_images directory. These are the images that must be flashed to the device.

The repo contains pre-build binaries if you want to use them as-is. You can also just build the library image, the library-safeboot image, or the filesystem image using the build script:

./build.sh library
./build.sh library-safeboot
./build.sh filesystem

If you only want to modify the books, config.toml, or password.txt, you can flash the pre-build firmware and safeboot binaries and build only the filesystem image.

Images

The build script should generate three separate images:

library.bin
library.littlefs.bin
library-safeboot.bin

library.bin is the main firmware image that will replace Tasmota. This contains the code for the access point, web server, and some OTA update code.

library.littlefs.bin contains the file system partition. This image contains most of the HTML files, images, the books, and the passwd.txt file.

library-safeboot.bin is the safeboot image. This is a separate firmware image that must be flashed to the device's alternate boot partition. This is critical to allow OTA updates of the main firmware later on, or to allow OTA flashing of Tasmota, ESPHome, or any other firmware.

Installation

To install this firmware, install the light bulb to a temporary fixture and power it on. You must first go through the Tasmota setup to configure the device to connect to a WiFi network you can access from your own computer. Connect to the device's access point and configure it to connect to your own WiFi network. It should walk you through this process and bring you to the device's web server.

Next, use the Tasmota Firmware Upgrade function to flash the library.bin image to the device.

Screenshot of Tasmota firmware update page

The Tasmota OTA process will reboot the device into the Tasmota safeboot partition. From there, it will flash the library.bin to the main partition and then finally boot into the custom firmware.

On first boot, the library firmware will repartition the device flash memory. It will also erase the non-volatile data partition to remove WiFI and other settings from the flash. It also erases the SPIFFS partition to be safe.

You must connect to the device's new WiFi network using the SSID BannedBookLibrary. It requires no password. Then visit the configuration page at http://192.168.4.1. Note the firmware does NOT support https.

Screenshot of setup page

It should display a setup page with instructions. The first step is to click the ElegantOTA link. You will need to log in with default credentials:

Username: human Password: being

On the ElegantOTA page, select LittleFS / SPIFFS from the OTA Mode drop down menu. Use ElegantOTA to flash the library.littlefs.bin image.

Screenshot of ElegantOTA with LittleFS selected

Then, select firmware from the drop-down menu and flash the library-safeboot.bin image. The device will automatically reboot into safeboot.

Screenshot of ElegantOTA with firmware selected

When the update is complete, power off the device. Then power it back on. It will boot into the safeboot partition.

Screenshot of safeboot web page

You can then reconnect to the device web server at http://192.168.4.1. This page can be used to re-flash the main firmware image to a new version, or back to Tasmota, or something else. Click the link to reboot back into the main firmware.

Your Banned Book Library is now configured and ready to go!

Basic Usage

Once the device is flashed and turned on, it should automatically create an open WiFi network with SSID BannedBookLibrary. This network will have no Internet connection. When a device connects to the access point, all DNS requests will resolve to the device's IP address. It will also attempt to initiate a captive portal to automatically redirect users to the home page.

If the captive portal is not working, you can browse to the main page via http://192.168.4.1.

The captive portal has been tested on a recent Android version and worked, but it's possible it may not work on other devices. If you find one that fails you can create an issue to track it.

Administrative Usage

Admin web page

Aside from the main library pages there are some administrative functions that can be accessed if you know the password configured in password.txt. The username is hardcoded to human.

The admin page is at http://192.168.4.1/admin. This page will allow you to set the bulb to warm white, cool white, or off to match whatever other bulbs may be in the area. There is also a link to ElegantOTA which can be used to update the filesystem image with new books, etc, or to update the safeboot partition image. There is a button to reboot into safeboot. There is also a button that will load a restore page.

Restore web page

The restore page is designed to help restore the device back to the factory settings. The restore page contains a button that will repartition the flash similarly to how it was flashed at the factory. The one difference is that it will leave the safeboot partition subtype set to OTA_1 instead of resetting it back to Factory. There is then another button to reboot into safeboot. From there you can attempt to flash Tasmota back to the main image.

NOTE: There is currently no way to flash the safeboot partition back to the Tasmota version after Tasmota is restored on the main partition. Also, if you attempt to flash the safeboot partition first, there will be no WiFi configuration for it to find and it will be unable to connect to any WiFi for you to actually use it.