amptool(1)

🎀 amptool(1), but make it bestie 🎀

Okay bestie, this is the amptool(1) manual, and I'm about to make it actually readable 💅 This is the part 1 of 2, so more is coming 🫶

✨ NAME ✨

amptool - Qualcomm Atheros AR7x00 Powerline Device Manager 🔌

💅 SYNOPSIS 💅

amptool [options] [device] [device] [...]

🦋 DESCRIPTION 🦋

Okay so this version of the Qualcomm Atheros Device Manager for Linux does the basic stuff on Atheros AR7400 devices. It talks over the raw Ethernet protocol described in the Qualcomm Atheros HomePlug AV Firmware Technical Reference Manual. You can interrogate and control devices, or upgrade firmware if on-board NVRAM is present 💖

This program is part of the Qualcomm Atheros Powerline Toolkit. It supports chipset AR7400 and QCA7450. For QCA6410, QCA7000 and QCA7420 devices, see plctool instead. For the overview and installation instructions, check the plc man page 🌸

🌸 COMMENTS 🌸

Real talk, this program version is identical to the legacy int6k program, except for option -m. That one uses version 1 of the Qualcomm Atheros VS_NW_INFO vendor-specific message. Older firmware versions may not recognize this message version 🙈

👑 OPTIONS 👑

Here's every single option, no skipping, bestie 🫶

• -a — Pull device attributes using VS_OP_ATTRIBUTES. Attributes are short strings and integers that describe the hardware and firmware 🧚 They get stitched together into output that's kinda like -r, but it's worked out a different way.
• -B action — Press the simple connect pushbutton using VS_PB_ENC. You can give the action as a number or a symbol: 1 is join, 2 is leave, 3 is status, and 4 is reset. Use 1 on both devices that are supposed to join. Only use 2 on the device that's expected to leave the network 🚪
• -C module — Commit (flash) downloaded modules to NVRAM using VS_MOD_NVM. The module can be 1, 2 or 3, or the symbols nvm, pib or all. So 1 is nvm, 2 is pib, and 3 is all. Module 3 is equivalent to -F, which writes the NVM and PIB together. You cannot force-flash NVRAM with this one. For that, use -FF 💀
• -d filename — Read the Watchdog Report from the device and write it to the named file in binary format using VS_WD_RPT. The report file can be sent to Qualcomm Atheros for technical analysis. No assumptions are made based on the filename and no filename conventions are enforced. Still, you should use a .log extension to show it's binary 📝
• -D xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx — Define the 16 octet Device Access Key (DAK) in hex format. The DAK is used by -J. It can also be set to key1 or key2, as explained in the KEYS section 🔑
• -e — Redirects stderr messages to stdout. By convention, status and error messages go to stderr, while the main program output goes to stdout. This option sends everything to stdout for when that's what you want 📤
• -f — Read flash memory parameters using VS_GET_NVM. You'll get an error if no flash memory is present 😭
• -F[F] — Write the previously downloaded MAC and PIB to NVRAM using VS_MOD_NVM. Add a second F here, or another -F anywhere on the command line, to force-flash a blank or corrupted NVRAM. Firmware loaded from NVRAM will treat force-flash as an error. This option can make factory settings, but it can't change them once they exist. Later use creates and updates operational settings, which can be erased with a factory reset ✨ This option runs after all the others on the command line, except for -R.
• -i interface — Select the host Ethernet interface. All requests go out through this host interface, and only responses received through it get recognized. The default is eth1, because most people use eth0 as their main network connection. If the environment string PLC is defined, it takes precedence over the default. This option takes precedence over either one 🌈
• -I — Read the device PIB header using VS_RD_MOD. It prints the firmware major revision number, PIB minor revision number, Device Access Key (DAK), Network Membership Key (NMK), MAC address and other info on stdout. The values displayed can be changed using the program modpib.
• -J xx:xx:xx:xx:xx:xx — Set the Network Membership Key (NMK) on a remote device using VS_SET_KEY. This is similar to -K, but it needs the remote device MAC and DAK on top of the NMK and local device MAC address. The NMK comes from -K unless you want the default value. The remote DAK comes from -D unless you want the default value. Remote device keys are complicated 🙃 It's often easier to connect the device directly to the host and use -K.
• -K xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx — Define the Network Membership Key (NMK) value used by -M or -J. The symbolic names key1 and key2 are recognized, as described in the KEY section 🗝️
• -l count — Define how many times the command repeats for each device specified. Normally you'll only repeat operations on one device 🔁
• -m — Read network membership info using VS_NW_INFO. This can be used to figure out the network configuration 🕸️
• -M — Set the Network Membership Key (NMK) on the local device using VS_SET_KEY. The NMK value comes from -K unless you want the default value.
• -n filename — Read firmware from the device SDRAM and write it to the named .nvm file using multiple VS_RD_MOD messages. No assumptions are made based on the filename and no filename conventions are enforced. This runs before -N when both are specified.
• -N filename — Read the named .nvm file and write it to the device using multiple VS_WR_MOD messages. No assumptions are made based on the filename and no filename conventions are enforced. Files with invalid .nvm format will be rejected 🚫 This runs after -n when both are specified.
• -p filename — Read parameters from the device SDRAM and write them to the named .pib file using multiple VS_RD_MOD messages. No assumptions are made based on the filename and no filename conventions are enforced. This runs before BP when both are specified.
• -P filename — Read the named .pib file and write it to the device using multiple VS_WR_MOD messages. No assumptions are made based on the filename and no filename conventions are enforced. Files with invalid .pib format will be rejected 🚫 This runs after -p when both are specified.
• -q — Suppresses status messages on stderr 🤫
• -Q — Quick flash ⚡ The program won't wait for a device to reset or the firmware to restart after writing flash memory. This is desirable with newer firmware that writes flash memory in the background. It has no effect unless used with -F or -C.
• -r — Read device firmware and hardware revision using VS_SW_VER. The output is similar to -a, but it's derived differently.
• -R — Reset the device using VS_RS_DEV. This runs after all the others on the same command line 🔄
• -s — Read device SDRAM configuration using VS_RD_CBLOCK.
• -t milliseconds — Read timeout in milliseconds ⏱️ Values range from 0 through UINT_MAX. This is the maximum time allowed for a response. The default is shown in brackets on the program menu.
• -T — Restore factory defaults.

