Active Antenna Reprogramming: Difference between revisions

From OLPC
Jump to navigation Jump to search
No edit summary
(categorize, some link freshening)
 
(12 intermediate revisions by 4 users not shown)
Line 1: Line 1:
<noinclude>{{OLPC}}[[Category:Network]]{{TOCright}}</noinclude>
{{OLPC}}


This page is about reprogramming the [[Active Antenna]], which is a standalone version of the XO laptop's [[Mesh_Network_Details|wireless mesh network interface]].
This page is about reprogramming the [[Active Antenna]], which is a standalone version of the XO laptop's [[Mesh_Network_Details|wireless mesh network interface]].


=Introduction=
==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 [[Active_Antenna#Pre-Build|pre-build]] and [[Active_Antenna#Prototype|prototype builds]] to be manufactured with firmware which puts them into the mesh repeater mode before a server has had time to boot ([http://dev.laptop.org/ticket/4632 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.
The [[Active Antenna]] performs two functions: it serves as a mesh interface for school servers, and it serves as a stand-alone mesh repeater. It was tension between these two functions that led to the [[Active_Antenna#Pre-Build|pre-build]] and [[Active_Antenna#Prototype|prototype builds]] to be manufactured with firmware which puts them into the mesh repeater mode before a server has had time to boot ([http://dev.laptop.org/ticket/4632 Trac #4632]). This page describes the recommended setup for reprogramming the firmware. It also describes how to "fix" an [[Active Antenna]] for use with a server, and how to upgrade the firmware on a mesh repeater.


Two methods are documented for updating the Active Antenna. One, the [[#Driver_Method|Driver Method]], requires replacing the drivers and works on XO laptops. Another, the [[#User_Space_Method|User Space Method]], requires that
Two older methods are documented for updating the Active Antenna. One, the [[#Driver_Method|Driver Method]], requires replacing the drivers and works on XO laptops. Another, the [[#User_Space_Method|User Space Method]], requires that drivers for the antenna not be installed, and does not work with these instructions on XO laptops. These older methods are undesirable because they require manipulating the installed drivers. This page also describes a third way, the sysfs method, that is the recommended way to reprogram the active antenna.
drivers for the antenna not be installed, and does not work with these instructions on XO laptops.


===Background on Active Antenna Firmware===
==What version of firmware is an antenna running ?==


Users may be slightly confused about which firmware images go where, why they go there, and what they do. This section provides a bit of background so that users upgrading the firmware can understand what, exactly, they are doing.
You can determine which Boot2 firmware is currently on the Active Antenna using:


Boot2 is the bootloader that resides in the persistent memory of all mesh interfaces, whether built into the XO or in an Active Antenna. When the mesh device is powered on, Boot2 is the first thing to run. Older versions of Boot2 wait to be initialized by a USB host (e.g., the XO or school server), which will pass a firmware image that Boot2 will load and execute (i.e., the firmware image in /lib/firmware/usb8388.bin). This is the common behavior for the XO's built-in interface.
lsusb -v -d 1286:2001 | grep bcdDevice


Newer versions of Boot2, such as those shipped on the Active Antenna, decide whether to load and run a firmware image from the USB host, or whether to load and run a firmware image that has been flashed to its persistent memory (i.e., stand-alone or mesh-repeater mode). They make this decision by waiting for a configurable amount of time to hear from a host (see [[Active Antenna Persistent Configuration]]), then booting the persistent firmware if it hears nothing. Note that this behavior does not apply to the XO's built-in wireless device. For one reason, these devices do not have persistent firmware. For another, they are always attached to a USB host because they are built in. For still another, they ship with older versions of Boot2 that unconditionally load firmware from a USB host.
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.


So, when you update Boot2 as described below, you are simply writing a new Boot2 image to the persistent memory of the device. Every time the device is powered on, this version of Boot2 will run. Similarly, when flashing the firmware image, you are updating the firmware image in the device's persistent memory. This new firmware image will only run if Boot2 times out waiting for contact from a USB host.
lsusb is part of the usbutils package, which can be installed on an XO by typing:
yum install usbutils


===What version of Boot2 and firmware is an Active Antenna running ?===
=Driver Method=


You can determine which Boot2 firmware is currently on the Active Antenna or built-in wireless device using:
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 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 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 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 [[Active_Antenna#Pre-Build|pre-build]] and [[Active_Antenna#Prototype|prototype builds]] of the Active Antennas were unfortunately manufactured with firmware which puts them into a stand-alone mesh repeater mode before a server has had time to boot ([http://dev.laptop.org/ticket/4632 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 http://dev.laptop.org/pub/firmware/libertas/repeater/libertas-eeprom-downgrade.tar.gz].

Untar the package on an XO:
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

===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 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_Server_Software|XS School Server]]).

It should NOT have drivers for the Active Antennas 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 Antennas is available from <tt>[git://git.infradead.org/libertas-flash]</tt> :

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 [[Active_Antenna#Pre-Build|pre-build]] and [[Active_Antenna#Prototype|prototype builds]] of the Active Antennas were unfortunately manufactured with firmware which puts them into a stand-alone mesh repeater mode before a server has had time to boot ([http://dev.laptop.org/ticket/4632 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
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.
The response should be something like "31.09" (indicating the shipped Boot2 version), "31.07" (indicating current boot-from-host-only Boot2), or "31.1A" (indicating current boot-stand-alone-or-host Boot2). 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:
lsusb is part of the usbutils package, which can be installed on an XO by typing:
yum install usbutils
yum install usbutils


Determining which version of the firmware an Active Antenna is running depends on whether it is plugged into a USB host or whether it is operating in "stand-alone/mesh-repeater" mode. In the former case, the firmware is loaded over USB by the host. You can determine the firmware version by typing:
===Obtaining the Antenna Firmware===

The currently recommended Boot2 code for Active Antennas not acting as stand-alone mesh repeaters is release 3107. You can download a copy of this code, named <tt>Boot2_3107.bin</tt>, from [http://dev.laptop.org/pub/firmware/libertas/boot2/Boot2_3107.bin 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 <tt>sudo ls</tt> 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 Antennas 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 http://dev.laptop.org/pub/firmware/libertas/boot2/Boot2_311A.bin].


ethtool -i ethX | grep firmware
The currently recommended operating firmware for Active Antennas 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 http://dev.laptop.org/pub/firmware/libertas/repeater/usb8388_126.0.p2.img]


This, of course, is simply the version of the firmware that is currently installed in /lib/firmware/usb8388.bin. In the latter case, you will need a sniffer to determine the firmware version. First, plug the Active Antenna into a host and check which channel it is configured to use:
===Updating the Repeater===
cat /sys/class/net/ethX/boot_options/channel


While you're at it, note the MAC address of the Active Antenna using ifconfig. Now unplug the it and boot it as a stand-alone mesh repeater by applying 5v (i.e., NOT by plugging it into a USB host). Sniff on the proper channel for beacons with the Active Antenna's MAC address as the source. The beacon will contain the firmware version number.
As [[#Programming_the_Antenna|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:
== How to upgrade the boot2 and the firmware in the Active Antennae? ==


Note: This is page describes the currently recommended method to upgrade both boot2 and firmware in the Active Antennae, which is based on the sysfs pseudo-filesystem. If you are interested in the older (unsupported) methods, they are documented [[Active_Antenna_Reprogramming_Old_Methods |in this page]].
sudo ./libertas-flash.py -v Boot2_311A.bin


Required bits are committed to the [http://dev.laptop.org/git?p=olpc-2.6;a=shortlog;h=testing ''testing'' branch of the olpc kernel tree]. There is also at least two kernel RPM packages with the necessary changes to the Libertas driver already available. They are both based on the ''stable'' branch (so probably equivalent):
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:
* 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 [http://dev.laptop.org/ticket/7528 5.110.22.p17] supports the update of boot2, firmware, and [[Active Antenna Persistent Configuration|persistent configuration]] of the Active Antenna and should be used in this procedure:
sudo ./libertas-flash.py -v usb8388_126.0.p2.img


<font color=red>WARNING</font>: Do not install version 31.1B of Boot2 with this method! This particular version of Boot2 has known problems.
You should now have an stand-alone mesh repeater (operating on channel 1).


* 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)
===Testing the Repeater===
* Ensure that the images you wish to flash to the device are in /lib/firmware. In all likelihood, the firmware you wish to flash is simply the usb8388.bin that is already present. (Question: where does the boot2 image come from?)
* To update the boot2, execute:
echo <boot2_img> > /sys/class/net/<interface>/lbs_flash_boot2
* To update the firmware, execute:
echo usb8388.bin > /sys/class/net/<interface>/lbs_flash_fw


Note that if you try to use these methods on a built-in device, or with an older version of firmware, they will fail with a Not Supported error.
In order to test the operation of the repeater, follow these steps:


After you upgrade your active antenna, you might wish to set some [[Active_Antenna_Persistent_Configuration |persistent configuration parameters]]
* 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 [[Mesh_Debug#Changes_to_the_Laptop|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.

Latest revision as of 17:37, 14 September 2011

  This page is monitored by the OLPC team.

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 interface 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 recommended setup for reprogramming the firmware. It also describes how to "fix" an Active Antenna for use with a server, and how to upgrade the firmware on a mesh repeater.

Two older 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. These older methods are undesirable because they require manipulating the installed drivers. This page also describes a third way, the sysfs method, that is the recommended way to reprogram the active antenna.

Background on Active Antenna Firmware

Users may be slightly confused about which firmware images go where, why they go there, and what they do. This section provides a bit of background so that users upgrading the firmware can understand what, exactly, they are doing.

Boot2 is the bootloader that resides in the persistent memory of all mesh interfaces, whether built into the XO or in an Active Antenna. When the mesh device is powered on, Boot2 is the first thing to run. Older versions of Boot2 wait to be initialized by a USB host (e.g., the XO or school server), which will pass a firmware image that Boot2 will load and execute (i.e., the firmware image in /lib/firmware/usb8388.bin). This is the common behavior for the XO's built-in interface.

Newer versions of Boot2, such as those shipped on the Active Antenna, decide whether to load and run a firmware image from the USB host, or whether to load and run a firmware image that has been flashed to its persistent memory (i.e., stand-alone or mesh-repeater mode). They make this decision by waiting for a configurable amount of time to hear from a host (see Active Antenna Persistent Configuration), then booting the persistent firmware if it hears nothing. Note that this behavior does not apply to the XO's built-in wireless device. For one reason, these devices do not have persistent firmware. For another, they are always attached to a USB host because they are built in. For still another, they ship with older versions of Boot2 that unconditionally load firmware from a USB host.

So, when you update Boot2 as described below, you are simply writing a new Boot2 image to the persistent memory of the device. Every time the device is powered on, this version of Boot2 will run. Similarly, when flashing the firmware image, you are updating the firmware image in the device's persistent memory. This new firmware image will only run if Boot2 times out waiting for contact from a USB host.

What version of Boot2 and firmware is an Active Antenna running ?

You can determine which Boot2 firmware is currently on the Active Antenna or built-in wireless device using: 

lsusb -v -d 1286:2001 | grep bcdDevice

The response should be something like "31.09" (indicating the shipped Boot2 version), "31.07" (indicating current boot-from-host-only Boot2), or "31.1A" (indicating current boot-stand-alone-or-host Boot2). 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

Determining which version of the firmware an Active Antenna is running depends on whether it is plugged into a USB host or whether it is operating in "stand-alone/mesh-repeater" mode. In the former case, the firmware is loaded over USB by the host. You can determine the firmware version by typing: 

ethtool -i ethX | grep firmware

This, of course, is simply the version of the firmware that is currently installed in /lib/firmware/usb8388.bin. In the latter case, you will need a sniffer to determine the firmware version. First, plug the Active Antenna into a host and check which channel it is configured to use: 

cat /sys/class/net/ethX/boot_options/channel

While you're at it, note the MAC address of the Active Antenna using ifconfig. Now unplug the it and boot it as a stand-alone mesh repeater by applying 5v (i.e., NOT by plugging it into a USB host). Sniff on the proper channel for beacons with the Active Antenna's MAC address as the source. The beacon will contain the firmware version number.

How to upgrade the boot2 and the firmware in the Active Antennae?

Note: This is page describes the currently recommended method to upgrade both boot2 and firmware in the Active Antennae, which is based on the sysfs pseudo-filesystem. If you are interested in the older (unsupported) methods, they are documented in this page.

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 driver already available. They are both based on the stable branch (so probably equivalent):

The firmware release 5.110.22.p17 supports the update of boot2, firmware, and persistent configuration of the Active Antenna and should be used in this procedure:

WARNING: Do not install version 31.1B of Boot2 with this method! This particular version of Boot2 has known problems.

  • 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)
  • Ensure that the images you wish to flash to the device are in /lib/firmware. In all likelihood, the firmware you wish to flash is simply the usb8388.bin that is already present. (Question: where does the boot2 image come from?)
  • To update the boot2, execute:
echo <boot2_img> > /sys/class/net/<interface>/lbs_flash_boot2
  • To update the firmware, execute:
echo usb8388.bin > /sys/class/net/<interface>/lbs_flash_fw

Note that if you try to use these methods on a built-in device, or with an older version of firmware, they will fail with a Not Supported error.

After you upgrade your active antenna, you might wish to set some persistent configuration parameters

Retrieved from "http://wiki.laptop.org/mediawiki/index.php?title=Active_Antenna_Reprogramming&oldid=260302"