plctool(1)

okay bestie, welcome to plctool(1) from the Qualcomm Atheros Open Powerline Toolkit ✨ this is the part where you learn to boss around your powerline adapters, and honestly? iconic.

🎀 NAME 🎀

plctool — Qualcomm Atheros Panther/Lynx Powerline Device Manager 🦋

---

🌸 SYNOPSIS 🌸

plctool [options] [device] [device] [...]

---

💅 DESCRIPTION 💅

This version of the Qualcomm Atheros Powerline Device Manager does the basic-operation thing on powerline devices using vendor-specific management messages. You can interrogate devices, control them, or upgrade firmware if on-board NVRAM is present. Lowkey a whole multitool. Also, go peek at amptool — it's the sibling utility that supports AR7400 devices. The chipsets this one rides for are QCA6410, QCA7000 and QCA7420. 💖

This program is the proper tool for upgrading panther/lynx devices, no cap. Two things you need to internalize:

• It is important to reset panther/lynx devices after update, since reset after update is not automatic anymore. Not me forgetting to reset and then being confused — don't be that girl. 😭
• Everything takes longer because part memory is erased before being written. Some operations may take 20 to 40 seconds, so be patient. fr fr, this is the moment to go refill your water. 🍓

This program is part of the Qualcomm Atheros Powerline Toolkit. See the plc man page for an overview and installation instructions. 🫶

---

🗒️ COMMENTS 🗒️

This program version is identical to legacy program int6k except for option -m, which uses version 1 of the Qualcomm Atheros VS_NW_INFO vendor-specific message. Heads up: older firmware versions may not recognize this message version. 👑

---

✨ OPTIONS ✨

• -a — Read device attributes using VS_OP_ATTRIBUTES. Attributes are short strings and integers that describe device hardware and firmware. They get concatenated to form the output, which is similar to option -r but derived differently. Same vibe, different origin story. 💫
• -B action — Press the simple connect pushbutton using VS_PB_ENC. The action can be specified by number 1, 2, 3 or 4, or by symbol "join", "leave", "status" or "reset", respectively. Use 1 on both devices that are expected to join. Use 2 only on the device that is expected to leave the network. Bye bestie 👋
• -d filename — Read 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 filename and no filename convetions are enforced; however, you should use a .log file extension to indicate binary format. 🩺
• -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 option -J. It may also be set to "key1" or "key2" as explained in the KEYS section. 🔑
• -e — Redirects stderr messages to stdout. Normally, status and error messages are printed on stderr while primary program output is printed on stdout. This option prints all output on stdout in cases where this is desired. Everything in one stream, one girl, one timeline. 🌈
• -f — Read flash memory parameters using VS_GET_NVM. An error will be reported if no flash memory is present. 💀
• -F[F] — Write previously downloaded MAC and PIB to NVRAM using VS_MOD_NVM. Adding a second F here or another -F anywhere on the command line WILL NOT force-flash a blank or corrupted NVRAM as with programs int6k and amptool. Firmware loaded from NVRAM will treat force-flash as an error. This option can be used to create factory settings but cannot be used to change them once created. Subsequent use creates and updates operational settings that can be erased using a factory reset. This option is executed after all others on the command line, except for the -R option.

🚨 bestie listen — the double-F force-flash trick from int6k/amptool does not work here. The firmware loaded from NVRAM treats force-flash as an error. Do not try it. 🙈

• -i interface — Select the host Ethernet interface. All requests are sent via this host interface and only reponses received via this host interface are recognized. The default interface is eth1 because most people use eth0 as their principle network connection; however, if environment string "PLC" is defined then it takes precedence over the default interface. This option then takes precedence over either default. Precedence stack, slay. 💅
• -I — Read the device PIB header using VS_MODULE_OPERATION and print the PIB major and minor revision number, Device Access Key (DAK), Network Membership Key (NMK), MAC address and other identity information on stdout. The values displayed can be changed using program modpib. 🪪
• -J xx:xx:xx:xx:xx:xx — Set the Network Membership Key (NMK) on a remote device using VS_SET_KEY. This option is similar to option -K but requires the remote device MAC and DAK in addition to the NMK and local device MAC address. The NMK value is defined using option -K unless you want to use the default value. The remote DAK is defined using option -D unless you want to use the default value. Programming remote device keys is complicated. It is often easier to connect the device directly to the host and use the -K option. ngl, just plug it in directly. 🔌
• -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 options -M or -J. The symbolic names "key1" and "key2" are recognized as described in the KEY section. 🔐
• -l count — Define the number of times that the command will be repeated for each device specified. Normally, you will repeat operations on one device only. 🔁
• -L — Read and display powerline link status. 📡
• -m — Read network membership information using VS_NW_INFO. This can be used to determine network configuration. 🗺️
• -M — Set the Network Membership Key (NMK) on the local device using VS_SET_KEY. The NMK value is specified using the -K option unless you want to use 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 filename and no filename conventions are enforced. This option is performed before option -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 filename and no filename conventions are enforced; however, files having invalid .nvm format will be rejected. This option is executed after -n when both are specified. 📤
• -p filename — Read parameters from the device NVRAM and write them to the named .pib file using multiple VS_RD_MOD messages. No assumptions are made based on filename and no filename convetions are enforced. This option is executed before option 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 filename and no filename conventions are enforced; however, files having invalid .pib format will be rejected. This option is executed after -p when both are specified. 🗃️
• -q — Suppresses status messages on stderr. 🤫
• -Q — Quick flash. The program will not wait for a device to reset or the firmware to restart after writing flash memory. This option is desirable with newer firmware that writes flash memory in the background. It has no effect unless used with option -F or -C. ⚡
• -r — Read device firmware and hardware revision using VS_SW_VER. Output is similar to option -a but is derived differently. 🧬
• -R — Reset the device using VS_RS_DEV. This option is executed after all others on the same command line. 🔄
• -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. This permanently erases all PIB changes made since the device was last programmed with factory default settings. The device will automatically reset and reboot.

