Using open-plc-utils in Linux with Powerline (HomePlug) adapters
April 23, 2021 6 Comments
According to the open-plc-utils documentation, open-plc-utils supports INT6000, INT6300, INT6400, AR6410, QCA7000, AR7400 and AR7420 and later Powerline products from Qualcomm Atheros. ‘INT’ stands for ‘Intellon’, which was acquired by Atheros in 2009. ‘AR’ stands for ‘Atheros’, which was acquired by Qualcomm in 2011. ‘QCA’ stands for ‘Qualcomm Atheros’.
The open-plc-utils command int6k
supports legacy chipsets INT6000, INT6300 and INT6400.
The open-plc-utils command plctool
supports QCA6410, QCA7000 and QCA7420 chipsets.
The open-plc-utils command amptool
supports AR7400 and QCA7450 chipsets.
I have used open-plc-utils successfully with the following Powerline products:
- NETGEAR XAVB1301-100UKS (uses AR6405 chipset).
- NETGEAR XAVB5221-100UKS (uses QCA7420 chipset).
- TP-Link TL-PA4010 (uses QCA7420 chipset).
- TP-Link TL-PA4010P (uses QCA7420 chipset).
- TP-Link TL-PA4020P (uses QCA7420 chipset).
For example, I used open-plc-utils to update the chipset firmware in my TP-Link Powerline adapters, as explained in my earlier post ‘Updating the Powerline adapters in my home network‘.
Below I summarise how I install open-plc-utils in Linux and how I use them to interrogate the Powerline adapters in my home network.
1. Download the open-plc-utils source code
user $ cd
user $ wget https://github.com/qca/open-plc-utils/archive/refs/heads/master.zip
user $ unzip master.zip # (This creates ~/open-plc-utils-master directory.)
2. Install plc-utils
user $ cd ~/open-plc-utils-master/
user $ cat README # Tells you how to install/uninstall plc-utils.
user $ sudo make
user $ sudo make install
user $ sudo make manuals
3. Bookmark the documentation index pages in your Web browser
user $ cd ~/open-plc-utils-master/docbook
Bookmark file:///home/<username>/open-plc-utils-master/docbook/index.html
Bookmark file:///home/<username>/open-plc-utils-master/docbook/toolkit.html
4. Use open-plc-utils commands to interrogate the adapters in the network
One example of the many possible commands:
user $ plcstat -t -i eno1 # eno1 is the Ethernet interface on this computer.
P/L NET TEI ------ MAC ------ ------ BDA ------ TX RX CHIPSET FIRMWARE
LOC STA 038 11:11:11:11:11:11 88:88:88:88:88:88 n/a n/a QCA7420 MAC-QCA7420-1.5.0.26-02-20200114-CS
REM STA 003 33:33:33:33:33:33 55:55:55:55:55:55 277 268 QCA7420 MAC-QCA7420-1.5.0.26-02-20200114-CS
REM CCO 004 22:22:22:22:22:22 FF:FF:FF:FF:FF:FF 009 009 QCA7420 MAC-QCA7420-1.5.0.26-02-20200114-CS
(For security reasons, in the output above I have edited the MAC addresses of the three adapters, and the BDA of the two STAs. The BDA of the CCO adapter, which is automatically selected, really is displayed as FF:FF:FF:FF:FF:FF
though.)
- LOC = ‘Local’, i.e. the Powerline adapter connected to this computer.
- REM = ‘Remote’, i.e. the other Powerline adapters in the network.
- CCO = ‘Central Coordinator’, i.e. the automatically selected Powerline adapter acting as the coordinator of the Powerline adapters in this network.
- STA = ‘Station’, i.e. the Powerline adapters being coordinated by the CCO.
- MAC = The MAC address of the adapter.
- BDA = ‘Bridged Destination Address’ (see the Powerline specifications for the meaning).
- TX/RX = the transmission/reception rate in Mbps of the adapter.
- CHIPSET = Atheros Qualcomm chipset type.
- FIRMWARE = Atheros Qualcomm chipset firmware version.
For other open-plc-utils commands, consult the documentation in a Web browser.
5. Optional: Create a Bash script to interrogate Powerline adapters in your network
user $ cd
user $ nano ~/homeplug.sh
user $ chmod +x ~/homeplug.sh
homeplug.sh
#!/bin/bash # # This script is to interrogate a network to find the details of the Powerline # HomePlug wall adapters in the network. It uses open-plc-utils tools: # https://github.com/qca/open-plc-utils # See https://github.com/qca/open-plc-utils/blob/master/README for # instructions on how to install (and uninstall) the tools. # Therefore this script is limited to the chipsets that open-plc-utils supports: # https://github.com/qca/open-plc-utils/blob/master/plc/chipset.h # # The command int6k supports legacy chipsets INT6000, INT6300 and INT6400. # The command plctool supports QCA6410, QCA7000 and QCA7420 devices. # The command amptool supports chipsets AR7400 and QCA7450. # NETGEAR XAVB1301-100UKS uses AR6405. NETGEAR XAVB5221-100UKS uses QCA7420. # TP-Link TL-PA4010, TL-PA4010P and TL-PA4020P use QCA7420. # echo "================================================================================" # Specify the interface on this PC connected to a HomePlug device: export PLC=$( ifconfig | head -1 | cut -d ":" -f1 ) echo echo -n "The Ethernet interface on this PC is: " echo $PLC echo echo "================================================================================" echo # # Step 1. Send VS_SW_VER to local device to determine its MAC address and device type. # MACINT6K=$( int6k -qr | awk -F ' ' '{print $2}' ) MACPLCTOOL=$( plctool -qr | awk -F ' ' '{print $2}' ) if [[ $MACINT6K != $MACPLCTOOL ]] then echo "Unable to determine MAC address of local HomePlug wall adapter." exit else MAC=$MACINT6K fi echo "Details for the HomePlug wall adapter connected to this computer:" echo if [ $( int6k -qI $MAC | wc -l ) -lt 2 ] then plctool -m $MAC plctool -qI $MAC echo CHIPSET=$( plctool -qr $MAC | awk -F ' ' '{print $3}' ) echo -n "Chipset: " echo $CHIPSET CHIPSETTYPE=2 else int6k -m $MAC int6k -qI $MAC echo CHIPSET=$( int6k -qr $MAC | awk -F ' ' '{print $3}' ) echo -n "Chipset: " echo $CHIPSET CHIPSETTYPE=1 fi echo echo "================================================================================" # # Step 2. Send VS_NW_INFO (int6k -m or plctool -m, depending on device type) # to local MAC address to find MAC addresses of the other devices. # if [[ $CHIPSETTYPE == 2 ]] then plctool -qm $MAC | grep MAC | cut -d " " -f3 > maclist.txt elif [[ $CHIPSETTYPE == 1 ]] then int6k -qm $MAC | grep MAC | cut -d " " -f3 > maclist.txt else echo "Unable to determine chipset of the local HomePlug wall adapter." exit fi # # Step 3. Send VS_SW_VER (int6k -r or plctool -r, depending on device type) to # each device to find the device type of each. # echo -n "" > chipsetlist.txt while read -r MAC do if [ $( int6k -qI $MAC | wc -l ) -lt 2 ] then CHIPSET=$( plctool -qr $MAC | awk -F ' ' '{print $3}' ) echo $CHIPSET >> chipsetlist.txt else CHIPSET=$( int6k -qr $MAC | awk -F ' ' '{print $3}' ) echo $CHIPSET >> chipsetlist.txt fi done < maclist.txt # # Step 4. Send VS_NW_INFO (int6k -m or plctool -m, depending on device type) to # each device to determine full PHY Rate. # echo echo "Details for the other HomePlug wall adapters in the network" echo "(adapters in Power Saving Mode are not shown):" while read -r MAC && read -r CHIPSET <&3 do echo if [ $( int6k -qI $MAC | wc -l ) -lt 2 ] then plctool -m $MAC plctool -qI $MAC else int6k -m $MAC int6k -qI $MAC fi echo echo -n "Chipset: " echo $CHIPSET echo echo "--------------------------------------------------------------------------------" done <maclist.txt 3<chipsetlist.txt rm maclist.txt chipsetlist.txt echo echo "Some of the abbreviations are listed below, but refer to the open-plc-utils" echo "documentation for more details. (Also see http://www.homeplug.org/ for" echo "detailed HomePlug specifications)" echo echo "BDA Bridged Destination Address" echo "CCo Central Coordinator" echo "DAK Device Access Key" echo "MDU Multiple Dwelling Unit" echo "NID Network Identifier" echo "NMK Network Membership Key" echo "PIB Parameter Information Block" echo "SNID Short Network Identifier" echo "STA Station" echo "TEI Terminal Equipment Identifier" echo exit
Run homeplug.sh to see details of Powerline adapters with Qualcomm Atheros chipsets in the network:
user $ ./homeplug.sh
N.B. Adapters in Power Saving Mode are not detected, so, if you want to see details of all Powerline adapters on the network, make sure none of the adapters are in Power Saving Mode before you run the script.
Below is the script’s output for my home network with the following three TP Link Powerline adapters currently connected to wall power sockets:
- TP-Link TL-PA4010P(UK) VER:5.0 (one device)
- TP-Link TL-PA4010(UK) VER:3.0 (two devices)
I also own the following Powerline adapters, which are currently not plugged in to wall power sockets, but this script would detect them if they were plugged in (as I have seen previously):
- TL-PA4020P(UK) VER:4.0 (one adapter)
- NETGEAR XAVB1301-100UKS (three adapters)
- NETGEAR XAVB5221-100UKS (two adapters)
user $ ./homeplug.sh
================================================================================
The Ethernet interface on this PC is: eno1
================================================================================
Details for the HomePlug wall adapter connected to this computer:
eno1 11:11:11:11:11:11 Fetch Network Information
eno1 11:11:11:11:11:11 Found 1 Network(s)
source address = 11:11:11:11:11:11
network->NID = 99:99:99:99:99:99:99
network->SNID = 5
network->TEI = 38
network->ROLE = 0x00 (STA)
network->CCO_DA = 22:22:22:22:22:22
network->CCO_TEI = 4
network->STATIONS = 2
station->MAC = 33:33:33:33:33:33
station->TEI = 3
station->BDA = 55:55:55:55:55:55
station->AvgPHYDR_TX = 279 mbps Primary
station->AvgPHYDR_RX = 276 mbps Primary
station->MAC = 22:22:22:22:22:22
station->TEI = 4
station->BDA = FF:FF:FF:FF:FF:FF
station->AvgPHYDR_TX = 009 mbps Primary
station->AvgPHYDR_RX = 009 mbps Primary
PIB 0-0 8836 bytes
MAC 11:11:11:11:11:11
DAK 66:66:66:66:66:66:66:66:66:66:66:66:66:66:66:66
NMK 77:77:77:77:77:77:77:77:77:77:77:77:77:77:77:77
NID 99:99:99:99:99:99:99
Security level 0
NET Qualcomm Atheros Enabled Network
MFG tpver_401115_191120_901
USR tpver_401115_191120_901
CCo Auto
MDU N/A
Chipset: QCA7420
================================================================================
Details for the other HomePlug wall adapters in the network
(adapters in Power Saving Mode are not shown):
eno1 33:33:33:33:33:33 Fetch Network Information
eno1 33:33:33:33:33:33 Found 1 Network(s)
source address = 33:33:33:33:33:33
network->NID = 99:99:99:99:99:99:99
network->SNID = 5
network->TEI = 3
network->ROLE = 0x00 (STA)
network->CCO_DA = 22:22:22:22:22:22
network->CCO_TEI = 4
network->STATIONS = 2
station->MAC = 22:22:22:22:22:22
station->TEI = 4
station->BDA = FF:FF:FF:FF:FF:FF
station->AvgPHYDR_TX = 305 mbps Primary
station->AvgPHYDR_RX = 319 mbps Primary
station->MAC = 11:11:11:11:11:11
station->TEI = 38
station->BDA = 88:88:88:88:88:88
station->AvgPHYDR_TX = 276 mbps Primary
station->AvgPHYDR_RX = 279 mbps Primary
PIB 0-0 8836 bytes
MAC 33:33:33:33:33:33
DAK 00:00:00:00:00:00:00:00:00:00:00:00:00:00:00:00 (none/secret)
NMK 77:77:77:77:77:77:77:77:77:77:77:77:77:77:77:77
NID 99:99:99:99:99:99:99
Security level 0
NET Qualcomm Atheros Enabled Network
MFG tpver_401013_171025_901
USR tpver_401013_171025_901
CCo Auto
MDU N/A
Chipset: QCA7420
--------------------------------------------------------------------------------
eno1 22:22:22:22:22:22 Fetch Network Information
eno1 22:22:22:22:22:22 Found 1 Network(s)
source address = 22:22:22:22:22:22
network->NID = 99:99:99:99:99:99:99
network->SNID = 5
network->TEI = 4
network->ROLE = 0x02 (CCO)
network->CCO_DA = 22:22:22:22:22:22
network->CCO_TEI = 4
network->STATIONS = 2
station->MAC = 33:33:33:33:33:33
station->TEI = 3
station->BDA = 55:55:55:55:55:55
station->AvgPHYDR_TX = 319 mbps Primary
station->AvgPHYDR_RX = 305 mbps Primary
station->MAC = 11:11:11:11:11:11
station->TEI = 38
station->BDA = 88:88:88:88:88:88
station->AvgPHYDR_TX = 009 mbps Primary
station->AvgPHYDR_RX = 009 mbps Primary
PIB 0-0 8836 bytes
MAC 22:22:22:22:22:22
DAK 00:00:00:00:00:00:00:00:00:00:00:00:00:00:00:00 (none/secret)
NMK 77:77:77:77:77:77:77:77:77:77:77:77:77:77:77:77
NID 99:99:99:99:99:99:99
Security level 0
NET Qualcomm Atheros Enabled Network
MFG tpver_401013_171025_901
USR tpver_401013_171025_901
CCo Auto
MDU N/A
Chipset: QCA7420
--------------------------------------------------------------------------------
Some of the abbreviations are listed below, but refer to the open-plc-utils
documentation for more details. (Also see http://www.homeplug.org/ for
detailed HomePlug specifications)
BDA Bridged Destination Address
CCo Central Coordinator
DAK Device Access Key
MDU Multiple Dwelling Unit
NID Network Identifier
NMK Network Membership Key
PIB Parameter Information Block
SNID Short Network Identifier
STA Station
TEI Terminal Equipment Identifier
For security reasons, in the output above I have edited the network membership key, device access key, network identifier and adapter addresses in the above output as follows:
- I have changed the three MAC addresses of the three adapters to be 11:11:11:11:11:11, 22:22:22:22:22:22 and 33:33:33:33:33:33.
- I have changed the two BDAs of the two adapters that are Stations (STAs) to be 55:55:55:55:55:55 and 88:88:88:88:88:88.
- I have changed the DAK of the adapter connected to the computer on which the script was run to be 66:66:66:66:66:66:66:66:66:66:66:66:66:66:66:66.
- I have changed the NMK of the three adapters to be 77:77:77:77:77:77:77:77:77:77:77:77:77:77:77:77.
- I have changed the NID of the three adapters to be 99:99:99:99:99:99:99.
Some of the information that can be gleaned from the above output of the script:
- the adapter with MAC address 22:22:22:22:22:22 has been automatically set as the CCO (Central Coordinator) for the Powerline network, and the other two adapters (MAC addresses 11:11:11:11:11:11 and 33:33:33:33:33:33) are STAs (Stations);
- the only DAK that can be read is for the adapter connected to the computer;
- the BDA of the CCO is reported as FF:FF:FF:FF:FF:FF;
- all three Powerline adapters use the QCA7420 chipset;
- the two Powerline stations are different models of TP-Link adapter (TP-Link versions ending in ‘401115_191120_901’ and ‘401013_171025_901’); the central coordinator is the same TP-Link model as one of the stations (TP-Link version ending in ‘401013_171025_901’).
Indeed, a TP-Link TL-PA4010P(UK) VER:5.0 adapter is connected to this computer, and the two remote adapters are TP-Link TL-PA4010(UK) VER:3.0, one of which is currently acting as the CCO. Last year I updated the Qualcomm Atheros firmware in all of them (see my 2020 post ‘Updating the Powerline adapters in my home network‘).