amprate(1)

💖 amprate 💖

okay bestie, let's talk about amprate 🦋 It's the Qualcomm Atheros Open Powerline Toolkit at its most iconic, so buckle up ✨

✨ NAME ✨

amprate is the Qualcomm Atheros AR7x00 PHY Rate Monitor, and it is giving main character energy 💅

🎀 SYNOPSIS 🎀

amprate [options] [device] [device] [...]

🌸 DESCRIPTION 🌸

okay so the Atheros PHY Rate Utility pokes at one or more devices and tells you the average transmit and receive PHY rates between a device and each neighboring network device 🔥 The output is column-based, so it's perfect for dumping into a spreadsheet or feeding into a simple program 📊

This program is part of the Qualcomm Atheros Powerline Toolkit 🧚 Check out the plc man page for the overview and install instructions, bestie 🫶

💜 COMMENTS 💜

tea time 🍵 This program is basically identical to the legacy program int6k, except options -t and -T use version 1 of the Qualcomm Atheros VS_NW_INFO vendor-specific message. Older firmware versions might not recognize this message version 🙈

✨ OPTIONS ✨

• -c — shows the coded PHY rates 🍓 Coded rates are already the default, so this one is technically redundant, but it's kept around for backwards compatibility 💖 This option and -u are mutually exclusive, so don't stan both at once 💀
• -d seconds — how long the traffic lasts for each connection, in seconds ⏱️ Directional traffic gets sent between each pair of powerline devices for that long. The total time to generate traffic between all devices is roughly n! times this value, so don't get carried away 😭 The minimum is 1 second and the maximum is 60 seconds.
• -e — redirects stderr messages to stdout 🔀 Normally status and error messages go to stderr while the main output goes to stdout. This option sends everything to stdout for when that's what you want 🫶
• -i interface — picks the host Ethernet interface 🔌 All requests go out this interface, and only responses received on it get recognized. The default is eth1, since most people use eth0 as their main network connection 😌 But if the environment string PLC is defined, it takes priority over that default. And this option beats both of them 👑
• -n — reads the average transmit and receive PHY rate for each device using VS_NW_INFO and prints it to stdout 📈 Each output line shows the Ethernet interface, source address, destination address, and either the transmit or receive PHY rate.
• -o milliseconds — read timeout in milliseconds ⏰ Values can go from 0 through UINT_MAX. It's the max time allowed for a response. The default is shown in brackets on the program menu 📋
• -r — reads the device's hardware and software revision info using VS_SW_VER and prints it to stdout 🛠️
• -R — resets the device using VS_RS_DEV 🔄
• -t — generates powerline traffic between the local device and each remote device on each powerline network connected to the host 🚀 It does not generate traffic between remote device pairs 🙅 This one is especially useful when remote powerline devices aren't hooked up to Ethernet devices that can send traffic back to the host 🫶
• -T — generates powerline traffic between all devices on each powerline network connected to the host 🌐 It's similar to -t, but it takes way longer because traffic gets generated systematically between every pair of powerline devices. Complete traffic path coverage isn't always needed 🤷

heads up 💀 The time to complete -T grows factorially as you add network devices, so this one can take a seriously long time.

• -u — displays the un-coded PHY rates 🔓 Coded rates are shown by default. This option and -c are mutually exclusive.
• -q — enters quiet mode 🤫 Progress messages get suppressed.
• -v — enters verbose mode 📢 Every Ethernet frame the program sends or receives gets displayed on stdout.
• -x — exits on the first error with a non-zero exit code 🚪 This lets shell scripts detect failed or incomplete operations and respond accordingly 🧠
• -?, --help — prints the program help summary on stdout ❓ This option takes precedence over other options on the command line.
• -!, --version — prints the program version info on stdout 🏷️ It also 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 🙏

🦋 ARGUMENTS 🦋

• device — the MAC address of some powerline device 💌 You can specify more than one. If you do, operations run on each device in turn. The default is local. See DEVICES for info about symbolic device addresses.

🧚 DEVICES 🧚

Powerline devices use Ethernet Media Access Control (MAC) addresses 🔢 A MAC address is a 48-bit value entered as 12 hexadecimal digits, in upper, lower, or mixed case. Octets can be separated with colons for clarity. These are all valid and equivalent 💯:

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

The following MAC addresses are special and can be entered by name instead of number ✨

• all — same as broadcast.
• broadcast — a synonym for the Ethernet broadcast address, FF:FF:FF:FF:FF:FF 📣 All devices, whether local, remote, or foreign, recognize messages sent to this address. A remote device is any device at the far end of a powerline connection. A foreign device is any device not manufactured by Atheros.
• local — a synonym for the Qualcomm Atheros vendor-specific Local Management Address (LMA), 00:B0:52:00:00:01 🏠 All local Atheros devices recognize this address, 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 📚

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

🎬 EXAMPLES 🎬

Example one! This shows the average TX and RX PHY rates from each of two devices. One is a local device connected to interface eth2, and the other is a remote device at the far end of the powerline. They're the only two devices on this powerline network, so notice the reciprocal rates shown 👀

# amprate -ni eth2 00:B0:52:00:00:AA 00:B0:52:00:00:BB
eth2 00:B0:52:00:00:AA 00:B0:52:00:00:BB TX 163 mbps
eth2 00:B0:52:00:00:AA 00:B0:52:00:00:BB RX 176 mbps
eth2 00:B0:52:00:00:BB 00:B0:52:00:00:AA TX 176 mbps
eth2 00:B0:52:00:00:BB 00:B0:52:00:00:AA RX 163 mbps

Example two! This one generates powerline traffic between the local device and each remote device, because -t is present 🚀 Then it displays the PHY rate read from the local device.

# amprate -tni eth2
eth2 00:B0:52:00:00:AA 00:B0:52:00:00:BB TX 163 mbps
eth2 00:B0:52:00:00:AA 00:B0:52:00:00:BB RX 176 mbps

🙈 DISCLAIMER 🙈

heads up 🫣 The Atheros HomePlug AV Vendor Specific Management Message Entry 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 and content in future firmware releases, without any obligation to notify or compensate users of this program.

🔗 SEE ALSO 🔗

plc(1), amprule(1), ampstat(1), amptone(1)

🫶 CREDITS 🫶

• Nathaniel Houghton
• Charles Maier

ily bestie 💖 this little guide came from open-plc-utils-0.0.3, November 2013, and we're keeping it iconic forever 🌈💅👑