The Librarybox Project

Equipment Needed

To build a LibraryBox, you need a router and a USB thumb drive. You can build a LibraryBox v2.1 with a variety of different router hardware, depending on your use-case and need. At the moment, Librarybox v2.1 supports 12 different pieces of hardware. These are the suggested ones, a complete list can be found see below in the Download section.

  • TP-Link MR3020
    • The MR3020 is the "standard" LibraryBox hardware, about the size of a hockey puck and cheap and easy to find.     - The latest revision of the MR3020 is NOT compatible with this firmware. If you just purchased an MR3020, it will probably NOT work with this.
  • TP-Link MR3040
    • The MR3040 is an upgrade from the 3020, in that has a built-in battery pack for on-the-go ease of use.
  • TP-Link WR703n
    • The WR703n is the non-US version of the MR3020, available in Japan, China, and elsewhere in the world. DO NOT confuse this with the 702n, which does not have a USB port and isn't suitable for use with LibraryBox.
  • TP-Link WR842n
    • The WR842n is best for non-portable LibraryBox installations, or where you want the power of external antenna to broadcast your signal. Make sure that you download the correct version of the firmware for your hardware.
  • TP-Link TL-MR10U
    • The MR10U is a portable router with a built-in 2600 mAh battery for charging other devices built in. It is primarily a non-US piece of hardware, so if you are in the US, tread carefully.
  • TP-Link MR13U
    • The MR13U is also a portable router for the non-US market, but this one has a 10,000 mAh battery, plenty for running the LibraryBox for over a full day of use.

LibraryBox also requires a FAT32 formatted USB flash drive to be used in conjunction with one of the above routers. You can use any FAT32 formatted USB flash drive, which means that there is a soft limit of 4GB for a single file (a limitation of the FAT32 filesystem). I like the SanDisk Cruzer line of drives, that come in a variety of sizes and costs from Amazon: from 4GB to 32GB. Another option is the Leef Surge low profile USB drive. I like the low-profile drives as they make for a more compact final product.

Once you've got your router and a USB flash drive, just follow the steps below.

Step One: Download & Install LibraryBox
  1. Download the firmware update that applies to the type of router that you are using to build your LibraryBox. Pay special attention to the Version # of the hardware, as some of these have a v1 and v2 where the hardware changes and a different firmware is needed.
  2. Download the LibraryBox v2.1 Install folder (as zip file) MD5 Hash: 85BF5A80220B9C8204303C6099908A7D
  3. Unzip the install_librarybox.zip file, so that you are left with an install folder, and copy both the install folder AND the firmware file onto your FAT 32 formatted USB stick. The only things on your USB drive should be a folder called "install" copied from the unzipped install_librarybox.zip file and the firmware.
  4. Plug the FAT 32 formatted USB drive into the router's USB port.
  5. If the router has a selection switch for mode (like the MR3020) ensure that it's set to WISP.
  6. Connect the router via ethernet cable to your computer, connect it to a power source. If you are on a laptop, you may have to temporarily disable wi-fi to make sure that your computer connects directly to the router over Ethernet.
  7. Open a web browser, and type the address below that matches your router type into the address bar.
    • MR3020 - http://192.168.0.254
    • MR3040 - http://192.168.0.1
    • WR703N - http://192.168.1.1
    • WR842N - http://192.168.1.1
    • WR1043ND - http://192.168.1.1
    • MR10U - http://192.168.1.1
    • MR13U - http://192.168.1.1
  8. Enter the default username & password (admin & admin).
  9. Navigate to System Tools > Firmware Upgrade and select the OpenWRT firmware that you downloaded in step 1.
  10. After the upgrade completes, the router will restart. Do not unplug the router or disconnect the ethernet cable during the firmware flash. The entire process of building your LibraryBox will take approximately 10 minutes. Walk away, go have a cup of coffee.

Step I is done. That's it...after about 20 minutes of LEDs flashing, you should have a working LibraryBox. The speed depends on the USB drive. The install is done when the lights are no longer changing and you can see the SSID "LibraryBox - Free Content!" being broadcast.

Once you have a running LibraryBox, you can power down the router, unplug the USB drive, plug it into your computer, and throw content into the /LibraryBox/Shared directory...anything you place here will show up alphabetically to be downloaded. If you’d like, you can download this bundle of freely licensed works (WARNING: Torrent client needed) to get started, or head to Project Gutenberg or Feedbooks to build your own.

