.B Please read the entire manpage prior using this utility. It may prevent you from problems arising later.
.SH SYNOPSIS
.B ap-tftp
-.B -l
+.B -i
+.IR IP
+.B -f
.IR firmware.rom
-.B IP
+.B [-c
+.IR community
+.B ]
.SH DESCRIPTION
The
.B ap-tftp
-utility is used to upgrade firmware in Access Points based on ATMEL AT76C510 VNET-B WiSOC (Wireless System On Chip). It should work for most (if not all) models with INTERSIL radio chipset, as well as those based on RFMD radio. However, so far it has only been tested on the following hardware: WLink WEN-2021, i-Tec AP GOLD (both with INTERSIL radio), and Tellus A14 (RFMD radio). If you have an AP with ATMEL AT76C510 and either INTERSIL or RFMD radio chipset, there's near 100% chance it will work for you, too.
+utility is used to upgrade or downgrade firmware in Access Points based on ATMEL AT76C510 VNET-B WiSOC (Wireless System On Chip). It should work for most (if not all) models with INTERSIL radio chipset, as well as those based on RFMD radio. However, so far it has only been tested on the following hardware: WLink WEN-2021, i-Tec AP GOLD, smartBridges airPOINT PRO (all with INTERSIL radio), and Tellus A14 (RFMD radio). If you have an AP with ATMEL AT76C510 and either INTERSIL or RFMD radio chipset, there's near 100% chance it will work for you, too.
.SH PREFACE: FIRMWARE TYPES
Functionally, there basically exist 2 types of firmware for ATMEL-based APs: an "
.B Access Point
-firmware (often referred as
-.B AP
-firmware), and
+firmware (often referred to as
+.B AP firmware
+), and
.B Wireless Adapter
firmware (referred to as
-.B WA
-firmware). Many hardware vendors produce their own more or less modified firmware derivatives, but usually they keep up with naming scheme introduced by ATMEL:
+.B WA firmware
+). Many hardware vendors produce their own more or less modified firmware derivatives, but usually they keep up with the naming scheme introduced by ATMEL:
.SS APs with INTERSIL radios
-For APs with INTERSIL radios, the AP firmware file typically uses naming scheme such as "1.4x.y.rom" (for example "1.4j.1.rom", "1.4k.2.rom", etc.), while the WA firmware files typically exist under names such as "0.01.ab.rom" (for example "0.01.09.rom", "0.01.11.rom", etc.). The values x, y, ab, and the letter x change according to firmware revision.
+For APs with INTERSIL radios, the AP firmware file typically uses naming scheme such as "1.4x.y.rom" (for example "1.4j.1.rom", "1.4k.2.rom", etc.), while the WA firmware files typically exist under names such as "0.01.ab.rom" (for example "0.01.09.rom", "0.01.11.rom", etc.). The values "x", "y", and "ab" indicate the firmware revision.
.SS APs with RFMD radios
-For APs with RFMD radios, the AP firmware files are known under names like "0.2.x.yz.rom" (such as "0.2.2.11.rom", "0.2.2.18.rom", etc.), while the WA firmware uses names as "0.3.b.c.rom" (for example "0.3.2.5.rom", "0.3.2.6.rom"). Again, the numbers change according to firmware revision.
+For APs with RFMD radios, the AP firmware files are known under names like "0.2.x.yz.rom" (such as "0.2.2.11.rom", "0.2.2.18.rom", etc.), while the WA firmware uses names as "0.3.b.c.rom" (for example "0.3.2.5.rom", "0.3.2.6.rom"), or "0.4.b.c.rom" for WA+ firmware (which is a variant of WA firmware that offers limited multiple MACs transparency in client mode) - for example "0.4.2.7.rom". Again, the numbers change according to the firmware revision.
To descend in even greater complexity, there usually exist 2 files for each firmware revision in the ATMEL+RFMD world: one so-called
-.B primary
-firmware (the bigger file of the two; it contains base firmware as well as the embedded webserver), and a second file with so-called
-.B backup
-firmware (the smaller file of the two, it contains just the base firmware).
-The name of secondary firmware always uses '0' in the third number field.
-.B You'll always need to upgrade with
-.B backup firmware FIRST, unless manufacturer states otherwise.
+.B primary firmware
+(the bigger file of the two; it contains base firmware as well as the embedded webserver), and a second file with so-called
+.B backup firmware
+(the smaller file of the two, it contains just the base firmware).
+The name of secondary firmware always uses '0' in the third number field (such as "0.2.0.18.rom").
+.B You'll always need to upgrade with backup firmware FIRST, unless its manufacturer states otherwise.
.TP
.RE 4
.B WARNING!!! WARNING!!! WARNING!!! WARNING!!! WARNING!!!
.RS 4
.IP o 3
-.B WA
-firmwares
+.B WA firmwares
+and their derivatives
.B ARE _NOT_ SUPPORTED
by ap-utils!!! They may appear to partially work with ap-utils, but you
can cause harm to your AP if you use ap-config with such firmware. Do not
(for example, firmware "1.4j.1.rom" exists in many incarnations, but their content differs). They may use different structures and offsets for reading configuration data in the flash memory without content validity checks, so
.B NEVER EVER USE FIRMWARE FROM ANOTHER HARDWARE VENDOR THAN THE ONE THAT IS MANUFACTURING YOUR AP, UNLESS EXPLICITLY STATED OTHERWISE! IF YOU DO SO, YOU MAY IRREVERSIBLY DAMAGE YOUR AP!
.IP o
+BEWARE! AP boards from several vendors may contain hardware design bugs, that will totally prevent it from successfull upgrade.
+.B Any attempt to upgrade such device, either via TFTP or DFU utility will fail and irreversibly damage content of its flash memory! If your vendor does NOT provide ANY firmware nor tools to perform upgrade for your device, it means (unless stated otherwise), that IT IS UNSAFE TO TRY UPGRADING and YOU SHOULD NOT ATTEMPT TO UPGRADE YOUR DEVICE AT ALL!
+Example of such board with bug in hardware design is Tellus A13 (also sold as i-Tec AP GOLD with blue front).
+.IP o
ATMEL AT76C510-based APs are notoriously known for their firmware upgrade design flaw: firmware validation checks and subsequent permission for upgrade are not performed by the AP itself, but in the TFTP upgrade client. This means that anyone with proper TFTP client, having access to your AP via its ethernet port, may _try_ to upload incorrect firmware (or even no-firmware file!) to your AP, causing irreversible damage to your AP. Hence:
.RS 3
.IP \- 3
.RE 1
.RS 4
.IP o 3
-.B Users of ATMEL+RFMD APs:
+.B Users of ATMEL+INTERSIL devices:
+If your AP firmware vendor extensions are auto-detected as
+.B SBRIDGES
+by ap-config, it means that your AP uses firmware made by smartBridges PTE: you will need to pass extra '-c community' to ap-tftp in order to perform actual upgrade.
+.B BY ALL MEANS, AVOID UPGRADE OF DEVICE THAT CONTAINS smartBridges FIRMWARE, with non-smartBridges FIRMWARE, AND VICE VERSA, even if the firmware names may look similar (see the warning above).
+Although there are checks in ap-tftp, that should avoid something such, be careful, and DO NOT TRY, UNDER ANY CIRCUMSTANCES, to circumvent this protection - if you do, you'd most likely end up with damaged flash content in your device. You got the warning.
+.TP
+.BR
+Remember: All firmware files with revision "1.4j.4" onwards are from smartBridges: unless you possess a device that is autodetected with 'SBRIDGES' vendor extension, DO NOT TRY TO UPGRADE TO smartBridges FIRMWARE!
+.IP o 3
+.B Users of ATMEL+RFMD devices:
If you are running
.B primary
firmware < 0.2.2.20, you
.B ap-tftp
will show an error code returned by the TFTP server in AP. Note that although RFC 1350 defines 8 TFTP error messages, the TFTP server in the AP is not compliant to this RFC and the error codes returned may NOT correspond to those messages (but ap-tftp will always display corresponding RFC-defined error message, if possible, although it may really have nothing to do with the returned error code meaning). In the case the message for error code returned is not defined in RFC 1350, just the error code alone will be displayed.
.IP \-
-If you want to upgrade firmware in an AP on a network where no DHCP server is available, it is advisable to assign static IP address and disable DHCP option on the device, so that you can verify, whether it is alive, using 'ping' command immediately after the upgrade succeeds, and you dont have to wait until AP's attempts to contact DHCP server time out. This is also especially useful if you need to do 2-step upgrade (using 'backup' and 'primary' firmware) - see above.
+If you want to upgrade firmware in an AP on a network where no DHCP server is available, it is advisable to assign static IP address and disable DHCP option on the device, so that you can verify, whether it is alive, using 'ping' command immediately after the upgrade succeeds (generally immediately after the device boots up), and you dont have to wait until AP's attempts to contact DHCP server time out. This is also especially useful if you need to do 2-step upgrade (using 'backup' and 'primary' firmware) - see above.
.IP \-
Firmware of APs based on ATMEL AT76C510 provides an interresting 'arp ping' feature. After AP boot-up, it is possible to remotely and TEMPORARILY (to next AP reboot) reconfigure its IP address, provided that within certain time period (several tens of seconds after boot-up), the AP receives ICMP ECHO request with target MAC address equal to its own. To set up IP in the AP using this method, do the following:
.RS 3
.IP 1\. 4
From the IP range your AP is connected to, pick up an unused IP you want to set on the AP using 'arp ping'.
.IP 2\.
-Set up static ARP entry associating the MAC address of your AP with the IP you selected in paragraph 1. Typically, you need to issue (as root) something like: 'arp -s required_AP_IP AP_MAC'. Consult manpage for 'arp' utility if this differs for you.
+Set up static ARP entry associating the MAC address of your AP with the IP you selected in paragraph 1. Typically, you need to issue (as root) something like: 'arp -s required_AP_IP AP_MAC'. Consult manpage for 'arp' utility, if your 'arp' utility uses different syntax.
.IP 3\.
Right after the AP boots, run 'ping required_AP_IP'. You need to wait few seconds prior seeing first AP response.
.RE 1
.RS 4
.IP \- 3
-.B Users of ATMEL+RFMD APs:
+.B Users of ATMEL+RFMD devices:
To
.B DOWNGRADE
to
.B AP
-firmware with lower number than the one thats currently in the device, you'll need to temporarily 'upgrade' to any
+firmware with lower revision number than the one thats currently in the device, you'll need to temporarily 'upgrade' to any
.B WA
-firmware available for your AP (as step-in-the-middle). This will 'unlock' your device for downgrading to previous
+firmware available for your device (as step-in-the-middle). This will 'unlock' your device for downgrading to previous
.B AP
firmware version.
.SH OPTIONS
.TP
-.B -l firmware.rom
+.B -i IP
+IP address of the AP you want upgrade firmware in.
+.TP
+.B -f firmware.rom
Full path to and name of the firmware file for your AP.
.TP
-.B IP
-IP address of the AP you want upgrade firmware in.
+.B -c community
+To be used ONLY with APs manufactured by smartBridges PTE. The given community
+must match with any of three three communities currently defined in the AP
+configuration - firmware upgrade will be allowed only upon the match.
+matches
.RE
.SH EXAMPLES OF USE
.PD 0
-.SS Upgrading "AP" firmware in AP with INTERSIL radio:
+.SS Upgrading AP firmware in a device with INTERSIL radio and non-smartBridges firmware
.BR
.TP
-ap-tftp -l 1.4j.3.rom 192.168.0.1
+ap-tftp -i 192.168.0.1 -f 1.4j.3.rom
-.SS Upgrading "AP" firmware in AP with RFMD radio:
+.SS Upgrading AP firmware in a device with INTERSIL radio and smartBridges firmware
.BR
.TP
-ap-tftp -l 0.2.0.20.rom 192.168.1.100
+ap-tftp -i 192.168.0.24 -f 1.4k.5.rom -c private
+
+.SS Upgrading AP firmware in a device with RFMD radio:
+.BR
+.TP
+ap-tftp -i 192.168.1.100 -f 0.2.0.20.rom
.TP
-ap-tftp -l 0.2.2.20.rom 192.168.1.100
+ap-tftp -i 192.168.1.100 -f 0.2.2.20.rom
-.SS Downgrading "AP" firmware in AP with RFMD radio:
+.SS Downgrading AP firmware in a device with RFMD radio:
.BR
.TP
-ap-tftp -l 0.3.0.6.rom 192.168.1.100
+ap-tftp -i 192.168.1.100 -f 0.3.0.6.rom
.TP
-ap-tftp -l 0.3.2.6.rom 192.168.1.100
+ap-tftp -i 192.168.1.100 -f 0.3.2.6.rom
.TP
-ap-tftp -l 0.2.0.19.rom 192.168.1.100
+ap-tftp -i 192.168.1.100 -f 0.2.0.19.rom
.TP
-ap-tftp -l 0.2.2.19.rom 192.168.1.100
+ap-tftp -i 192.168.1.100 -f 0.2.2.19.rom
+
+.SH KNOWN BUGS
+This utility has not been verified on and will probably not work on big-endian architectures. Its use is discouraged in such environment.
.SH AUTHOR
Jan Rafaj <jr-aputils at cedric dot unob dot cz>
projects / ap-utils.git / blobdiff