Programming the Linksys WRT54GS Wireless Broadband Router

Abstract: In part 1 of this tutorial you will learn how to compile the OpenWRT firmware for the Linksys WRT54GS Wireless Broadband Router, and how to install it on the device. In part 2 you will learn how to add further software to the router, including prepackaged software and programs that you wrote and compiled yourself.

Credits: http://openwrt.ksilebo.net, http://www.seattlewireless.net

Part I: Replacing the original Linksys firmware

Introduction

The Linksys WRT54GS Wireless Broadband Router has a Broadcom BCM4712KPB CPU, running at 200MHz. This CPU is not compatible with the Pentium (or similar) on your desktop computer, i.e. you can not simply take a binary program file from your desktop and execute it on the Linksys router - the Broadcom CPU encodes instructions and data in a completely different way and would therefore not "understand" your Pentium-based program at all.

The operating system on the Linksys router is Linux - again, not the same Linux that you might run on your desktop, but a Linux that was specifically compiled for the Broadcom CPU. The operating system along with all other programs is stored in a regular Linux file system which physically resides on the Linksys router's 8MB of flash memory. Flash memory is nonvolatile RAM which does not lose its data when the device is powered-off. But it is RAM, i.e. it can be modified in much the same way as regular RAM - just at a slower speed. In addition to the 8MB of non-volatile flash memory for the Linux file system, the Linksys router has 16MB of regular volatile RAM.

The content of the flash memory (i.e. the file system with all its data, including the operating system, programs and configuration data) is also called firmware. When we say that we replace the firmware of the Linksys router, we mean that we erase the content of the flash memory, i.e. it the entire file system that was stored in it - and replace it with an entirely new file system, which contains a completely new operating system, and a new set of programs and data files. Nothing from the old system will survive when the firmware is replaced.

For the initial setup of the Linksys router we will download the source code for the OpenWRT firmware and cross-compile it for the Broadcom CPU. Cross-compilation is a process where the compiler produces binary program files that are not meant to be executed on the local system, but rather on another platform (here the Linksys router with its Broadcom CPU). Then, using the web-interface of the original Linksys firmware, we will tinker with the original bootloader configuration and finally replace the Linksys firmware with our OpenWRT firmware.

Once the original Linksys firmware has been replaced by the OpenWRT firmware, the original Linksys web-interface is not available anymore. But we won't need it. The OpenWRT Linux allows you to login, using telnet or ssh, which gives you direct access to everything on that machine (details below).

Before you begin, one word of caution: Once you overwrite the original Linux firmware, it is gone forever. No pressing of the reset button or power cycling will bring it back. If the new firmware does not work, then you have transformed your Linksys router into a nice paperweight. But fortunately, this does not happen often.

Getting Started

You need a Linux system with approximately 1GB free disk space to download and compile the OpenWRT source code and the toolchain.

What is a toolchain?

To build a Linux system for the Broadcom CPU, you need several tools that are not part of your normal Linux distribution. To obtain those tools, you have to download their source code and compile them on your Linux system. All these tools together make up the toolchain. Note, that the toolchain programs run on your local (Pentium-based) computer; they are only needed to build the OpenWRT firmware, but they will not be included in the firmware itself!

Downloading the OpenWRT sources

wget http://openwrt.org/cgi-bin/viewcvs.cgi/buildroot/buildroot.tar.gz
tar zxvf buildroot.tar.gz

Compiling the Sources

cd buildroot
make

This will take care of everything, including the toolchain. Just be patient, this takes a while. 'make' will occasionally download more source code from the Internet - i.e. you have to remain online while this is done. When 'make' finishes you will have numerous new files, including one with the name openwrt-gs-code.bin - this is the firmware for the WRT54GS Linksys router.

Hooking up the Linksys router

Now it is time to talk to the Linksys router. The original Linksys firmware contains a web-server which we can use to modify the bootloader and to upload our just created OpenWRT firmware.

