Provided by: plc-utils_0.0.6+git20230504.1ba7d5a0-1_amd64 bug

NAME

       plctool - Qualcomm Atheros Panther/Lynx Powerline Device Manager

SYNOPSIS

       plctool [options] [device] [device] [...]

DESCRIPTION

       This version of the Qualcomm Atheros Powerline Device Manager performs basic operations on
       powerline  devices  using  vendor-specific  management  messages.   It  can  be  used   to
       interrogate  and  control  devices  or upgrade firmware if on-board NVRAM is present.  See
       amptool for a similar utility that supports AR7400 devices.  It supports chipsets QCA6410,
       QCA7000 and QCA7420.

       This  program  is  the proper tool for upgrading panther/lynx devices.  It is important to
       reset panther/lynx devices after update since reset after update is not automatic anymore.
       Also,  everything  takes  longer because part memory is erased before being written.  Some
       operations may take 20 to 40 seconds so be patient.

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

COMMENTS

       This  program version is identical to legacy program int6k except for option -m which uses
       version 1 of the Qualcomm Atheros  VS_NW_INFO  vendor-specific  message.   Older  firmware
       versions may not recognize this message version.

OPTIONS

       -a     Read  device  attributes  using VS_OP_ATTRIBUTES.  Attributes are short strings and
              integers that describe device hardware and firmware.  They are concatenated to form
              the output that is similar to option -r but derived differently.

       -B action
              press  the  simple connect pushbutton using VS_PB_ENC.  The action can be specified
              by number 1, 2, 3  or  4  or  by  symbol  "join",  "leave",  "status"  or  "reset",
              respectively.   Use 1 on both devices that are expected to join.  Use 2 only on the
              device that is expected to leave the network.

       -d filename
              Read Watchdog Report from the device and write it  to  the  named  file  in  binary
              format  using  VS_WD_RPT.   The  report  file  can  be sent to Qualcomm Atheros for
              technical analysis.  No assumptions are made based  on  filename  and  no  filename
              convetions  are enforced; however, you should use a .log file extension to indicate
              binary format.

       -D xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx
              Define the 16 octet Device Access Key (DAK) in hex format.   The  DAK  is  used  by
              option  -J.   It  may  also  be  set  to  "key1" or "key2" as explained in the KEYS
              section.

       -e     Redirects stderr messages to stdout.   Normally,  status  and  error  messages  are
              printed  on  stderr while primary program output is printed on stdout.  This option
              prints all output on stdout in cases where this is desired.

       -f     Read flash memory parameters using VS_GET_NVM.  An error will  be  reported  if  no
              flash memory is present.

       -F[F]  Write previously downloaded MAC and PIB to NVRAM using VS_MOD_NVM.  Adding a second
              F here or another -F anywhere on the command line WILL NOT force-flash a  blank  or
              corrupted  NVRAM  as  with  programs int6k and amptool.  Firmware loaded from NVRAM
              will treat force-flash as an error.  This option can  be  used  to  create  factory
              settings  but  cannot  be used to change them once created.  Subsequent use creates
              and updates operational settings that can be erased using a  factory  reset.   This
              option is executed after all others on the command line, except for the -R option.

       -i interface
              Select  the host Ethernet interface.  All requests are sent via this host interface
              and only reponses received via this host interface  are  recognized.   The  default
              interface  is  eth1  because  most  people  use  eth0  as  their  principle network
              connection;  however,  if  environment  string  "PLC"  is  defined  then  it  takes
              precedence  over  the  default  interface.   This option then takes precedence over
              either default.

       -I     Read the device PIB header using VS_MODULE_OPERATION and print the  PIB  major  and
              minor  revision  number, Device Access Key (DAK), Network Membership Key (NMK), MAC
              address and other identity information on stdout.   The  values  displayed  can  be
              changed using program modpib.

       -J xx:xx:xx:xx:xx:xx
              Set  the  Network  Membership  Key (NMK) on a remote device using VS_SET_KEY.  This
              option is similar to option -K but requires  the  remote  device  MAC  and  DAK  in
              addition  to  the NMK and local device MAC address.  The NMK value is defined using
              option -K unless you want to use the default value.   The  remote  DAK  is  defined
              using  option  -D  unless  you  want  to use the default value.  Programming remote
              device keys is complicated.  It is often easier to connect the device  directly  to
              the host and use the -K option.

       -K xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx
              Define  the  Network  Membership  Key  (NMK)  value  used by options -M or -J.  The
              symbolic names "key1" and "key2" are recognized as described in the KEY section.

       -l count
              Define the number of times that the  command  will  be  repeated  for  each  device
              specified.  Normally, you will repeat operations on one device only.

       -L     Read and display powerline link status.

       -m     Read  network  membership  information  using  VS_NW_INFO.   This  can  be  used to
              determine network configuration.

       -M     Set the Network Membership Key (NMK) on the local device using VS_SET_KEY.  The NMK
              value is specified using the -K option unless you want to use the default value.

       -n filename
              Read  firmware  from  the  device  SDRAM  and write it to the named .nvm file using
              multiple VS_RD_MOD messages.  No assumptions are made  based  on  filename  and  no
              filename  conventions are enforced.  This option is performed before option -N when
              both are specified.

       -N filename
              Read the named .nvm file and write  it  to  the  device  using  multiple  VS_WR_MOD
              messages.   No  assumptions  are made based on filename and no filename conventions
              are enforced; however, files having invalid .nvm format  will  be  rejected.   This
              option is executed after -n when both are specified.

       -p filename
              Read  parameters  from the device NVRAM and write them to the named .pib file using
              multiple VS_RD_MOD messages.  No assumptions are made  based  on  filename  and  no
              filename  convetions  are  enforced.  This option is executed before option BP when
              both are specified.

       -P filename
              Read the named .pib file and write  it  to  the  device  using  multiple  VS_WR_MOD
              messages.   No  assumptions  are made based on filename and no filename conventions
              are enforced; however, files having invalid .pib format  will  be  rejected.   This
              option is executed after -p when both are specified.

       -q     Suppresses status messages on stderr.

       -Q     Quick  flash.   The  program will not wait for a device to reset or the firmware to
              restart after writing flash memory.  This option is desirable with  newer  firmware
              that  writes  flash  memory  in  the background.  It has no effect unless used with
              option -F or -C.

       -r     Read device firmware and hardware revision using VS_SW_VER.  Output is  similar  to
              option -a but is derived differently.

       -R     Reset  the device using VS_RS_DEV.  This option is executed after all others on the
              same command line.

       -t milliseconds
              Read timeout in milliseconds.  Values range from 0 through UINT_MAX.  This  is  the
              maximum  time  allowed  for  a  response.   The default is shown in brackets on the
              program menu.

       -T     Restore factory defaults.  This permanently erases all PIB changes made  since  the
              device  was  last  programmed  with  factory  default  settings.   The  device will
              automatically reset and reboot.

       -v     Print additional information on stdout.  In particular, this option dumps  incoming
              and outgoing packets which can be saved as text files for reference.

       -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.

       -x     Cause the program to exit on the first error instead of continuing  with  remaining
              iterations,  operations or devices.  Normally, the program reports errors and moves
              on to the next operation, iteration or device depending on the command line.

       -?,--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 option when sending  screen  dumps  to
              Atheros  Technical  Support  so  that  they know exactly which version of the Linux
              Toolkit you are using.

