Installing OpenWrt 19.07.3 on BT Homehub 5A

Installing OpenWrt 19.07.3 on BT Homehub 5A

After moving into a new property a few months ago, the drawbacks of using the ISP supplied firmware included on my router rapidly started to become apparent.

As a rule, ISP supplied firmwares tend to have poor support for custom DNS servers (no PiHole for you), lack an SSH server (ruling out remote administration) and do not allow the installation of software supplied by a third party, among other drawbacks.

This is not a conspiracy against end users - removing features that are infrequently used makes sense from a business perspective when you consider the extra man-hours required to develop, test and support them. Additionally, the attack surface of a device can be reduced by limiting the number of features capable of causing security issues if improperly configured.

Regardless, it’s still frustrating using a router that offers few of the features needed to have control over your home network.

Fortunately, the OpenWrt project offers an alternative firmware that is available for many embedded devices. I’ve been using it both professionally and at home for a number of years now, mostly for creating additional WLAN access points or repeaters connected to existing networks. OpenWrt has the advantages of a decent web interface (LUCI), shell access using the Dropbear SSH server and the option of installing extra software using the opkg package manager.

However, there are some significant drawbacks depending on the device that you use. Support for some devices lags behind others and is dependent on both the level of interest that the community takes in that device and the availability of open source drivers for the hardware within the router. This means that 2.4Ghz WiFi, 5Ghz WiFi, the modem or some combination thereof may not be functional.

This leaves us with the choice of buying either a new or used router with good support for OpenWrt. I prefer to reuse old hardware whenever it is practical and was lucky enough to have a BT Homehub 5A lying about unused. This router is a popular target for OpenWrt and has excellent hardware support but the installation process is quite convoluted, requiring you to solder wires to test points exposing a serial port and the boot mode selector.

You then need to load a modified version of U-Boot over the serial connection that allows booting via TFTP. This, in turn, is used to load a minimal OpenWrt image that allows you to back up the existing firmware and patch U-Boot to enable console access and modify the boot variables. Once this is done, you can install a full release of OpenWrt from a USB drive.


Prerequisites

To install OpenWrt on this device, you will need to download the following files:

There are a number of USB to Serial converters available, usually based on the CH340/341, CP102 or FT232RL chips. Any converter that supports 115200 bauds at 5 volts will do; in this article I am using one based on the CP102. A USB extension cable is not necessary but allows you some additional flexibility when working on the router.

You will also need a serial terminal emulator and TFTP server. You could use screen, minicom, picocom or a variety of others as your serial terminal; my personal preference is for picocom. For the TFTP server, I used aftpd.


Opening the case

This is perhaps the most difficult part of the installation. You will need to use a plastic card or spudger to work open the clips inside the case to release the front section and expose the PCB within. James Finnie has created a video detailing this process which I have included below.


Soldering to test points

Dodgy soldering job

You will now need to solder wires to the PCB of the router at the following locations:

Location Purpose
Right of R77 Serial RX
Right of R78 Serial TX
Above R45 Boot Select
Left USB GND

I used Dupont wires terminated with female connectors for this. The Dupont connectors made it easier to attach the wires to my serial converter but if I was to do this again, I’d probably use finer single core wire considering the size of the pads. Once the wires were attached, I taped them down to the PCB and case to provide some strain relief.


Booting into UART mode and loading U-Boot

You will need to connect the RX and TX wires to the matching pins on your serial converter and bridge the Boot Select wire to the ground wire with a jumper wire or paper clip. When ready, open a picocom session on your serial converter - on Linux, the serial converter is usually located within the /dev/ directory with a name beginning with ttyUSB* or ttyACM*:

picocom -b 115200 /dev/ttyUSB0

Turn on the router and wait until you see the output below:

ROM VER: 1.1.4
CFG 04
UART

When you see the output above, quickly remove the bridge wire between Boot Select and ground, then attach the ground wire to your serial converter.

In a separate terminal, use cat to send the U-Boot image to the device:

cat lede-lantiq-bthomehubv5a_ram-u-boot.asc > /dev/ttyUSB0

This will take a few minutes to load. Once this is completed, you should see output in picocom similar to that below:

U-Boot 2013.10-openwrt4 (Nov 05 2016 - 21:13:45) BTHOMEHUBV5A

Board: BT Home Hub 5A
SoC:   Lantiq VRX268 v1.2
CPU:   125 MHz
IO:    125 MHz
BUS:   125 MHz
BOOT:  UART
DRAM:  128 MiB
NAND:  128 MiB
Using default environment

