NAME

SYNOPSIS

ap-tftp-iIP-ffirmware.rom[-ccommunity]

DESCRIPTION

The ap-tftp 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.

PREFACE:FIRMWARETYPES

Functionally, there basically exist 2 types of firmware for ATMEL-based APs: an " AccessPoint firmware (often referred to as APfirmware ), and WirelessAdapter firmware
(referred to as WAfirmware ). Many hardware vendors produce their own more or less
modified firmware derivatives, but usually they keep up with the naming scheme introduced
by ATMEL:
APswithINTERSILradios
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.
APswithRFMDradios
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 primaryfirmware (the bigger file of the
two; it contains base firmware as well as the embedded webserver), and a second file with
so-called backupfirmware (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"). You'llalwaysneedtoupgradewithbackupfirmwareFIRST,unlessitsmanufacturerstatesotherwise.WARNING!!!WARNING!!!WARNING!!!WARNING!!!WARNING!!!
o WAfirmwares and their derivatives 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 complain if you use ap-config with such
firmware and it damages your AP!
o Since some hardware vendors keep up the bad habit of producing their own firmwares
using the original ATMEL firmware naming scheme, it is easy to find firmwares from
different hardware vendors for ATMEL-based APs with exactlythesamenameandsometimeseventhelength (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 NEVEREVERUSEFIRMWAREFROMANOTHERHARDWAREVENDORTHANTHEONETHATISMANUFACTURINGYOURAP,UNLESSEXPLICITLYSTATEDOTHERWISE!IFYOUDOSO,YOUMAYIRREVERSIBLYDAMAGEYOURAP!
o BEWARE! AP boards from several vendors may contain hardware design bugs, that will
totally prevent it from successfull upgrade. Anyattempttoupgradesuchdevice,eitherviaTFTPorDFUutilitywillfailandirreversiblydamagecontentofitsflashmemory!IfyourvendordoesNOTprovideANYfirmwarenortoolstoperformupgradeforyourdevice,itmeans(unlessstatedotherwise),thatITISUNSAFETOTRYUPGRADINGandYOUSHOULDNOTATTEMPTTOUPGRADEYOURDEVICEATALL! Example of
such board with bug in hardware design is Tellus A13 (also sold as i-Tec AP GOLD
with blue front).
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:
- SECUREYOURAPONIP(LAYER3)BASIS!SETUPYOURAP(ANDITSWIRELESSCLIENTS)WITHIPFROMADIFFERENTIPSEGMENTTHANTHEONEITISPHYSICALLYON.TOACCESSAPONSUCHDIFFERENTSEGMENT,YOUMAYUSEIP-ALIASINTERFACE(onLinux).
- FORAPsINAccessPointclientMODE,USEap-configANDIN'Config->Bridge'MENU,CHANGETHEVALUEOF'Configuration-enabledport(s):'TO'Wireless'.THISWAY,USERBEHINDAccessPointclientDEVICEWONTBEABLETOREACHITSMANAGEMENTIP,ANDSUBSEQUENTLY(S)HEWONTBEABLETOCAUSEANYDAMAGEWITHTFTP. Note
that setting Conf.-enabled port to 'Wireless' may be risky if you intend to
reconfigure the device through Wireless media (bad values could be written to
the AP due to wireless media unreliability). You should choose what is of
greater risk for you.
o UsersofATMEL+INTERSILdevices: If your AP firmware vendor extensions are auto-
detected as 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. BYALLMEANS,AVOIDUPGRADEOFDEVICETHATCONTAINSsmartBridgesFIRMWARE,withnon-smartBridgesFIRMWARE,ANDVICEVERSA,evenifthefirmwarenamesmaylooksimilar(seethewarningabove). 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.
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!
o UsersofATMEL+RFMDdevices: If you are running primary firmware < 0.2.2.20, you
shouldupgradeassoonaspossible!AP firmware of version 0.2.2.19 and lower
contains serious 'death by reconfiguration' bug, which, if triggered, may
irreversibly damage content in flash memory of your AP. The event to trigger is
usually changing & writing some settings in the 'Bridge' menu. So if you run such
firmware, please upgrade. You may also look into README to see whether 'Firmware
available free of charge for ATMEL12350 MIB devices' (section) applies to your AP.
GENERALHINTSANDRECOMMENDATIONSPRIORUPGRADING
- IF POSSIBLE, PLACE YOUR AP BEHIND A FIREWALL SO THAT YOU PREVENT ACCESS TO ITS
MANAGEMENT IP FOR UNWANTED THIRD PARTIES
- Avoid upgrading your AP via its wireless port, if possible. Due to the unreliable
nature of wireless media and UDP protocol used for upgrade, anything could happen -
although there is CRC-like check in the firmware, that prevents flashing of
(firmware) file that has possibly been altered during transmission, upgrade process
interruption might cause damage (but even this is not very likely). You may upgrade
AP via its wireless port only if you're 101% sure the wireless connection to the
target device is reliable.
- If you experience upgrade timeout in the 'middle' of the upgrade progress, it is
usually ok to wait until the utility completely times out, and repeat the command
afterwards. You may also experience 'catch up' (very short network break, so
utility will resume uploading firmware to your AP).
- In case when firmware upgrade fails, 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.
- 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.
- 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:
1. From the IP range your AP is connected to, pick up an unused IP you want to set
on the AP using 'arp ping'.
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 your
'arp' utility uses different syntax.
3. Right after the AP boots, run 'ping required_AP_IP'. You need to wait few
seconds prior seeing first AP response.
- UsersofATMEL+RFMDdevices: To DOWNGRADE to AP firmware with lower revision number
than the one thats currently in the device, you'll need to temporarily 'upgrade' to
any WA firmware available for your device (as step-in-the-middle). This will
'unlock' your device for downgrading to previous AP firmware version.

OPTIONS

-iIP IP address of the AP you want upgrade firmware in.
-ffirmware.rom
Full path to and name of the firmware file for your AP.
-ccommunity
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