    ampID(1)                                     Qualcomm Atheros Open Powerline Toolkit                                    ampID(1)

    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 sin‐
           gle  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 mutu‐
                  ally 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 hexa‐
           decimal 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 mes‐
           sage  structure and content in future firmware releases without any obligation to notify or compensate users of this pro‐
           gram.

    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 <cmaier@qca.qualcomm.com>

    open-plc-utils-0.0.3                                        Mar 2014                                                    ampID(1)

[PREV] [HOME] [NEXT]