In:    serial
Out:   serial
Err:   serial
Net:   ltq-eth
Hit any key to stop autoboot:  0 
UBI: attaching mtd1 to ubi0
UBI: physical eraseblock size:   131072 bytes (128 KiB)
UBI: logical eraseblock size:    129024 bytes
UBI: smallest flash I/O unit:    2048
UBI: sub-page size:              512
UBI: VID header offset:          512 (aligned 512)
UBI: data offset:                2048
UBI: attached mtd1 to ubi0
UBI: MTD device name:            "mtd=0"
UBI: MTD device size:            126 MiB
UBI: number of good PEBs:        1012
UBI: number of bad PEBs:         0
UBI: max. allowed volumes:       128
UBI: wear-leveling threshold:    4096
UBI: number of internal volumes: 1
UBI: number of user volumes:     3
UBI: available PEBs:             9
UBI: total number of reserved PEBs: 1003
UBI: number of PEBs reserved for bad PEB handling: 10
UBI: max/mean erase counter: 1757/1260
Read 0 bytes from volume kernel to 81000000
Volume kernel not found!
Wrong Image Format for bootm command
ERROR: can't get kernel image!
BTHOMEHUBV5A #

Loading the install image

The router is now ready to load a firmware image over TFTP. You will need to configure our Ethernet interface to temporarily use a static IP address - this build of U-Boot is configured to load an image from 192.168.1.2.

To do so, disconnect any existing connection on this interface and issue the following command, replacing eth0 with the name of your Ethernet interface if necessary:

sudo ifconfig eth0 192.168.1.2

Next, prepare the directory that you will serve the firmware image from and move the minimal install image to it:

sudo mkdir /tftpboot
sudo chmod 777 /tftpboot
mv ~/Downloads/lede-lantiq-xrx200-BTHOMEHUBV5A-installimage.bin /tftpboot

Finally, start the TFTP server. This needs to run as root as the TFTP protocol uses port 69, a privileged port:

sudo atftpd --bind-address 192.168.1.2 --daemon --no-fork /tftpboot/

If you are running Ubuntu 18.04/20.04, this command may exit immediately. This is because the package provided with this distribution adds an entry to /etc/inetd.conf which runs atftpd with different parameters to those above. This can be verified using netstat:

user@ubuntu:~$ sudo netstat -plunt | grep :69
udp        0      0 0.0.0.0:69              0.0.0.0:*                           861/inetutils-inetd 

To avoid this, stop the inetutils-inetd service:

sudo systemctl stop inetutils-inetd.service

To load the minimal image, issue the following command within the picocom session:

BTHOMEHUBV5A # tftpboot 0x81000000 lede-lantiq-xrx200-BTHOMEHUBV5A-installimage.bin; bootm 0x81000000

Once the image has loaded, you should see output similar to this:

ltq_phy: addr 0, link 0, speed 10, duplex 0
ltq_phy: addr 1, link 0, speed 10, duplex 0
ltq_phy: addr 17, link 0, speed 10, duplex 0
ltq_phy: addr 19, link 1, speed 1000, duplex 1
ltq_phy: addr 5, link 0, speed 10, duplex 0
Using ltq-eth device
TFTP from server 192.168.1.2; our IP address is 192.168.1.1
Filename 'lede-lantiq-xrx200-BTHOMEHUBV5A-installimage.bin'.
Load address: 0x81000000
Loading: #################################################################
	 #################################################################
	 #################################################################
	 ##########################################
done
Bytes transferred = 3474686 (3504fe hex)
## Booting kernel from Legacy Image at 81000000 ...
   Image Name:   MIPS LEDE Linux-4.4.30
   Created:      2016-11-05  20:35:36 UTC
   Image Type:   MIPS Linux Kernel Image (lzma compressed)
   Data Size:    3474622 Bytes = 3.3 MiB
   Load Address: 80002000
   Entry Point:  80002000
   Verifying Checksum ... OK
   Uncompressing Kernel Image ... OK

Starting kernel ...

[    0.000000] Linux version 4.4.30 (mkresin@desktop) (gcc version 5.4.0 (LEDE GCC 5.4.0 r2112+5) ) #0 Sat Nov 5 20:35:36 2016
[    0.000000] SoC: xRX200 rev 1.2
[    0.000000] bootconsole [early0] enabled
[    0.000000] CPU0 revision is: 00019556 (MIPS 34Kc)
[    0.000000] MIPS: machine is BTHOMEHUBV5A - BT Home Hub 5A
...

Backing up original firmware and preparing for install

Once the minimal image has finished booting, you will presented with the guide below:

*******************************************************************************
*    Guide for installing LEDE onto a BT Home Hub 5 Type A/Plusnet Hub One    *
*******************************************************************************

You need an USB flash drive with at least 512MB free capacity, formatted as
FAT32 or exFAT, attached to the Hub. The attached flash drive will be
accessible at /tmp/mounts/<directory>.

