ap-tftp(8)

📦 version 1.5, in debian bookworm, ubuntu jammy, ubuntu noble

💖 ap-tftp — the manual, part 1 ✨

okay bestie, pull up a chair because we're about to talk about ap-tftp, from the System Manager's Manual (section 8, if you're keeping score 🎀).

🌸 NAME 🌸

ap-tftp — a TFTP client for upgrading ATMEL AT76C510 WiSOC-based APs 💅

and like, real talk? Please read the entire manpage prior using this utility. It may prevent you from problems arising later. I'm not being dramatic, I'm being accurate. 🫶

✨ SYNOPSIS ✨

ap-tftp -i IP -f firmware.rom [-c community ]

that's it, that's the whole vibe. two required flags, one optional one, go off 👑

🦋 DESCRIPTION 🦋

so. ap-tftp is the utility you use to upgrade or downgrade firmware in Access Points based on the ATMEL AT76C510 VNET-B WiSOC (that's a Wireless System On Chip, iykyk 🧚).

It should work for most (if not all) models with an INTERSIL radio chipset, plus the ones based on RFMD radio. It's giving "universal, lowkey". 😌

but — and I need you to hear me on this — so far it has only been tested on the following hardware:

  • WLink WEN-2021 🌈
  • i-Tec AP GOLD ⭐
  • smartBridges airPOINT PRO 💜

(all three of those are running INTERSIL radio, bestie 💖)

  • Tellus A14 🎀

(and that one's the RFMD radio rep, we love an inclusive lineup ✨)

so 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. no cap. 🔥

more parts coming, don't go anywhere 👀💖

🎀 PREFACE: FIRMWARE TYPES 🎀

okay bestie, before we even think about flashing anything, we need a little firmware lore drop, because this is the part where people brick their APs and cry about it 😭

So functionally? There are basically 2 kinds of firmware for ATMEL-based APs:

  • Access Point firmware — aka "AP firmware", the classic 💅
  • Wireless Adapter firmware — aka "WA firmware"

A bunch of hardware vendors make their own more-or-less-modified little remixes of these, but bestie, they usually keep the naming scheme ATMEL came up with. so like, at least the names stay recognizable. ✨

🌸 APs with INTERSIL radios 🌸

If your AP has INTERSIL radios, the AP firmware file is typically named like 1.4x.y.rom — think 1.4j.1.rom, 1.4k.2.rom, etc. Meanwhile the WA firmware files usually live under names like 0.01.ab.rom — for example 0.01.09.rom, 0.01.11.rom, etc. The x, y, and ab bits are literally just the firmware revision. That's it, that's the code 🦋

🌈 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 like 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. And again, the numbers shift around according to the firmware revision. no cap.

And because the universe loves chaos, it gets even more complicated: in the ATMEL+RFMD world there are usually 2 files for every single firmware revision:

  • the so-called primary firmware — the bigger file of the two; it contains the base firmware plus the embedded webserver
  • the so-called 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 (like 0.2.0.18.rom). And you'll always need to upgrade with the backup firmware FIRST, unless the manufacturer says otherwise. That's not a vibe, that's a rule 🫶

WARNING!!! WARNING!!! WARNING!!! WARNING!!! WARNING!!!
  • WA firmwares and their derivatives ARE _NOT_ SUPPORTED by ap-utils!!! They may appear to partially work with ap-utils, but bestie, 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! 💀
  • 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 exactly the same name — and sometimes even the same length. (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 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! 😭
  • BEWARE! AP boards from several vendors may contain hardware design bugs that will totally prevent a successful upgrade. Any attempt to upgrade such a device — whether via TFTP or the DFU utility — will fail and irreversibly damage the content of its flash memory! If your vendor does NOT provide ANY firmware nor tools to perform an 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! An example of such a board with a bug in its hardware design is the Tellus A13 (also sold as the i-Tec AP GOLD with blue front).
  • ATMEL AT76C510-based APs are notoriously known for their firmware upgrade design flaw: the firmware validation checks and the subsequent permission for upgrade are not performed by the AP itself, but in the TFTP upgrade client. Which means literally anyone with a proper TFTP client, having access to your AP via its ethernet port, may try to upload incorrect firmware (or even a no-firmware file!) to your AP, causing irreversible damage to your AP. Hence:
    • SECURE YOUR AP ON IP (LAYER 3) BASIS! SET UP YOUR AP (AND ITS WIRELESS CLIENTS) WITH IP FROM A DIFFERENT IP SEGMENT THAN THE ONE IT IS PHYSICALLY ON. To access the AP on such a different segment, you may use an IP-alias interface (on Linux).
    • FOR APs IN Access Point client MODE, USE ap-config AND IN Config -> Bridge MENU, CHANGE THE VALUE OF Configuration-enabled port(s): TO Wireless. This way, a user behind the Access Point client device WON'T be able to reach its management IP, and subsequently (s)he won't be able to cause any damage with TFTP. Note that setting Conf.-enabled port to Wireless may be risky if you intend to reconfigure the device through the 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. 🙈
  • Users of ATMEL+INTERSIL devices: if your AP firmware vendor extensions are auto-detected as SBRIDGES by ap-config, it means your AP uses firmware made by smartBridges PTE — and you will need to pass an extra -c community to ap-tftp in order to perform the actual upgrade. BY ALL MEANS, AVOID UPGRADE OF A 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 like that, 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!

  • Users of ATMEL+RFMD devices: if you are running primary firmware < 0.2.2.20, you should upgrade as soon as possible! AP firmware of version 0.2.2.19 and lower contains a serious 'death by reconfiguration' bug which, if triggered, may irreversibly damage the content in the flash memory of your AP. The event that triggers it 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.

💜 GENERAL HINTS AND RECOMMENDATIONS PRIOR UPGRADING 💜

  • 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 the UDP protocol used for the upgrade, anything could happen — although there is a CRC-like check in the firmware that prevents flashing of a (firmware) file that has possibly been altered during transmission, an upgrade process interruption might cause damage (but even this is not very likely). You may upgrade the AP via its wireless port only if you're 101% sure the wireless connection to the target device is reliable.
  • If you experience an 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' (a very short network break, so the utility will resume uploading firmware to your AP).
  • In the case when a firmware upgrade fails, ap-tftp will show an error code returned by the TFTP server in the 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 the corresponding RFC-defined error message, if possible, although it may really have nothing to do with the returned error code's meaning). In the case the message for the returned error code 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 a static IP address and disable the DHCP option on the device, so that you can verify whether it is alive using the 'ping' command immediately after the upgrade succeeds (generally immediately after the device boots up), and you don't have to wait until the AP's attempts to contact the DHCP server time out. This is also especially useful if you need to do a 2-step upgrade (using 'backup' and 'primary' firmware) — see above. 👑
  • Firmware of APs based on ATMEL AT76C510 provides an interesting 'arp ping' feature. After AP boot-up, it is possible to remotely and TEMPORARILY (until the next AP reboot) reconfigure its IP address — provided that within a certain time period (several tens of seconds after boot-up) the AP receives an ICMP ECHO request with a target MAC address equal to its own. To set up the 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 a 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 the manpage for the 'arp' utility if your 'arp' utility uses a different syntax.
    3. Right after the AP boots, run 'ping required_AP_IP'. You need to wait a few seconds prior to seeing the first AP response. 🦋
  • Users of ATMEL+RFMD devices: to DOWNGRADE to AP firmware with a lower revision number than the one that's currently in the device, you'll need to temporarily 'upgrade' to any WA firmware available for your device (as a step-in-the-middle). This will 'unlock' your device for downgrading to a previous AP firmware version. ✨

✨ OPTIONS ✨

  • -i IP — the IP address of the AP you want to upgrade firmware in. 📍
  • -f firmware.rom — the full path to, and the name of, the firmware file for your AP. 🎀
  • -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

🌈 EXAMPLES OF USE ✨

Okay bestie, this is the part where it all clicks. Real commands, real vibes. Let's go 🫶

🌸 Upgrading AP firmware in a device with INTERSIL radio and non-smartBridges firmware

ap-tftp -i 192.168.0.1 -f 1.4j.3.rom

💖 Upgrading AP firmware in a device with INTERSIL radio and smartBridges firmware

ap-tftp -i 192.168.0.24 -f 1.4k.5.rom -c private

🦋 Upgrading AP firmware in a device with RFMD radio

ap-tftp -i 192.168.1.100 -f 0.2.0.20.rom
ap-tftp -i 192.168.1.100 -f 0.2.2.20.rom

🙈 Downgrading AP firmware in a device with RFMD radio

ap-tftp -i 192.168.1.100 -f 0.3.0.6.rom
ap-tftp -i 192.168.1.100 -f 0.3.2.6.rom
ap-tftp -i 192.168.1.100 -f 0.2.0.19.rom
ap-tftp -i 192.168.1.100 -f 0.2.2.19.rom

💀 KNOWN BUGS

Not everything is slay, and we gotta be honest about it. This utility has not been verified on — and will probably not work on — big-endian architectures. Like, it's just not it. Its use is discouraged in such an environment. No cap. 😭

👑 AUTHOR

Jan Rafaj <jr-aputils at cedric dot unob dot cz>

http://ap-utils.polesye.net

Absolute legend behavior, honestly. 💅

🎀 SEE ALSO

Go read these next, they're all part of the same friend group:

And that's the whole page, bestie! 🥳 This little icon comes from Wireless Access Point Utilites for Unix, and the page itself is ap-tftp(8) — mwah, periodt. 🦋💖✨

📦 where this page comes from