💀 PERMANENT. That's the whole point of the word permanently, bestie. It also auto-resets and reboots itself, so just let it cook.

• -v — Print additional information on stdout. In particular, this option dumps incoming and outgoing packets which can be saved as text files for reference. 🕵️‍♀️
• -w seconds — Defines the number of seconds to wait before repeating command line options. This option has no effect unless option -l is also specified with a non-zero value. 💤
• -x — Cause the program to exit on the first error instead of continuing with 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 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 this option when sending screen dumps to Atheros Technical Support so that they know exactly which version of the Linux Toolkit you are using. 📸

---

🫶 ARGUMENTS 🫶

• device — The Ethernet hardware address of some powerline device. More than one address may be specified on the command line. If more than one address is specified then operations are performed on each device in turn. The default address is local. as explained in the DEVICES section. 🏡

---

🔑 KEYS 🔑

Passwords are variable length character strings that end-users can remember. Keys are fixed length binary values created by encrypting passwords. There are two encryption algorithms for HomePlugAV. One for DAKs and the other for NMKs. This means that a given password will produce different keys depending on use. This program only deals with keys because that is what powerline devices recognize. The passwords that generated the keys are irrelevant here. Like, the password did its job and then left the chat. 💨

Encryption keys are tedious to type and prone to error. For convenience, symbolic names have been assigned to common encryption keys and are recognized by options -D and -K. Type the short cute name, not the 32-character hex novel. 🎀

key1

Key for encrypted password "HomePlugAV". This is "689F074B8B0275A2710B0B5779AD1630" for option -D and "50D3E4933F855B7040784DF815AA8DB7" for option -K.

key2

Key for encrypted password "HomePlugAV0123". This is "F084B4E8F6069FF1300C9BDB812367FF" for option -D and "B59319D7E8157BA001B018669CCEE30D" for option -K.

none

Always "00000000000000000000000000000000". ⭐

---

🌙 hold up, we are NOT done — part 2 is right there waiting for you, bestie 💖

🦋 DEVICES 🦋

okay so here's the tea: powerline devices don't have names, they have Ethernet hardware addresses — aka Media Access Control (MAC) addresses. periodt.

A device address is 12 hexadecimal digits (0123456789ABCDEFabcdef), and you can type them in upper case, lower case, or a chaotic little mix, whatever vibes. 💅 Individual octets may be separated by colons for clarity, but ngl not all octets need to be seperated. So for example, these three are all valid and literally equivalent:

00b052000001
00:b0:52:00:00:01
00b052:000001

These symbolic addresses are recognized by this program, and you can use them instead of the actual address value. slay.

---

• all — Equivalent to broadcast, which is described right below. that's it, that's the whole thing.
• broadcast — A synonym for the standard Ethernet broadcast address, FF:FF:FF:FF:FF:FF. All devices — whether local, remote or foreign — will respond to this address. everybody's invited to this party fr fr. 🎉
• local — A synonym for the Qualcomm Atheros vendor specific Local Management Address (LMA), 00:B0:52:00:00:01. All local Atheros devices will recognize this address, but remote and foreign devices will not. So real quick, bestie, the definitions:
  • 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 📚

See the Qualcomm Atheros HomePlug AV Firmware Technical Reference Manual for more information. iykyk. 📖

💀 DISCLAIMER 💀

Atheros HomePlug AV Vendor Specific Management Message structure and content is proprietary to Qualcomm Atheros, Ocala FL USA. Consequently, public information 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. no cap, read that again. 🙈

✨ EXAMPLES ✨

The following command writes QCA7000.pib and QCA7000.nvm to a remote powerline device, then resets it. The reset is required because reset after flash is no longer automatic. not optional, bestie.

# plctool -P QCA7000.pib -N QCA7000.nvm -R 00B05201053E

But wait — the previous command does not replace existing PIB values. Instead, it appends the new PIB values to the end of the old PIB. To actually replace existing PIB values, you must write the same PIB again, like this:

# plctool -P QCA7000.pib -R 00B05201053E

---

The following commands do the same thing, but they avoid one unecessary reset. efficient queen behavior 👑

# plctool -P QCA7000.pib -N QCA7000.nvm 00B05201053E
# plctool -P QCA7000.pib -R 00B05201053E

The reset can also be postponed, like so:

# plctool -P QCA7000.pib -N QCA7000.nvm 00B05201053E
# plctool -P QCA7000.pib 00B05201053E
# plctool -R 00B05201053E

---

The next two commands are equivalent. They set the NMK on the local device to key1 as described in the KEYS section. The first command resets the NMK on the local device with -M and then specifies the NMK as key1. The second command omits the key specification, since key1 is the program default NMK. And yeah, you could of course just type the encryption key yourself, main character energy. 🔥

# plctool -MK key1
# plctool -M

👀 SEE ALSO 👀

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

(yes, ampboot(1) is listed twice. we're not editing the group chat history. 💅)

🫶 CREDITS 🫶

• Charles Maier
• Nathaniel Houghton

---

and that's a wrap on plctool(1), bestie!! 🎀 this was open-plc-utils-0.0.3, dated November 2013 — vintage but still iconic, like a thrifted jacket. go flash something responsibly, drink water, and remember: reset after flash is no longer automatic. mwah 💖✨🌸