To install LEDE, the USB flash drive must have a copy of the file:
  lede-lantiq-xrx200-BTHOMEHUBV5A-squashfs-sysupgrade.bin

To restore the stock Firmware, the USB flash drive must have a have a copy
of the nanddump backup file (hh5a.nanddump) containing the stock Firmware.

LIST OF COMMANDS

  To create a backup of the installed firmware (Take care to not overwrite
  any previously made backup):
      nanddump --file /tmp/mounts/<directory>/hh5a.nanddump /dev/mtd4

  To install LEDE:
      prepare

  To restore stock firmware:
      restore

TO UPGRADE FROM OpenWrt OR LEDE PRIOR TO XXX:

  Restore the stock firmware and do a fresh install of LEDE.

If you don't have a backup of the stock firmware from your Hub, use the
experimental 'migrate' script. It is offered with no guarantee of success. 
You are strongly advised to restore the stock firmware.

From here, things are fairly self explanatory.

The first step is to create a backup of the original firmware. This will allow you to restore the original state of the device, including the bootloader and firmware. The backup is unique to each device, as it contains MAC addresses and calibration data for the wireless radios, among other things.

root@lede:/# nanddump --file /tmp/mounts/hh5.dump /dev/mtd4
ECC failed: 0
ECC corrected: 0
Number of bad blocks: 0
Number of bbt blocks: 4
Block size 131072, page size 2048, OOB size 64
Dumping data starting at 0x00000000 and ending at 0x08000000...

This will take a while to complete (around 25 minutes in this case but others have reported shorter backup times). Once this is complete, you can prepare the router for the installation of OpenWRT:

root@lede:/# prepare

This script will erase parts of the Nand flash memory on this Hub, and then
prepare it for running Sysupgrade.


WARNING: DO NOT CONTINUE unless you have saved a backup of the original firmware
         to your COMPUTER or other storage device!


DO NOT POWER OFF THE DEVICE DURING THIS PROCEDURE.


Please enter YESIHAVEABACKUP to continue:
YESIHAVEABACKUP

Starting installation...

Please select you device:

a) BT Home Hub 5 Type A
b) Plusnet Hub One

a

WRITING custom uboot-env to unlock u-boot console and update bootcmd...
Erasing 128 Kibyte @ 0 -- 100 % complete 
Writing data to block 0 at offset 0x0

REMOVING ubi volume OpenRG...
[ 1688.651185] ubi0: reserved more 1 PEBs for bad PEB handling

REMOVING ubi volume FFS...


Preparation completed!

Your attached USB media is mounted as a subdirectory at /tmp/mounts/

To install LEDE, run:

  sysupgrade /tmp/mounts/<directory>/lede-lantiq-xrx200-BTHOMEHUBV5A-squashfs-sysupgrade.bin

Sysupgrade will automatically restart your device when it has finished.
If the UART prompt appears, power-cycle your device!
The hub should now boot up using LEDE.

The final step is to run the sysupgrade utility to install a full version of OpenWRT.

root@lede:/# sysupgrade /tmp/mount/openwrt-19.07.3-lantiq-xrx200-bt_homehub-v5a-squashfs-sysupgrade.bin 
Cannot save config while running from ramdisk.
killall: watchdog: no process killed
Watchdog handover: fd=3
- watchdog -
killall: telnetd: no process killed
Sending TERM to remaining processes ... ubusd logd netifd odhcpd mountd ntpd dnsmasq 
Sending KILL to remaining processes ... 
Volume ID 0, size 16 LEBs (2064384 bytes, 2.0 MiB), LEB size 129024 bytes (126.0 KiB), dynamic, name "kernel", alignment 1
Volume ID 1, size 30 LEBs (3870720 bytes, 3.7 MiB), LEB size 129024 bytes (126.0 KiB), dynamic, name "rootfs", alignment 1
Set volume size to 121411584
Volume ID 2, size 941 LEBs (121411584 bytes, 115.8 MiB), LEB size 129024 bytes (126.0 KiB), dynamic, name "rootfs_data", alignment 1
sysupgrade successful

OpenWRT is now installed! My router rebooted into UART mode on the first reboot, but this was easily fixed by following the guidance in the output of prepare and power-cycling the router.

Conclusion

Although installing OpenWRT over the serial port probably felt quite intimidating, there are a number of benefits gained by doing so:

  • A router with performance and functionality that is usually found only in much more expensive routers
  • Skills that can be useful when debricking or reverse engineering other embedded devices
  • By re-using an old router, you’ve made a small contribution to reducing the amount of e-waste in the world

I will not be covering the setup of this device in this article (it’s destined for a mundane life hooked up to an ADSL line), but some useful resources can be found here: