NAME

       plcID - Echo Device Key

SYNOPSIS

       plcID [options] [device] [device] [ ... ]

DESCRIPTION

       This  program  prints  a  single  powerline  device key or HFID on stdout.  It can be used to dynamically
       define environment variables or insert command line arguments in scripts at runtime.  It is  intended  to
       echo  a  specific  key read from a single device but it can be used to echo a specific key type read from
       several devices by specifying either the  Qualcomm  Atheros  Local  Management  Address  or  a  broadcast
       address.

       This  program  is,  in  some sense, the inverse of modpib but it reads the key and HFID directly from the
       powerline device instead of reading from a PIB file.

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

OPTIONS

       -A     Prints the Ethernet address (MAC) for each specified device.  This option and options -D, -M,  -N,
              -S and -U are mutually exclusive.

       -D     Prints the Device Access Key (DAK) for each specified device.  This option and options -A, -M, -N,
              -S and -U are mutually exclusive.

       -e     Redirects  stderr  messages  to  stdout.   By  convention 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.

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

       -n     Append  a  newline to the end of each key.  Newlines are omitted by default so that program output
              can be used as the raw input to another program.  If you want the newline then you must request it
              with this option.

       -M     Prints the Network Membership Key (NMK) for each specified device.  This option  and  options  -A,
              -D, -N, -S and -U are mutually exclusive.

       -N     Prints  the network HFID string for each specified device.  This option and options -A, -D, -M, -S
              and -U are mutually exclusive.

       -q     Suppresses status messages on stderr.

       -S     Prints the manufacturer HFID string for each specified device.  This option and  options  -A,  -D,
              -M, -N and -U are mutually exclusive.

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

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

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

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  valid  and
       equivalent.

       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.

EXAMPLES

       The following example prints the DAK of the local device on stdout.  The  local  device  is  interrogated
       because  no  MAC  address  was specified.  The default interface, eth1 on Linux and 2 on Windows, is used
       unless environment variable PLC is defined.  The DAK is always printed by  default.   Depending  on  your
       system, you may want to use option -n when using this program interactively.

          # plcID
          00:11:22:33:44:55:66:77:88:99:AA:DD:CC:DD:EE:FF

       The  following  example prints the NMK of device 00:B0:52:DA:DA:57 connected to interface eth2 on a Linux
       system.  Several devices could be specified but that is not a common request.

          # DAK -Mi eth2 00:B0:52:DA:DA:57
          F4:23:71:4A:51:39:C2:2D:E5:EA:87:43:99:A1:37:81

       The following example dynamically inserts the DAK and NMK of the previous device on the command  line  of
       another  program.  In this example, we want to insert the DAK and NMK into PIB file abc.pib using program
       modpib.  See the modpib man page for an explanation of command line syntax.  See the GNU bash manuals for
       an explanation of why this works.

          # modpib abc.pib -D $(plcID -Di eth2 00:B0:52:DA:DA:57) -N $(plcID -Mi eth2 00:B0:52:DA:DA:57)

       The following example is an alternate way of accomplishing the same thing using shell  script  variables.
       This  method  may be easier to read and maintain.  Notice that we 'squished' all the options together for
       brevity.

          # PLC=00:B0:52:DA:DA:57
          # DAK=$(plcID -Dieth2 ${PLC})
          # NMK=$(plcID -Mieth2 ${PLC})
          # modpib abc.pib -D ${DAK} -N ${NMK}

SEE ALSO

       plc(1), plcboot(1), plcinit(1), plctool(1)

CREDITS

        Charles Maier

open-plc-utils-0.0.3                              November 2013                                         plcID(1)