Active Antenna Reprogramming
This page is about reprogramming the Active Antenna, which is a standalone version of the XO laptop's wireless mesh network interface.
Introduction
The Active Antenna performs two functions: it serves as a mesh access point for school servers, and it serves as a stand-alone mesh repeater. It was tension between these two functions that led to the pre-build and prototype builds to be manufactured with firmware which puts them into the mesh repeater mode before a server has had time to boot (Trac #4632). This page describes the setup for reprogramming the firmware, then either how to "fix" an Active Antenna for use with a server, or how to upgrade the firmware on a mesh repeater.
Two methods are documented for updating the Active Antenna. One, the Driver Method, requires replacing the drivers and works on XO laptops. Another, the User Space Method, requires that drivers for the antenna not be installed, and does not work with these instructions on XO laptops.
What version of firmware is an antenna running ?
You can determine which Boot2 firmware is currently on the Active Antenna using:
lsusb -v -d 1286:2001 | grep bcdDevice
The response should be something like "31.09" (indicating the shipped Boot2 firmware version), "31.07" (indicating current boot-from-host-only Boot2 firmware), or "31.1A" (indicating current stand-alone mesh repeater firmware). If you get a response other than this, please contact server-devel at laptop.org as upgrading earlier versions (which shouldn't be encountered in the field) require additional steps.
lsusb is part of the usbutils package, which can be installed on an XO by typing:
yum install usbutils
Sysfs Method
This is the new and recommended method to upgrade both boot2 and firmware in the Active Antennae. The other methods in this page are not recommended or supported anymore.
Required bits are committed to the testing branch of the olpc kernel tree. There is also at least two kernel RPM packages with the necessary changes to the Libertas drive already available. They are both based on the stable branch (so probably equivalent):
- http://dev.laptop.org/~dsaxena/kernel-2.6.22-20080722.1.olpc.0.i586.rpm
- http://dev.laptop.org/~rcarrano/kernel-2.6.22-20080721.1.olpc.0_carrano.i586.rpm
The firmware release 5.110.22.p17 supports the update of boot2/firmware/non-volatile parameters to the standalone module (active antenna) and should be used in this procedure:
Before proceeding: Do not install 31.1B boot2 version with this method
- Install firmware 22.p17 in the host (by copying it to /lib/firmware with name usb8388.bin and then restart the XO or reload the usb8xxx module)
- To update the boot2, execute:
echo <boot2_img> > /sys/class/net/<interface>/lbs_flash_boot2
- To update the firmware, execute:
echo /lib/firmware/usb8388.bin > /sys/class/net/<interface>/lbs_flash_fw
After you upgrade your active antenna, you might be able to set some persistent configuration parameters
Driver Method
Marvell's current recommended method to update the software on the 8388's EEPROM is to use code that runs on the radio's ARM processor itself and not on the host (as the method described above). The required code exists inside wireless firmware version 5.126.0 (and later versions in that series).
Modified Drivers and Patches
Modified drivers, along with the appropriate firmware, can be found at http://dev.laptop.org/pub/firmware/libertas/repeater/libertas-eeprom-downgrade.tar.gz (for downgrading an antenna for proper operation with a server) and http://dev.laptop.org/pub/firmware/libertas/repeater/libertas-eeprom-upgrade.tar.gz (for proper operation as a repeater).
The driver patch source can be found at http://dev.laptop.org/pub/firmware/libertas/repeater/libertas-driver-with-eeprom-programming-support.tar.gz, along with compiled libertas driver kernel objects that can be used in the XO (tested with build 675).
Downgrading
The pre-build and prototype builds of the Active Antennae were unfortunately manufactured with firmware which puts them into a stand-alone mesh repeater mode before a server has had time to boot (Trac #4632). In order to this, you will need to downgrade the Boot2 code installed on the Antenna.
Download the modified driver and required firmware tarball from http://dev.laptop.org/pub/firmware/libertas/repeater/libertas-eeprom-downgrade.tar.gz.
Untar the package on an XO laptop running a build such as 684:
tar xfz libertas-eeprom-downgrade.tar.gz
Back up the old drivers and install the new driver modules:
cp -r /lib/modules/`uname -r`/kernel/drivers/net/wireless/libertas . cp libertas-eeprom-downgrade/*.ko /lib/modules/`uname -r`/kernel/drivers/net/wireless/libertas/
Now place the appropriate boot2 and firmware files in /lib/firmware/usb8388_boot2.bin and /lib/firmware/usb8388_fw.bin respectively.
mv /lib/firmware/usb8388.bin . ln -s /root/libertas-eeprom-downgrade/usb8338-5.126.0.p2.bin /lib/firmware/usb8388.bin ln -s /root/libertas-eeprom-downgrade/Boot2_3107.bin /lib/firmware/usb8388_boot2.bin ln -s /root/libertas-eeprom-downgrade/usb8338-5.126.0.p2.bin /lib/firmware/usb8388_fw.bin
Now reboot the laptop.
Programming
After installing the new firmware and drivers on the laptop, reboot it. Plug the Active Antenna being reprogrammed into the laptop.
Now the actual EEPROM programming commands can be issued:
iwpriv eth1 boot2_upgrade
Wait for the LED on the module to stop blinking before unplugging. You must unplug and reinsert the Active Antenna for the upgrade to be noticeable. If successful, the Boot2 version will be reported as 31.07.
Please note that on current XOs (B3 and later), eth0 is the built-in radio. Please make sure that you do not update the boot2 code on it.
Upgrading to a Repeater
Download the modified driver and required firmware tarball from http://dev.laptop.org/pub/firmware/libertas/repeater/libertas-eeprom-upgrade.tar.gz.
Untar the package on an XO:
tar xfz libertas-eeprom-upgrade.tar.gz
Back up the old drivers and install the new driver modules:
cp -r /lib/modules/`uname -r`/kernel/drivers/net/wireless/libertas . cp libertas-eeprom-upgrade/*.ko /lib/modules/`uname -r`/kernel/drivers/net/wireless/libertas/
Now place the appropriate boot2 and firmware files: in /lib/firmware/usb8388_boot2.bin and /lib/firmware/usb8388_fw.bin respectively.
mv /lib/firmware/usb8388.bin . ln -s /root/libertas-eeprom-upgrade/usb8338-5.126.0.p2.bin /lib/firmware/usb8388.bin ln -s /root/libertas-eeprom-upgrade/Boot2_311A.bin /lib/firmware/usb8388_boot2.bin ln -s /root/libertas-eeprom-upgrade/usb8338-5.126.0.p2.bin /lib/firmware/usb8388_fw.bin
Programming
After installing the new firmware and drivers on the laptop, reboot it. Plug the Active Antenna being reprogrammed into the laptop.
Now the actual EEPROM programming commands can be issued:
iwpriv eth1 boot2_upgrade
Wait for the LED on the module to stop blinking before proceeding with
iwpriv eth1 fw_upgrade
This one will take a bit longer...
Please note that on current XOs (B3 and later), eth0 is the built-in radio. Please make sure that you do not update the boot2 code on it.
User Space Method
This method, while more generic, has the potential to fail (it has failed twice during programming of twelve units). If it fails, the Active Antenna is rendered useless (it can be recovered using JTAG programming of the onboard EEPROM).
Setup
Prerequisites
The system used to reprogram the Antenna probably needs to be either Fedora 6 or Fedora 7 (such as an XS School Server).
It should NOT have drivers for the Active Antennae installed. If using an XS school server build, move the drivers out of the way (don't forget to move them back when you are done!:
mv /lib/modules/`uname -r`/kernel/drivers/net/wireless/libertas /root
It will need to have the libusb development headers installed:
yum install libusb-devel
Obtaining the software
The software needed to program the firmware on the Active Antennae is available from [1] :
git clone git://git.infradead.org/libertas-flash
You will need to compile part of the software:
cd libertas-flash make
Fixing an Active Antenna
The pre-build and prototype builds of the Active Antennae were unfortunately manufactured with firmware which puts them into a stand-alone mesh repeater mode before a server has had time to boot (Trac #4632). In order to this, you will need to downgrade the Boot2 code installed on the Antenna.
You can determine which Boot2 firmware is currently on the Active Antenna using:
lsusb -v -d 1286:2001 | grep bcdDevice
The response should be something like "31.09" (indicating the shipped Boot2 firmware version), "31.07" (indicating current boot-from-host-only Boot2 firmware), or "31.1A" (indicating current stand-alone mesh repeater firmware). If you get a response other than this, please contact server-devel at laptop.org as upgrading earlier versions (which shouldn't be encountered in the field) require additional steps.
lsusb is part of the usbutils package, which can be installed on an XO by typing:
yum install usbutils
Obtaining the Antenna Firmware
The currently recommended Boot2 code for Active Antennae not acting as stand-alone mesh repeaters is release 3107. You can download a copy of this code, named Boot2_3107.bin, from http://dev.laptop.org/pub/firmware/libertas/boot2/Boot2_3107.bin.
Programming the Antenna
In downgrading the Active Antenna, speed is of the essence. After plugging the Antenna into USB, you have less than ten seconds to begin the programming or it will fail. After downloading the required software and firmware, and running sudo ls so your password is cached, plug in the antenna and immediately type:
sudo ./libertas-flash.py -v Boot2_3107.bin
If this is sucessful, you will be prompted at the end to "power cycle your board or replug your card". You should reboot the Active Antenna by unplugging it from USB.
Ignored Warnings
Currently, the libertas-flash.py software generates a warning when loading the software into the Active Antenna:
./libertas-flash.py:249: DeprecationWarning: struct integer overflow masking is deprecated
buf = struct.pack("<%dB" % len(response), *response)
./libertas-flash.py:249: DeprecationWarning: 'B' format requires 0 <= number <= 255
buf = struct.pack("<%dB" % len(response), *response)
This does not seem to impact the proper operation of the loader, and can be ignored.
Upgrading a Mesh Repeater
If you are trying to use an Active Antenna as a stand-alone mesh repeater, you will want to upgrade both the Boot2 firmware and the firmware used for normal operation.
Obtaining the Repeater Firmware
The currently recommended Boot2 code for Active Antennae acting as stand-alone mesh repeaters is release 311A. You can download a copy of this code from http://dev.laptop.org/pub/firmware/libertas/boot2/Boot2_311A.bin.
The currently recommended operating firmware for Active Antennae acting as stand-alone mesh repeaters is release 126.0.p2. You can download a copy of this code from http://dev.laptop.org/pub/firmware/libertas/repeater/usb8388_126.0.p2.img
Updating the Repeater
As above, speed may be required when updating a repeater running version 3109 of Boot2 firmware.
After downloading the required software and firmware, plug in the antenna and immediately type:
sudo ./libertas-flash.py -v Boot2_311A.bin
If this is successful, you will be prompted to "power cycle your board or replug your card". Do this by unplugging the Active Antenna, then plugging it back in. Now repeat the process to program the "operational" firmware into the Antenna:
sudo ./libertas-flash.py -v usb8388_126.0.p2.img
You should now have an stand-alone mesh repeater (operating on channel 1).
Testing the Repeater
In order to test the operation of the repeater, follow these steps:
- Plug the repeater into a school server and write down its MAC address (obtained from ifconfig).
- You will need a school server (or another laptop) supporting a mesh on channel 1.
- Take an XO laptop, and modify it to have a blinding table which only allows it to communicate with the repeater's MAC address.
- With the repeater unpowered, attempt to communicate with the school server or laptop on channel 1. If this succeeds, the previous step wasn't done correctly. If everything is setup properly, you should NOT be able to communicate with any other devices on the mesh.
- Power on the repeater (and wait a couple of minutes for it to enter repeater mode.)
- Now the blinded laptop should be able to communicate with the school server/laptop on mesh channel 1.