But first we have to connect the Linksys router and the desktop PC through a network. Your desktop PC will most likely have an Ethernet cable connecting it to some outlet at the wall. Unplug that cable from the desktop PC and plug it instead into one of the four Ethernet ports at the back of the Linksys router (do not use the single Ethernet port, use one from the 4-port block!). Then plug another Ethernet cable into another port from the 4-port block, and plug the other end into the desktop PC. Now your desktop is again connected to the wall, through the Linksys router (see picture below). Note: This setup will not change the network connectivity for the desktop PC, since the Linksys router is actually an Ethernet switch, which is completely transparent for the desktop PC. (For this to work, the Linksys router needs to be turned on!)

Initially, the Linksys router has the IP address 192.168.1.1 - which is most likely not on a subnet with your desktop PC. Here is a trick to work around that problem: As superuser, create an alias network interface for a fictitious 192.168.1 subnet (see below). After that, the Linksys router and the desktop PC are both connected, via cable 2, to the 192.168.1 subnet, i.e. they can communicate with each other.

ifconfig  eth0:1  192.168.1.2

The eth0:1 network interface will automatically disappear the next time you reboot your desktop.

Now you are ready for primetime. On your desktop PC, start the Internet browser of your choice and enter the URL http://192.168.1.1 . This brings up the Linksys router's web interface. When asked for authentication, leave the User-ID field empty; as password enter 'admin' (without the quotes). Click around to learn a bit about the device, then modify the bootloader and upload the OpenWRT firmware, as described below.

Changing the Bootloader

We want to change a setting of the bootloader which is called boot_wait. If enabled, the boot process will be delayed for a few seconds - giving you a chance to send a new firmware, as will be shown below.

To enable boot_wait, the following commands must be executed on your Linksys router:

cp */*/nvram /tmp/n
*/n set boot_wait=on
*/n commit
*/n show

But how? You don't have a shell on the router where you could enter these commands.

Actually, you have a shell there! And that's the entire reason why we brought the router's web interface up. Locate the Ping.asp page (found under Administration >> Diagnostics) and perform a series of pings using the following lines as "addresses":

;cp${IFS}*/*/nvram${IFS}/tmp/n
;*/n${IFS}set${IFS}boot_wait=on
;*/n${IFS}commit
;*/n${IFS}show>tmp/ping.log

These are the same commands as shown before, modified slightly to work with the Ping.asp page. Carefully cut and paste one line at a time into the IP address field and hit "ping". You won't see any results. When you get to the last line, the ping results window will contain a long list of configuration variables, verify that boot_wait is set to on.PS:

Did you notice the trick? The input from the 'IP address' field is simply appended to a string "ping " and feed to a Shell. The ';' marks the end of one shell command (the one with the ping) and the beginning of a new command - which is then executed on the Linksys router - great, isn't it?

Troubleshooting: If you get the error message 'network unreachable', you router might not yet have a correct IP configuration. In the web-interface, go to (Setup >> Basic Setup) and set the IP address to 192.168.1.1; the Netmask to 255.255.255.0; and the Gateway to 192.168.1.2 (actually, the values do not really matter, as long as they are syntactically correct). Then push [Save Settings] at the bottom of the page and try the ping-trick again.

Uploading the firmware

Once boot_wait is enabled (see above), the power-LED will flash for about 3 seconds when the router is powered-on. While these LEDs are flashing you can use a normal tftp client to send a new firmware to the router.

Make sure the Linksys router and your desktop are hooked up as described above. Then ftp send the firmware immediately at bootup; this can be tricky so we suggest the following:

• power the router off by disconnecting the power cable
• open tftp and connect to 192.168.1.1, switch to binary mode and start sending the firmware while the router is still powered off
• immediately after the tftp client starts sending, plug in the router. Be sure you have tftp sending when it boots up.

tftp 192.168.1.1
tftp> binary
tftp> rexmt 1
tftp> trace
Packet tracing on.
tftp> put openwrt-gs-code.bin
tftp> quit

If you get an error message 'Code pattern is incorrect', then you sent the wrong firmware. If you get an error message 'Invalid password' then the router is no longer in boot_wait - you waited too long; just start over and try again.

After quitting tftp, wait for a few seconds, until the Power-LED is steady on (the router is rebooting). Then telnet in ...

Logging in for the first time - Initial setup

Once booted, OpenWRT should be configured to your previous settings. Simply telnet in

telnet  192.168.1.1

Then run the following:

firstboot

At this time, you might also want to change the router's IP address to something more reasonable. Use the following command sequence as a template.

nvram set wan_ipaddr=138.15.104.55
nvram set wan_netmask=255.255.255.0
nvram set wan_gateway=138.15.104.254
nvram set lan_ipaddr=138.15.104.55
nvram set lan_netmask=255.255.255.0
nvram set wan_dns=138.15.108.11
nvram commit

Note: The new values will take effect after you reboot. From that moment on use the new IP address, for example, in the telnet command - 192.168.1.1 will not work anymore!

The router's file system

OpenWRT uses two filesystems, squashfs and jffs2. The first time OpenWRT boots up it will boot from the (readonly) squashfs partition embedded in the firmware. Running the firstboot script will create a writable jffs2 partition on the unused portion of flash memory, which will be used as the new root file system; the process may take a few minutes. The WRT54GS has 8M of flash memory, which yields roughly 6M of jffs2 space.

To save space on the jffs2 partition, files are initially symlinks to the (readonly) squashfs version of the file. To edit a file, first remove the symlink and copy the old version from /rom to the writable jffs2 file system - then modify the file as you like.

Failsafe mode

Occasionally, through configuration error, the (writable) jffs2 partition becomes unbootable. To force the router to boot from the original (read-only) squashfs partition using default network settings you can use OpenWRT's failsafe mode: ,./:

mtd  unlock  mtd4
mount  -t jffs2  /dev/mtdblock/4  /jffs

If this does not help either, you can always load a fresh copy of the OpenWRT firmware to the router (see details above). However, this will also erase your changes on the jffs file system.

Part II: Adding software to the router

Installing existing/prepackaged software on the Linksys router - Ipkg

The ipkg utility is a minimalistic package manager that runs on the Linksys router. It is capable of downloading and installing prepackaged OpenWRT software from the Internet. Debian users familiar with the apt-get system will recognize the similarities.

First, hookup the Linksys router to the network, as described in Part I. Then login, using telnet or ssh (if you haven't changed it, then the router's IP address is still 192.168.1.1).

Ipkg maintains a list of available software on the Internet, which should be periodically updated:

ipkg update

To list the available packages, do:

ipkg list

To install one of the available packages, e.g. xyz, do:

ipkg install xyz

To remove a previously installed package xyz, do the following:

ipkg remove xyz

More packages are available from 3rd parties. The following link contains a list of OpenWRT Package Repositories: OpenWrtPackages. Simply add the corresponding lines to /etc/ipkg.conf.

Writing your own programs for the Linksys router

[to be written]

You may also want to consult http://www.kegel.com/crosstool/ for tips on cross-compiling.

Part III: Details about the Linksys router hardware

Ports:

• WAN: One 10/100 RJ-45 port for WAN connectivity
• LAN: Four 10/100 RJ-45 Auto-MDI(X) switched ports
• WLAN: 54mbps 802.11g on a MiniPCI built-in with dual external RP-TNC antenna ports

LED Indicators:

• Power
• DMZ
• WLAN: Act, Link
• LAN (4x): Link/Act, Full/Col, 100
• Internet: Link/Act, Full/Col, 100

RF Channels:

• 1-11 (USA)

Internal:

• RAM: 2 x IC42S16400, 64Mbit (4M X 16) RAM chips (16MB)
• Flash: Intel TE28F320 C3 flash 32Mbit chip (4MB)
• CPU: Broadcom BCM4712KPB, running at 200MHz
• Ethernet: ADMtek ADM6996 5 port 10/100 switch
• WLAN: On board; Broadcom BCM2050KWL

Device details:

• Width: 7.32 inches (186 mm)
• Height: 1.89 inches (48 mm)
• Depth: 6.89 inches (175 mm)

Transmit Power:

• 15 dBm (Can be increased to 20db)
• Note: 15db=31mW 17db=50mW 20db=100mW

Receiver Sensitivity (unconfirmed):

• -65db for ofdm 802.11g 54 megs
• -80db for dsss 802.11b 11 megs

Power:

• 5V @ 2.0A

Links

• Linksys WRT54G/WRT54GS Dual Serial Port Mod
• How to add a serial interface - DANGEROUS! (German)