| 123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260 |
- <?xml version='1.0' encoding='iso-8859-1'?>
- <!doctype html public '-//W3C//DTD XHTML 1.0 Strict//EN' 'http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd'>
- <html xmlns='http://www.w3c.org/1999/xhtml' lang='en-us'>
- <head>
- <title>
- plctool.1
- </title>
- <meta http-equiv='content-type' content='text/html;iso-8859-1'/>
- <meta name='generator' content='motley-tools 1.9.4 13:40:33 Feb 18 2015'/>
- <meta name='author' content='cmaier@cmassoc.net'/>
- <meta name='robots' content='noindex,nofollow'/>
- <link href='toolkit.css' rel='stylesheet' type='text/css'/>
- </head>
- <body>
- <div class='headerlink'>
- [<a href='plctone.1.html' title=' plctone.1 '>PREV</a>]
- [<a href='toolkit.html' title=' Index '>HOME</a>]
- [<a href='plcwait.1.html' title=' plcwait.1 '>NEXT</a>]
- </div>
- <pre>
- plctool(1) Qualcomm Atheros Open Powerline Toolkit plctool(1)
- 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 ven‐
- dor-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 differ‐
- ently.
- -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 pro‐
- gram 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 can‐
- not 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.
- -g Read multicast group information discovered while IGMP snooping using VS_MULTICAST_INFO.
- -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 mem‐
- ory. 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 differ‐
- ently.
- -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 clar‐
- ity, 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 <cmaier@qca.qualcomm.com>
- Nathaniel Houghton <nhoughto@qca.qualcomm.com>
- open-plc-utils-0.0.3 Mar 2014 plctool(1)
- </pre>
- <div class='footerlink'>
- [<a href='plctone.1.html' title=' plctone.1 '>PREV</a>]
- [<a href='toolkit.html' title=' Index '>HOME</a>]
- [<a href='plcwait.1.html' title=' plcwait.1 '>NEXT</a>]
- </div>
- </body>
- </html>
|