One bit of warning: because of the way that the default webpage is designed, you do need to have the basic organizational folders in place in the Shared directory if you want the menu links to work (text, audio, video, software). Of course, if you change the website, you can do whatever you want with the Shared folder.

Set Password

At this point, you have a working LibraryBox. The problem is that it isn't protected in any way, and anyone that knows the IP address (192.168.1.1) can simply telnet in and do what they wish. In order to secure your LibraryBox, you need to set a password.

  1. Reboot your LibraryBox (power-cycle the router) and let it boot up.
  2. Connect to the LibraryBox SSID with your computer, and telnet into it:

    3. telnet 192.168.1.1
  3. Run the LibraryBox advance setup script: 
    box_init_setup.sh
    That will launch a script that will walk you through the possible customizations to LibraryBox v2.1.
  4. Choose 1 for Setting Password and Enable SSH.
  5. Choose a strong password. After you set the password, you will no longer be able to login via insecure telnet. Log into the LibraryBox via SSH like this: 
    ssh root@192.168.1.1
  6. You've now got a working, secure LibraryBox!

Optional: Config, DLNA, FTP, Sync, & More

Config Options

On the USB drive under the LibraryBox folder, there is a folder named "Config" that is full of text files. This includes:

  • channel.txt
  • hostname.txt
  • librarybox_ftp.txt
  • librarybox_ftpadmin.txt
  • librarybox_ftpanon.txt
  • librarybox_ftpsync.txt
  • librarybox_ftpsyncport.txt
  • librarybox_shoutbox.txt
  • ssid.txt
  • system_hostname.txt
  • txpower.txt

Some of these are controlled by the menus mentioned above in the FTP setup, but several of them allow you to customize your LibraryBox. You can change the value of:

  • channel.txt to reflect the wifi channel that you want the LibraryBox to use
  • system_hostname.txt if you'd like a custom hostname when setting up Sync Clients
  • ssid.txt if you want to have a custom wifi ssid to be broadcast
  • txpower.txt if you'd like to make your LibraryBox have just a bit more (or a bit less) oomph when it comes to wifi coverage. The default is 25, but ranges between 20-30 should be safe (although raising the TX power will result in significantly higher power consumption and heat generation by the MR3020.

    • If you make any changes to these files, they will take effect the next time you boot your LibraryBox. I would recommend NOT changing the various FTP settings in this way, stick to the config files mentioned above.

MiniDLNA Setup

Connect to the LibraryBox SSID with your computer, and SSH into it:

ssh root@192.168.1.1
Run the LibraryBox advance setup script: 
box_init_setup.sh
which will give you the following menu: 
1 - Setting password and enable SSH
2 - Set date & time (enable timesave)
3 - Start FTP configuration
4 - minidlna enable
Simply select 4, and hit return. Your LibraryBox is now a DLNA server and should be discoverable by any DLNA client. The setting is saved across reboots, so the next time you power up your LibraryBox, the miniDLNA server will be active.

FTP Setup

Setting up your LibraryBox for FTP will allow you to upload, download, and delete files from the "Shared" directory from a computer connected to the wifi signal, without having to physically interact with the LibraryBox or the USB drive. Once you have it setup, you will be able to use any FTP software to login and change the Shared files. Follow the steps below to enable FTP access on your LibraryBox.

  1. Connect to the LibraryBox SSID with your computer, and SSH into it:

    2. ssh root@192.168.1.1
  2. Run the LibraryBox advance setup script: 
    box_init_setup.sh
    which will give you the following menu: 
    1 - Setting password and enable SSH
2 - Set date & time (enable timesave)
3 - Start FTP configuration
4 - minidlna enable
    This time, we are looking for option 3 on that menu, Start FTP Configuration.

  3. Selecting 3 will give you one more menu, this one a bit more complicated. First, I'll walk you through setting up just FTP access, and then below we'll worry about Sync and other options. The second menu looks like this: 
     Choose an option: 3
------------------------------------------------------
   Current configuration:
------------------------------------------------------
   FTP enabled                : yes
   Admin access               : yes
   Special SYNC access        : yes
   SYNC Port                  : 54321
   Anonymous login possible   : no
 --
   FTP Synchronisation active : no
   FTP Sync hostname          : empty
   FTP Sync password          : empty

