ampwait(1)

✨ NAME ✨

ampwait — Qualcomm Atheros Powerline Procrastinator 💅 It lives in the Qualcomm Atheros Open Powerline Toolkit, so it's giving main character energy 👑

🌸 SYNOPSIS 🌸

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

💖 DESCRIPTION 💖

okay so ampwait is the patient bestie of the group 🧚 It polls a Qualcomm Atheros powerline device and waits for one or more events to happen before it continues or returns. The events are reset or power off, restart or power on, and network association. It's used to pause shell scripts at critical points where a device has to be in a known state before anything else happens. no cap, it's so clutch 🔥

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

✨ OPTIONS ✨

• -a — This one pings the device every few seconds with VS_NW_INFO messages until it says a network exists and has at least one station 🛜 Heads up bestie, it can give false readings if other devices have dropped offline but the device bridging table still remembers them 🙈 If other event options are specified, this one always gets checked last 💅
• -e — Redirects stderr messages to stdout. Normally status and error messages go to stderr while the main output goes to stdout. This option shoves everything onto stdout for when you want it that way 🍓
• -f firmware — The identification string for the firmware that should be running after the device starts. Use it to catch a failed firmware load 😭 If the real identification string doesn't match once the device starts, an error gets reported. If -x is also present, the program exits with a non-zero exit code. This does nothing unless -s is present too. An identification string looks like "INT6000-MAC-3-1-3143-1690-20071107-FINAL-B", and you can grab one with int6k -r 🎀
• -i — Picks the host Ethernet interface. All requests get sent through this host interface, and only responses that come back through it get recognized 🌐 The default is eth1, because most people use eth0 as their main network connection 🌈 BUT if the environment string "PLC" is defined, it takes priority over the default. And this option beats both of those 👑
• -p seconds — Fixed pause time in seconds. It adds a fixed delay after the other events have occurred ⏸️ No pause happens if any of the specified events time out 💀 With no other events specified, this one is basically the same as sleep 😴 It's great for letting the device or the network settle. For example, a nominal 5 second wait is recommended after a device successfully associates, before you try transferring data ✨
• -q — Quiet mode 🤫 Progress messages get suppressed.
• -R — Resets the device, then checks the return status. If -x is present, the program exits on error. Otherwise it keeps repeating the reset request until the device accepts it or the wait time runs out 🔁
• -s — Polls the device every few seconds with VS_SW_VER messages until the bootloader or runtime firmware responds, or the poll count runs out 📡 A response means the device has connected to the host, received power, or finished rebooting 🎀
• -t milliseconds — Channel read/write timeout in milliseconds. This is the max time allowed for a confirmation or a response from a powerline device before the read/write op gets abandoned ⏱️ Allowed values range from 0 through UINT_MAX as defined in limits.h. The default is 50 milliseconds.
• -v — Verbose mode 📣 Every Ethernet frame sent or received by the program gets displayed on stdout.
• -w seconds — Wait timeout in seconds. This is the max time the app will wait for an event to happen, where an event is reset, start or assoc ⏰ If the event doesn't happen in time, the program moves on to wait for the next specified event. This timeout applies to each event in turn when you specify more than one. Allowed values are 0 through 86400 seconds, which is 24 hours 🫠
• -x — Exits the program on the first error with a non-zero exit code. This lets shell scripts catch failed or incomplete operations and take the right action 🫶
• -y — Shows the actual wait times on stdout ⏳
• -?, --help — Prints the program help summary on stdout. This one beats the other options on the command line 👑
• -!, --version — Prints the program version info on stdout. It also beats the other options on the command line. Use this when you're sending screen dumps to Atheros Technical Support, so they know exactly which version of the Linux Toolkit you're using 🙏

🧚 ARGUMENTS 🧚

• device — The Media Access Control (MAC) address of some device. Addresses are 6 hexadecimal octets, optionally separated by colons 💜 For example, "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".

📚 REFERENCES 📚

See the Qualcomm Atheros HomePlug AV Firmware Technical Reference Manual for more info 🤓

🌈 DISCLAIMER 🌈

Real talk bestie: the 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. 💀

🎀 EXAMPLES 🎀

The following command polls the local device until firmware stops running, then polls it again until firmware starts running again. You can drop this into a shell script at a point where the device has to reset and reboot before moving on 🧚 Notice the program waits up to 60 seconds for each event, in turn, because 60 seconds is the default wait period 🕐 If an event happens before the timeout, the program moves 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

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). It's the same as the one above, but we've 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

The next example reports the actual amount of time each event took to happen ⏱️ Notice that the last event, device association, did not happen 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

This example shows how the revision string catches mismatched firmware 🔍 Here we reset the device first, using the program amptool, then wait for it to reset and start up again. There are also operations that can make the device 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

Right after a reset, we wait for the firmware to stop responding (with option -r), then for it to start responding (with option -s), and then do a string comparison against the actual firmware revision string (with option -f). If the strings don't match, an error is reported. Since option -x is present, the program exits with a non-zero return code in this case 🔥

🦋 DISCLAIMER 🦋

Real talk bestie: the 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. 💀

🔗 SEE ALSO 🔗

amp(1), amptool(1), amphost(1), amprate(1), ampid(1), ampstat(1) 💜

👑 CREDITS 👑

Huge shoutout to Charles Maier 🫶

Version open-plc-utils-0.0.3, November 2013. That's a wrap on ampwait(1), bestie! Go wait for those events in style 💖🦋✨