ARGUMENTS

       device The Ethernet hardware address of some powerline device.  More than one address  may
              be  specified  on  the  command  line.   If more than one address is specified then
              operations are performed on each device in turn.  The default address is local.  as
              explained in the DEVICES section.

KEYS

       Passwords  are  variable  length  character strings that end-users can remember.  Keys are
       fixed length binary values created by encrypting  passwords.   There  are  two  encryption
       algorithms  for HomePlugAV.  One for DAKs and the other for NMKs.  This means that a given
       password will produce different keys depending on use.  This program only deals with  keys
       because  that  is what powerline devices recognize.  The passwords that generated the keys
       are irrelevant here.

       Encryption keys are tedious to type and prone to error.  For convenience,  symbolic  names
       have been assigned to common encryption keys and are recognized by options -D and -K.

       key1   Key       for       encrypted       password       "HomePlugAV".       This      is
              "689F074B8B0275A2710B0B5779AD1630"        for         option         -D         and
              "50D3E4933F855B7040784DF815AA8DB7" for option -K.

       key2   Key      for      encrypted      password      "HomePlugAV0123".       This      is
              "F084B4E8F6069FF1300C9BDB812367FF"        for         option         -D         and
              "B59319D7E8157BA001B018669CCEE30D" for option -K.

       none   Always "00000000000000000000000000000000".

DEVICES

       Powerline devices use Ethernet hardware, or Media Access Control (MAC), addresses.  Device
       addresses are 12 hexadecimal digits (0123456789ABCDEFabcdef)  in  upper,  lower  or  mixed
       case.   Individual octets may be separated by colons, for clarity, but not all octets need
       to be seperated.  For example, "00b052000001", "00:b0:52:00:00:01" and "00b052:000001" are
       valid and equivalent.

       These  symbolic  addresses  are  recognized by this program and may be used instead of the
       actual address value.

       all    Equivalent to "broadcast", described next.

       broadcast
              A synonym for the standard  Ethernet  broadcast  address,  FF:FF:FF:FF:FF:FF.   All
              devices, whether local, remote or foreign will respond to this address.

       local  A  synonym for the Qualcomm Atheros vendor specific Local Management Address (LMA),
              00:B0:52:00:00:01.  All local Atheros  devices  will  recognize  this  address  but
              remote  and foreign devices will 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  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 or  content
       in  future  firmware releases without any obligation to notify or compensate users of this
       program.

EXAMPLES

       The following command writew file QCA7000.pib and QCA7000.nvm to a remote powerline device
       then resets it.  The reset is required because reset after flash is no longer automatic.

          # plctool -P QCA7000.pib -N QCA7000.nvm -R 00B05201053E

       The  previous  command  does not replace existing PIB values.  Instead, it appends the new
       PIB values to the end of the old PIB.  To replace existing PIB values, you must write  the
       same PIB again, as follows.

          # plctool -P QCA7000.pib -R 00B05201053E

       The following commands do the same thing but avoid one unecessary reset.

          # plctool -P QCA7000.pib -N QCA7000.nvm 00B05201053E
          # plctool -P QCA7000.pib -R 00B05201053E

       The reset can also be postponed as follows.

          # plctool -P QCA7000.pib -N QCA7000.nvm 00B05201053E
          # plctool -P QCA7000.pib 00B05201053E
          # plctool -R 00B05201053E

       The  next  two  commands  are equivalent.  They set the NMK on the local device to key1 as
       descripted in the KEYS section.  The first command resets the NMK on the local device with
       -M  then  specifies the NMK as key1.  The second command omits the key specification since
       key1 is the program default NMK.  One could, of course, type the encryption key.

          # plctool -MK key1
          # plctool -M

SEE ALSO

       plc(1),  ampboot(1),   ampboot(1),   amphost(1),   int6kid(1),   amprate(1),   amprule(1),
       ampstat(1), ampwait(1)

CREDITS

        Charles Maier
        Nathaniel Houghton