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