LibraryBox: Portable Private Digital Distribution

Download a custom copy of OpenWrt for the TP-Link MR3020 router at makezine.com/go/openwrt (OpenWrt firmware modified by Strubel to include all needed kernel modules). The MR3020 is a $40 device meant to be a 3G to wi-fi router for sharing a 3G USB dongle among multiple devices; this firmware update will prepare the router for all of the other customization.

Set the toggle switch located beside the LAN/WAN port to WISP mode.

If using a computer with wi-fi, turn off the wireless in order to force it to connect to the router over Ethernet.

Connect the router via Ethernet cable to your computer, connect it to a power source via USB cable, and open a web browser to http://192.168.0.254.

Enter the default username and password (“admin” and “admin”).

Navigate to System Tools → Firmware Upgrade and select the OpenWrt firmware that you downloaded in Step 1.

After the upgrade completes, the MR3020 will restart. Don’t unplug the router or disconnect the Ethernet cable during the firmware flash.

Installing PirateBox doesn’t require that you understand the command line; you can simply follow the instructions. But if you mistype something, it helps if you know your way around Linux a bit. Once the MR3020 restarts, begin this section.

Telnet to the device:

telnet 192.168.1.1 (Yes, this is the right IP address, à la the OpenWrt install.)

Use the passwd command to set your login password. This will enable SSH:

passwd

In Step 10 you’ll be editing the MR3020 network configuration at /etc/config/network so that it can access the internet and install dependencies. You will be changing 4 lines of the file; 2 of these changes (the lines with dns in them) will be the same for every LibraryBox. The other 2 depend on your network configuration. You’ll need to determine values for the lines that start with option ipaddr and option gateway.

The value for option gateway should be the IP address of your network router.
The value for option ipaddr should be an IP address that is assignable by your network router. Example: If your network router is 172.16.0.1, then the 2 lines would be:

option gateway ‘172.16.0.1’
option ipaddr ‘172.16.0.101’

The other 2 lines that need changing are list dns. I recommend using Google’s DNS servers for this, unless you have a good reason not to. If you have such a reason, then you probably already know what you should be using for these values. Otherwise, stick to:

list dns ‘8.8.8.8’
list dns ‘8.8.6.6’

Because network configurations and routers vary widely it’s impossible for me to give you step-by-step instructions for how to determine these values, but some judicious use of Google should help if you’re lost.

Edit the network file with vi:

vi /etc/config/network

You’re editing the /etc/config/network file so that you set a static IP address for the MR3020 and the gateway that matches the IP range being delivered by your network router. I’ve chosen to use the DNS provided by Google, as it’s fast and stable, but if you prefer you can use your network router’s DNS, or OpenDNS. The MR3020 needs to be able to access the internet in order to update the packages necessary for PirateBox to run. This is where the largest number of failures occur in the install process, so take a moment to look it over, and use the values you determined in Step 9.

CAUTION: If you make a mistake at this point, it’s possible to brick the MR3020 in such a way that it’s no longer accessible. Be careful.

You should modify the /etc/config/network file to look like this, where the lines in the second set with ipaddr and gateway are customized as noted in Step 9. You don’t need to change any values in the first set of values:

config interface 'loopback'
option ifname 'lo'
option proto 'static'
option ipaddr '127.0.0.1'
option netmask '255.0.0.0'

config interface 'lan'
option ifname 'eth0'
option type 'bridge'
option proto 'static'
option ipaddr '172.16.0.101'
option netmask '255.255.255.0'
option gateway '172.16.0.1'
list dns '8.8.8.8'
list dns '8.8.4.4’

For instance, if your router is 192.168.0.1 (as many home routers are by default) and is set to assign IPs in the 192.168.0.X range, the lines in question would read:

option ipaddr ‘192.168.0.101’
option gateway ‘192.168.0.1’

The important thing is that the lines under config interface ‘lan’ for option ipaddr get set to an address not currently in use on your network, and that option gateway gets set to the IP address of your router.

Remove the power from the router, and plug in the FAT-formatted USB drive. Don’t disconnect it for the remainder of the PirateBox install.

Enable your computer’s wi-fi once more.

Connect the MR3020 to your network router with an Ethernet cable and plug the power back into the MR3020. Wait a couple of minutes until the MR3020 boots up. With your computer connected to your home network, try SSHing into the MR3020 from your computer.

ssh root@172.16.0.101

You should be able to log into the router using the IP address you set in Step 10. If you can’t, check your network settings by connecting the MR3020 directly to your computer via Ethernet once more, and double-check the Step 10 instructions. The MR3020 should be reachable on your network, at the address you gave.

Ping Google to ensure that your MR3020 can access the internet:

ping google.com

If you get packet response from google.com, you should be good to go for the next section. CTRL-C to stop the ping command. If you don’t get a packet response, double check your /etc/config/network file, double check your IP range, and make sure that any router-based firewall is off, then try again.

Add USB support to OpenWrt by installing and enabling the following packages:

opkg update
opkg install kmod-usb-uhci
insmod uhci
opkg install kmod-usb-ohci
insmod usb-ohci

