NAME

       ampID - Echo Device Key

SYNOPSIS

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

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

          # ampID
          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 $(ampID -Di eth2 00:B0:52:DA:DA:57) -N $(ampID -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=$(ampID -Dieth2 ${PLC})
          # NMK=$(ampID -Mieth2 ${PLC})
          # modpib abc.pib -D ${DAK} -N ${NMK}

SEE ALSO

       plc(1), amptool(1), ampboot(1), ampinit(1), modpib(1)

CREDITS

        Charles Maier

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