------------------------------------------------------
  1 -  Enable / Disable FTP
  2 -  Enable / Disable Admin Access
  3 -  Enable / Disable Sync Master
  4 -  Enable / Disable Anonymous Access
  5 -  Set password for Sync Master
  6 -  Set password for Admin Access

  7 -  Enable Sync Client
  8 -     Client host
  9 -     Client password

 Enter h and a number for help about the topic. For example, h8 for Client host help
 Every other button is a clean exit.

    The list above the selections show you the current status of the settings, and choosing any selection will cause the menu to re-draw to show you the new current settings. They are not applied, however, until you exit the menu and reboot your LibraryBox.
  4. To enable FTP, choose Option 1.
  5. You must also set a password for your FTP access, done by selecting Option 6 - Set password for Admin Access. Choose a secure password for your FTP access!
  6. After you have set the password, exit the menu by pressing any key. Then, reboot your LibraryBox by unplugging and plugging it back in.
  7. At this point, you should be able to connect to the LibraryBox SSID, and use any popular FTP program to connect using your password and the username "nobody".

Sync Setup

A brief word about Mesh/Sync: due to technical limitations and an effort to ensure good user experience in regards to battery life, we've implemented this first Sync protocol to be Master/Client oriented rather that true peer-to-peer mesh. We are going to continue to look at more robust sync services for LibraryBox, but for this release, the Sync works like this:

You will designate one LibraryBox to be the Master box, and any number you wish as the Clients. The Client Boxen will search for a Master every 7 minutes, just looking to see if there is one in range. If a Client sees a Master that has the appropriate login credentials, it will start a comparison and sync with the Master in question. The Client will mirror the Master in content, both in deletions and additions. In order to automagically change the Shared folder on remote LibraryBoxen, you can set up a single Master that stays with you, and you can wander into range of your installed LibraryBoxen, hang out for a few minutes, and move on.

To set up Sync, follow these direction:

  1. Connect to the LibraryBox SSID with your computer, and SSH into it:

    2. ssh root@192.168.1.1
  2. Run the LibraryBox advanced setup script: 
    box_init_setup.sh
    which will give you the following menu: 
    1 - Setting password and enable SSH
2 - Set date & time (enable timesave)
3 - Start FTP configuration
    Choose option 3 on that menu, Start FTP Configuration.

  3. Selecting 3 will give you one more menu, this one a bit more complicated. 
     Choose an option: 3
------------------------------------------------------
   Current configuration:
------------------------------------------------------
   FTP enabled                : yes
   Admin access               : yes
   Special SYNC access        : yes
   SYNC Port                  : 54321
   Anonymous login possible   : no
 --
   FTP Synchronisation active : no
   FTP Sync hostname          : empty
   FTP Sync password          : empty

------------------------------------------------------
  1 -  Enable / Disable FTP
  2 -  Enable / Disable Admin Access
  3 -  Enable / Disable Sync Master
  4 -  Enable / Disable Anonymous Access
  5 -  Set password for Sync Master
  6 -  Set password for Admin Access

  7 -  Enable Sync Client
  8 -     Client host
  9 -     Client password

 Enter h and a number for help about the topic. For example, h8 for Client host help
 Every other button is a clean exit.

    The list above the selections show you the current status of the settings, and choosing any selection will cause the menu to re-draw to show you the new current settings. They are not applied, however, until you exit the menu and reboot your LibraryBox.

Set Up a Master LibraryBox

  1. Disable FTP
  2. Set Password for Sync Master
  3. Enable Sync Master
  4. Exit the menu by choosing any other key.
  5. Run the command: 
    /etc/init.d/mesh enable
  6. Run the command: 
    /etc/init.d/piratebox avahi
  7. Reboot your LibraryBox, and now you have a Master, ready for connections to Client Boxen.

Set Up a Client LibraryBox

  1. Disable FTP
  2. Enable Sync Client
  3. Under "Client Host" you will need the full hostname of the Master that you wish to sync to.
  4. Client Password - you want to enter the Password you set for the Master here. The Client will use the Hostname and this Password to log in to the Master to begin the sync
  5. Exit the menu by choosing any other key.
  6. Run the command: 
    /etc/init.d/mesh enable
  7. Run the command: 
    /etc/init.d/piratebox avahi
  8. Reboot your LibraryBox, and now you have a Client, ready for connections to its corresponding Master LibraryBox.

Upgrading from an another version?


Have a problem along the way?

Website Content - Creative Commons Licensed NC-BY Jason Griffey 2012, where not otherwise licensed.
Software Licensed under GPLv2, see http://www.gnu.org/licenses/gpl-2.0.html Back to Top