ampstat(1)

✨ NAME ✨

ampstat - Qualcomm Atheros AR7x00 Link Statistics 💖

📦 SYNOPSIS

ampstat [options] [device] [device] [...]

💅 DESCRIPTION

Okay so the Atheros Device Statistics Utility basically pokes a device and spits out network and link stats in a bunch of formats other programs can actually use. 🧚 It's still a work in progress, so bestie, user feedback is highly encouraged! 🫶

Quick heads up: link statistics are only valid between one powerline device and another, so don't expect them to make sense otherwise. 🙈

This program is part of the Qualcomm Atheros Powerline Toolkit. For an overview and installation instructions, check out the plc man page. ✨

🦋 COMMENTS

This program is identical to the legacy program int6kstat, but it uses version 1 of the Qualcomm Atheros VS_NW_INFO Atheros vendor-specific message. 💜

Older firmware versions may not recognize this message version. So if things look off, it might be the firmware, not you. 😭

⚙️ OPTIONS ✨

• -C — Clear the device link statistics using VS_LNK_STATS. The stats get read and cleared, then displayed. Which stats get read and shown depends on -d, -p and -s, but all link statistics are cleared no matter what. 🧹
• -d direction — Grab the statistics for a specific direction using VS_LNK_STATS. You can pass 0 (tx), 1 (rx), 2 (both), or just "rx", "tx" or "both". Pick your fighter! 🎀
• -e — Redirects stderr messages to stdout. Normally status and error messages go to stderr while the main output goes to stdout, but this option sends everything to stdout for when you need it all in one place. 📬
• -i — Selects the host Ethernet interface. All requests go out through this 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. 🌸 However, if the environment variable PLC is defined, it takes precedence over that default. And if you use this option, it wins over both defaults. 👑
• -l count — Sets how many times the command gets repeated for each device you list. Usually you'll only repeat stuff on one device, so don't stress. 🔁
• -m — Displays network membership info as seen by one device, using VS_NW_INFO. If you want the full network topology from the local host's point of view, use -t instead. 🌐
• -p peernode — The Ethernet hardware address of the peer node for VS_LNK_STATS. This is required for every Link ID value except 0xFC. The default is 00:00:00:00:00:00. 🫧
• -q — Enters quiet mode, which suppresses progress messages. Shh, it's a secret. 🤫
• -s linkid — The Link ID for VS_LNK_STATS. Link IDs range from 0 through 255, but the device firmware doesn't accept every value. You can write values in decimal, binary with a 0b prefix, or hexadecimal with a 0x prefix. Lots of valid values also have names, and those are listed and explained under LINKID. The default Link ID is 0xFC. 🔢
• -t — Displays network topology using VS_SW_VER and VS_NW_INFO messages. It's similar to -m, but it gives you the complete topology plus each device's hardware and firmware version. Topology is always relative to the local host (or local hosts, if there are several). Powerline devices on the command line don't get used for this one. 🗺️

Older QCA powerline devices may fail to respond to this option. If that happens, try int6kstat or plcstat instead. 💀

• -v — Enters verbose mode. Every Ethernet frame the program sends or receives gets displayed on stdout. Very detailed, very main-character. 🔍
• -w seconds — Sets how many seconds to wait before repeating the command line options. This does nothing unless -l is also set to a non-zero value. ⏳
• -?, --help — Prints the program help summary on stdout. This one beats every other option on the command line. 🆘
• -!, --version — Prints the program version info on stdout. This one also beats every other option on the command line. If you're sending screen dumps to Atheros Technical Support, use this so they know exactly which version of the Linux Toolkit you're running. 📸

🎀 ARGUMENTS ✨

• device — The MAC address of a powerline device. You can list more than one, and if you do, the operations run on each device in turn. The default is local. For symbolic device addresses, see DEVICES. 🧸

🔗 LINKID ✨

These are the named Link IDs you can pass to -s. 💫

• 0x00, CSMA-CAP0 — Shows CSMA stats for CAP0 traffic using a single peer node. You have to specify the peer node MAC address with -p. 🟣
• 0x01, CSMA-CAP1 — Shows CSMA stats for CAP1 traffic using a single peer node. You have to specify the peer node MAC address with -p. 🔵
• 0x02, CSMA-CAP2 — Shows CSMA stats for CAP2 traffic using a single peer node. You have to specify the peer node MAC address with -p. 🩵
• 0x03, CSMA-CAP3 — Shows CSMA stats for CAP3 traffic using a single peer node. You have to specify the peer node MAC address with -p. 💚
• 0xF8, CSMA-PEER — Shows CSMA stats for all traffic using a single peer node. You have to specify the peer node MAC address with -p. 🩷
• 0xFC, CSMA-ALL — Shows CSMA stats for all traffic with all peer nodes. You don't need a peer node MAC address here, and if you give one anyway it gets ignored. This is the default for -s. 👑

🗺️ DEVICES ✨

Powerline devices use Ethernet Media Access Control (MAC) addresses. A MAC address is a 48-bit value written as 12 hexadecimal digits, in upper, lower or mixed case. You can separate the octets with colons if you want it to look cleaner. For example, 00b052000001, 00:b0:52:00:00:01 and 00b052:000001 are all valid and equivalent. Iconic. 🫶

These special MAC addresses can be entered by name instead of by number:

• all — Same as broadcast. 📣
• broadcast — A synonym for the Ethernet broadcast address, FF:FF:FF:FF:FF:FF. Every device recognizes messages sent here, whether it's local, remote or foreign. 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 ✨

Check out the Qualcomm Atheros HomePlug AV Firmware Technical Reference Manual for more info. 📖

⚠️ DISCLAIMER ✨

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 change message structure and content in future firmware releases, without any obligation to notify or compensate users of this program. Rude, but that's the deal. 🙃

🧪 EXAMPLES ✨

None. 🥲

🔗 SEE ALSO ✨

plc(1), amplist(1), amprate(1), ampstat(1), amptone(1), amptool(1) 🌈

👯 CREDITS ✨

Charles Maier 💜

Source: open-plc-utils-0.0.3, last updated November 2013. Bye bestie, stay iconic! 🦋💅✨