plcwait(1)

✨ NAME ✨

ampwait — the Qualcomm Atheros Powerline Procrastinator 🦋 — which is also what you're looking at right now, plcwait(1), part of the Qualcomm Atheros Open Powerline Toolkit. She is patient. She is unbothered. She waits. 💅

📜 SYNOPSIS 📜

ampwait [options] [device] [device] [...]

💖 DESCRIPTION 💖

ok so bestie, the whole concept is this: you point ampwait at a Qualcomm Atheros powerline device and it just polls that thing, waiting for one or more events to happen before it continues or returns. The events are:

• reset or power off
• restart or power on
• network association

It exists so you can pause a shell script at critical points, where the device has to be in a known state before anything else can proceed. It's giving emotional support for your script. 🧘‍♀️

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

🌈 OPTIONS 🌈

• -a — poll the device every few seconds using VS_NW_INFO messages until the device indicates that a networks exists and has at least one station. ⚠️ heads up though: this can give false readings if other devices have dropped off-line and the device bridging table still holds information about them. If you also specified other event options, the program always checks for this event last.
• -e — redirects stderr messages to stdout. By convention 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. ✨
• -f firmware — the identification string for firmware that should be running after the device starts. Use it to detect a failed firmware load 🫠. If the actual identification string does not match this one once the device starts then an error is reported. If option -x is present then the program terminates with a non-zero exit code. This option has no effect unless option -s is present. An identification string looks like "INT6000-MAC-3-1-3143-1690-20071107-FINAL-B" and can be obtained using int6k -r.
• -i — 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. 👑 queen of the hierarchy.
• -p seconds — fixed pause time in seconds. This adds an fixed delay after the other events have occured. A pause does not occur if any of the specified events timeout. When no other events are specified this option is effectively equivalent to sleep. Great for letting the device or the network settle. For example, a nominal 5 second wait is recommended after a device successfully associates before attempting to transfer data. ⏳
• -q — enter quiet mode. Progress messages are suppressed. 🤫
• -R — reset the device then check return status. Exit program on error if option -x is present; otherwise, repeat the reset request until the device either accepts the request or the wait time is exceeded.
• -s — poll the device every few seconds using VS_SW_VER messages until the bootloader or runtime firmware responds or the poll count exhausts. The presence of a response indicates that the device has either connected to the host, received power or finished reboot. ⚡
• -t milliseconds — channel read/write timeout in milliseconds. This is the maximum time allowed for a confirmation or a response from a powerline device before abandoning a read/write operation. Permitted values range from 0 through UINT_MAX as defined in limits.h. The default is 50 milliseconds.
• -v — enter verbose mode. All Etherenet frames sent or received by the program are displayed on stdout. 🫣 every single one.
• -w seconds — wait timeout in seconds. This is the maximum time that this application will wait for an event to occur where an event is reset, start or assoc. If an event does no occur within this time, the program proceeds to wait for the next specified event. This timeout applies to each event in turn when more than one event is specified. Permitted values are 0 through 86400 seconds which is 24 hours. 🕰️
• -x — exit program on first error with a non-zero exit code. This option allows shell scripts to detect failed or incomplete operations and take the appropriate action. 💀
• -y — display actual wait times on stdout. ⏱️
• -?, --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 Media Access Control (MAC) address of some device. Addresses are 6 hexadecimal octets optionally separated by colon. For example, the addresses "00b052000001", "00:b0:52:00:00:01" and "00b052:000001" are all valid and equivalent. For convenience, the symbolic address "local" resolves to "00:b0:52:00:00:01" and the symbolic addresses "all" and "broadcast" both resolve to "ff:ff:ff:ff:ff:ff". 🦋 so many ways to say the same thing, and we love that for us.

📚 REFERENCES 📚

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

💀 DISCLAIMER 💀

Atheros HomePlug AV Vendor Specific Management Message Entry 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 and content in future firmware releases without any obligation to notify or compensate users of this program. 🫠 yeah. that's the whole thing. read it twice if you need to.

🌟 EXAMPLES 🌟

example one: reset then start, with default waits

The following command polls the local device until firmware stops running then polls the device until firmware starts running again. This command can be inserted into a shell script at a point where the device must reset and reboot before proceeding. Observe that the program waits up to 60 seconds for each event, in turn, because 60 seconds is the default wait period. If an event occurs before the specified timeout the program will move on to the next event. 🏃‍♀️

# ampwait -rs
eth0 00:B0:52:BA:BA:01 Allow 60 seconds for Reset
eth0 00:B0:52:BA:BA:01 Allow 60 seconds for Start

example two: same thing but with our own timeout

The following example waits up to 30 seconds for the local device to reset (-r) then up to 50 seconds for the local device to start (-s). This is the same as above but we have specified 30 seconds using option -w.

# ampwait -r -s -w 30
eth0 00:B0:52:BA:BA:01 Allow 30 seconds for Reset
eth0 00:B0:52:BA:BA:01 Allow 30 seconds for Start

example three: show me the receipts

The next example reports the actual amount of time taken for each event to occur. Observe that the last event, device association, did not occur within the allotted time. 😭

# ampwait -rsay
eth0 00:B0:52:BA:BA:01 Allow 60 seconds for Reset
etho 00:B0:52:BA:BA:01 Waited 22 seconds to Reset
eth0 00:B0:52:BA:BA:01 Allow 60 seconds for Start
etho 00:B0:52:BA:BA:01 Waited 4 seconds to Start
eth0 00:B0:52:BA:BA:01 Allow 60 seconds for Assoc
etho 00:B0:52:BA:BA:01 Waited 60 seconds for Assoc
etho 00:B0:52:BA:BA:01 Device did not Assoc

example four: catching mismatched firmware

The following example illustrates use of the revision string to detect mismatched firmware. In this example, we reset the device first, using program amptool, then wait for it to reset then start up again. There are also operation that can cause the device to reset.

# amptool -R
# ampwait -xrsf INT6000-MAC-3-1-3143-1690-20071107-FINAL-B
eth0 00:B0:52:BA:BA:01 Device started wrong firmware

Immediately after a reset we wait for the firmware to stop responding, with option -r, and then start responding, with option -s, and then perform a string comparison against the actual firmware revision string, with option -f. If the strings do not match then an error is reported. In this case, the program will exit with a non-zero return code since option -x is present. 🔥

💀 DISCLAIMER 💀

Atheros HomePlug AV Vendor Specific Management Message Entry 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 and content in future firmware releases without any obligation to notify or compensate users of this program. 🫠 yes, bestie, it really does say it twice. that's not a me thing, that's a them thing.

👀 SEE ALSO 👀

amp(1), amptool(1), amphost(1), amprate(1), ampid(1), ampstat(1) — go read the whole friend group. 💜

🏆 CREDITS 🏆

Charles Maier 🌸

and that's the whole page, bestie!! this gem is from open-plc-utils-0.0.3, dated November 2013 — yeah, she's vintage, and she still ate. 🎀⭐💅