💀 Heads up, bestie: this permanently erases all PIB changes made since the device was last programmed with factory default settings. The device will automatically reset and reboot.

• -v — Print additional info on stdout 📜 This option dumps incoming and outgoing packets, which can be saved as text files for reference.
• -w seconds — Defines how many seconds to wait before repeating the command line options ⏳ This has no effect unless -l is also specified with a non-zero value.
• -x — Make the program exit on the first error, instead of pushing on with the remaining iterations, operations or devices 🛑 Normally the program reports errors and moves on to the next operation, iteration or device, depending on the command line.
• -?,--help — Print the program help summary on stdout 🆘 This option takes precedence over other options on the command line.
• -?,--version — Print program version information on stdout 🎀 This option takes precedence over other options on the command line. Use it when sending screen dumps to Atheros Technical Support, so they know exactly which version of the Linux Toolkit you're using.

✨ DEVICES ✨

Okay so powerline devices are identified by their Ethernet hardware addresses, aka MAC addresses 🫶. A device address is 12 hexadecimal digits (0123456789ABCDEFabcdef), and you can type them in upper, lower, or mixed case. It's giving flexibility 💅 Colons are optional for clarity, and not every octet has to be separated, so all of these are valid and equivalent: 00b052000001, 00:b0:52:00:00:01 and 00b052:000001 🦋

You can also use symbolic addresses instead of typing out the real value, and this program recognizes them ✨

• all — Same thing as broadcast, which is next 💖
• broadcast — This is the standard Ethernet broadcast address, FF:FF:FF:FF:FF:FF. Every device responds to it, whether it's local, remote, or foreign 📡
• local — This is the Qualcomm Atheros vendor specific Local Management Address (LMA), 00:B0:52:00:00:01. All local Atheros devices recognize it, but remote and foreign devices don't 🌸 A remote device is any device at the far end of a powerline connection. A foreign device is any device not manufactured by Atheros.

📚 REFERENCES 📚

For more info, check out the Qualcomm Atheros HomePlug AV Firmware Technical Reference Manual 🤓📖

🚨 DISCLAIMER 🚨

Okay, serious moment bestie 😭 The Atheros HomePlug AV Vendor Specific Management Message structure and content is proprietary to Qualcomm Atheros, Ocala FL USA. That means public info may not be available. Qualcomm Atheros reserves the right to modify message structure or content in future firmware releases, without any obligation to notify or compensate users of this program 💀

🎀 EXAMPLES 🎀

Let's do the examples 🧚

# amptool -n old.nvm -p old.pib -N new.nvm -P new.pib -F 01:23:45:67:89:AB

This one does 5 operations on one device 👑 It uploads the firmware and PIB from the device and writes them to the files old.nvm and old.pib, respectively. Then it reads new.nvm and new.pib and downloads them as new firmware and PIB, respectively. Last, it commits the downloaded firmware and PIB to NVRAM. The operations always run in the order I just described, no matter what order you type them on the command line. If you want reading and writing in a different order, you need two or more commands to get the tasks done in the order you want 💅

# amptool -N new.nvm 01:23:45:67:89:28
# amptool -P new.pib 01:23:45:67:89:28
# amptool -C 3 01:23:45:67:89:28

You don't have to cram every operation onto one command line, and these three lines do basically the same thing as the previous example 🫶 Notice this one uses -C 3 instead of -F as another way to write the MAC and PIB to NVRAM. -C 1 would write the .nvm file only, and -C 2 would write the .pib file only. The value 3 is the logical OR of 1 and 2 🧠

# amptool -N new.nvm -P new.pib -FF local

This downloads new.nvm and new.pib, then force flashes the local device 🔥 Force flashing only works on running firmware that has been downloaded and started by the Qualcomm Atheros Boot Loader. If you want to download, start firmware, and force flash in one go, check out amptoolf 🌈

# amptool -MK key1
# amptool -M

These two commands are equivalent 🔑 Both set the NMK on the local device to key1, as described in the KEYS section. The first one resets the NMK on the local device with -M, then specifies the NMK as key1. The second one skips the key specification because key1 is the program's default NMK. Of course, you could also just type out the encryption key yourself 💜

🔗 SEE ALSO 🔗

plc(1), ampboot(1), ampboot(1), amphost(1), int6kid(1), amprate(1), amprule(1), ampstat(1), ampwait(1) 🦋

💖 CREDITS 💖

Huge shoutout to Charles Maier and Nathaniel Houghton 🫶✨

Okay bestie, that's the whole page 💅 It's from open-plc-utils version 0.0.3, last updated November 2013. Iykyk 🌸