plcstat(1)

💖 plcstat — Qualcomm Atheros AR7x00 Link Statistics 💖

okay bestie, welcome to plcstat(1) from the Qualcomm Atheros Open Powerline Toolkit — yes that whole toolkit, we're getting into it. 🦋

SYNOPSIS

plcstat [options] [device] [...]

DESCRIPTION

The Atheros Device Statistics Utility goes and polls a device, then prints out network and link statistics in a bunch of different formats that are suitable for other programs to snack on. 🍓 Heads up tho: this is a work in progress, so user feedback is genuinely encouraged — slide into the comments, they want to hear from you.

Also real talk: link statistics are only valid between one powerline device and another. That's the whole vibe.

This program is part of the Qualcomm Atheros Powerline Toolkit. If you want the overview and the installation instructions, go read the plc man page. 👑

COMMENTS

So this program is literally identical to the legacy program int6kstat, except it uses version 1 of the VS_NW_INFO Atheros vendor-specific message. Older firmware versions may not recognize this message version — not their fault, they're just old. 💀

OPTIONS ✨

• -C — Clear device link statistics using VS_LNK_STATS. The stats get read and cleared, then displayed. Which stats get read and displayed depends on options -d, -p and -s, but bestie — all link statistics are cleared. Every single one. 🧹
• -d direction — Return statistics for the specified direction using VS_LNK_STATS. Direction can be 0=tx, 1=rx, 2=both, or the strings "rx", "tx" or "both". Pick your fighter.
• -e — Redirects stderr messages to stdout. By convention, status and error messages go on stderr while the primary program output goes on stdout — this option puts all output on stdout, for when that's what you want. 🫶
• -i — Select the host Ethernet interface. All requests are sent via this host interface, and only responses received via this host interface are recognized. The default interface is eth1, because most people use eth0 as their principle network connection. However — if the environment string PLC is defined, it takes precedence over the default interface. And this option then takes precedence over either default. Precedence chain, periodt. 👑
• -l count — Define the number of times that the command will be repeated for each device specified. Normally you'll repeat operations on one device only.
• -m — Displays network membership information, as seen by one device, using VS_NW_INFO. Want the complete network topology seen by the local host instead? Use option -t.
• -p peernode — Ethernet hardware address of the peer node for VS_LNK_STATS. This option is required for all Link ID values except 0xFC. The default is 00:00:00:00:00:00.
• -q — Enter quiet mode. Progress messages are suppressed. 🤫
• -s linkid — The Link ID for VS_LNK_STATS. Link ID values range from 0 through 255, but not all values are accepted by the device firmware (rude, honestly). Values may be expressed in decimal, in binary prefixed with "0b", or in hexadecimal prefixed by "0x". Many valid values can also be expressed by name — the valid ones are listed and explained under LINKID. The default Link ID is 0xFC.
• -t — Display network topology using VS_SW_VER and VS_NW_INFO messages. This is similar to option -m but gives you the complete network topology plus device hardware and firmware version. Topology is relative to the queried powerline device(s) given on the command line. If no device is given explicitly, then it is tried to determine all local devices (you can also use local instead). However, this can fail if you have the local powerline device(s) not directly connected but via a switch which does not broadcast the Qualcomm Atheros vendor specific Local Management Address (LMA) to all ports. 🙈
• -v — Enter verbose mode. All Ethernet frames sent or received by the program are displayed on stdout. Every. Single. Frame. 💅
• -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.
• -?, --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 one 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 MAC address of some powerline device. More than one address may be specified. If more than one address is specified then operations are performed on each device in turn. The default address is local. See DEVICES for information about symbolic device addresses.

LINKID 🔥

• 0x00, CSMA-CAP0 — Display CSMA statistics for CAP0 traffic using a single peer node. The peer node MAC address must be specified using option -p.
• 0x01, CSMA-CAP1 — Display CSMA statistics for CAP1 traffic using a single peer node. The peer node MAC address must be specified using option -p.
• 0x02, CSMA-CAP2 — Display CSMA statistics for CAP2 traffic using a single peer node. The peer node MAC address must be specified using option -p.
• 0x03, CSMA-CAP3 — Display CSMA statistics for CAP3 traffic using a single peer node. The peer node MAC address must be specified using option -p.
• 0xF8, CSMA-PEER — Display CSMA statistics for all traffic using a single peer node. The peer node MAC address must be specified using option -p.
• 0xFC, CSMA-ALL — Display CSMA statistics for all traffic with all peer nodes. A peer node MAC address is not needed and will be ignored if provided. This value is the default for option -s. ⭐

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 character case. Octets may be separated with colons for clarity. For example, "00b052000001", "00:b0:52:00:00:01" and "00b052:000001" are all valid and equivalent — same address, three fits. 💅

The following MAC addresses are special and may 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 do not. 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. 📚

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. Not a drill, bestie. 💀

EXAMPLES

None. 😭

SEE ALSO

plc(1), plcrate(1), plcstat(1), plctool(1)

CREDITS

Charles Maier

okay that's the whole page, you ate that 💖 this shipped as part of open-plc-utils-0.0.3, dated November 2013 — iconic behavior, no cap. go poll some devices, bestie. 🦋✨