NOTE: The opkg install lines may return the message: installed in root is up to date. This is fine, and is not an error.

Install PirateBox 0.3.2:

cd /tmp
wget http://piratebox.aod-rpg.de/piratebox_0.3-2_all.ipk
opkg update && opkg install piratebox_0.3-2_all.ipk

CAUTION: Be patient and wait a few minutes for the install process to finish completely. Removing power, pulling the USB, or otherwise interrupting the install could possibly brick your MR3020, although there are recovery procedures at the LibraryBox website if anything goes wrong.

After the install completes, unplug the MR3020 from your network router, unplug the power to the MR3020, and power it back up. You should have a working PirateBox and be able to connect to the new “Piratebox” SSID that your MR3020 is broadcasting via wi-fi.

Download the librarybox.zip file from github.com/griffey/Librarybox and save it somewhere you can find it.

Unzip the file. The result should be called librarybox and has several files and scripts inside.

With the MR3020 powered down, remove the USB drive, and insert it into your computer. Copy the librarybox folder (the whole folder, not the contents) to the USB, in the root directory. Eject/remove the USB from your computer, plug it back into MR3020, and power the MR3020 back up.

Connect your wi-fi to the “Piratebox” SSID, and reconnect to the MR3020 via SSH:

ssh root@192.168.1.1

then enter your password from Step 9 to login.

NOTE: This address is different from that in Step 13. The PirateBox install resets the IP that the MR3020 assigns itself.

Navigate to the librarybox directory on the USB drive on the MR3020:

cd /mnt/usb/librarybox/

And run the LibraryBox install script:

./librarybox.sh

That script will copy the files necessary for the UI customizations into place, and alters values in other files. If you’d like the details of the script, and want to follow where all the parts go, see librarybox.us/scripts.html.

By default, LibraryBox v1.5 is installed with Chatbox functionality, which some may prefer to remove. If you’d like to remove Chatbox, run the nochat script:

./nochat.sh

If you later change your mind, SSH back in to the MR3020, navigate back to /mnt/usb/librarybox/, and run:

./chat.sh

Done! One more reboot, and you should now have a LibraryBox. When the MR3020 boots back up, you should see an SSID called “LibraryBox – Free Content!” Connect to it via any wi-fi-enabled device, launch a browser, and you should see the LibraryBox homepage with the ability to browse and download files.

Adding content for download is as easy as powering down the MR3020, popping the USB out and into a computer, and copying anything that you wish to share into the /Piratebox/Share folder. Anything in that folder becomes shared by LibraryBox. I recommend starting with a collection of books from Project Gutenberg, or music and movies from the Internet Archive. I have a sample collection of Public Domain works on the LibraryBox website, librarybox.us.

To use a LibraryBox in the wild, people simply need to attach their devices to the “Librarybox – Free Content!” SSID, and visit any webpage in their browser. The device acts as a captive-portal, redirecting the request to its own internal pages. The index page contains a link to an About page, a link to the Downloads page, and the default install also includes a chatbox where users can communicate anonymously with each other.

LibraryBox has been tested on a range of mobile phones, laptops, and tablets. Just about any device with wi-fi and a web browser should be able to connect and download files from LibraryBox.

If you’d like a protective case for your LibraryBox that isn’t quite as stylish as a hollowed-out book but is way more modern, I have designed two different 3D printable containers for your LibraryBox: a small enclosure designed for very low-profile USB drives like the Sandisk Cruzer Fit, and a larger one with more room for the USB drive. Both are available on my Thingiverse page: thingiverse.com/griffey.

So what do you do with a $40 digital library that fits in your pocket? There are as many answers as there are things to share: fill it with photos of art for people to download as they browse an art fair; music to download at the local music festival; or presentation files for your conference paper. Anywhere there is limited or no internet connectivity but still a need to deliver digital files, LibraryBox can do it.

Very early in the life of the project, I received an email from an English teacher in a country where, for political reasons, the internet is tightly controlled. In this country, the upper class can avoid the restrictions by buying into a VPN, while the economically disadvantaged learners are just stuck, unable to buy their way past the restrictions that limit the availability of educational material. With a LibraryBox, educators in this situation could have a local, anonymous method for distribution of classroom materials to those who need them most.

Much of the world has intermittent Internet access at best. But even in those areas, the mobile phone is becoming ubiquitous, and LibraryBox can bring educational information, health information, and entertainment to the parts of the world where the gadgets outstrip access. While we live in an increasingly connected world, bringing information to remote areas is still a concern, and LibraryBox can help fill this gap.

The LibraryBox Project recently completed a successful Kickstarter campaign to fund the v2.0 release, currently in development with Matthias Strubel (lead developer for PirateBox). It will include many upgrades, from SFTP content updating and mesh network content sharing to a revised UI based on Bootstrap, plus a hugely simplified installation. To keep up with LibraryBox, visit librarybox.us.

Many thanks to Dr. David Darts, Matthias Strubel, Matt Neer, Ross Singer, and Andromeda Yelton.

This article appeared in MAKE Volume 37, page 74.