Provided by: plc-utils-extra_0.0.6+git20230504.1ba7d5a0-1_amd64 bug

NAME

       int6kwait - Qualcomm Atheros INT6x00 Powerline Device Procrastinator

SYNOPSIS

       int6kwait [options] [device] [device] [...]

DESCRIPTION

       Poll  a  Qualcomm Atheros powerline device, waiting for one or more events to occur before
       continuing or returning.  The events include reset or power off, restart or power  on  and
       network  association.  It is used to pause shell scripts at critical points where a device
       must be in a known state before continuing.

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

OPTIONS

       -a     Poll  the  device  every  few  seconds  using  VS_NW_INFO messages until the device
              indicates that a networks exists and has at least one  station.   This  option  can
              give  false readings if other devices have dropped off-line and the device bridging
              table still holds information about them.  The program always checks for this event
              last if other event options are specified.

       -c count
              The  number  of  times  the  program will poll the device before declaring an event
              failure.  The program will wait a fixed period of time between each  poll  attempt.
              Overall  wait  time is count/frequency where count can be modified using option -c.
              Overall wait time is always approximate since operating system overhead and latency
              are not taken into account.  The default count is 300.

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

       -f firmware
              The  identification  string  for  firmware  that should be running after the device
              starts.  This option can be used to detect a failed firmware load.  If  the  actual
              identification  string does not match this one once the device starts then an error
              is reported.  If option -x is present then the program terminates with  a  non-zero
              exit   code.   This  option  has  no  effect  unless  option  -s  is  present.   An
              identification string looks like  "INT6000-MAC-3-1-3143-1690-20071107-FINAL-B"  and
              can be obtained using int6k -r.

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

       -p frequency
              The polling frequency expressed in polls-per-second.  For example, 1 means one poll
              per second and 10 means ten polls per second.  Overall wait time is count/frequency
              where count may  be  modified  using  option  -c.   Overall  wait  time  is  always
              approximate since operating system overhead and latency are not taken into account.
              The default frequency is 5.

       -q     Enter quiet mode.  Progress messages are suppressed.

       -r     Poll the device every few seconds using VS_SW_VER messages until the bootloader  or
              runtime  firmware  fails  to  respond or the poll count exhausts.  The absence of a
              response indicates that the device either lost connection to the host,  lost  power
              or has reset.  The program always checks for this event first when other events are
              specified.

       -R     Reset the device then check return status.  Exit program on error if option  -x  is
              present;  otherwise,  repeat  the reset request until the device either accepts the
              request or the wait time is exceeded.

       -s     Poll the device every few seconds using VS_SW_VER messages until the bootloader  or
              runtime  firmware  responds or the poll count exhausts.  The presence of a response
              indicates that the device has either connected  to  the  host,  received  power  or
              finished reboot.

       -t     Display  the  actual time in seconds taken for successful completion, or waited for
              unsuccessful completion, of ecah event.

       -v     Enter verbose mode.  All Etherenet frames sent  or  received  by  the  program  are
              displayed on stdout.

       -w seconds
              Additional  time to wait once all events have occured.  This wait does not occur if
              any of the events timeout.  When no other  events  are  specified  this  option  is
              effectively  equivalent  to  sleep.  This option can be used to allow the device or
              the network to settle.  For example, a nominal 5 second wait is recommended after a
              device successfully associates before attempting to transfer data.

       -x     Exit  program  on  first error with a non-zero exit code.  This option allows shell
              scripts to detect failed or incomplete operations and take the appropriate action.

       -?, --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 Media Access Control (MAC) address of some device.  Addresses are 6 hexadecimal
              octets  optionally  separated by colon.  For example, the addresses "00b052000001",
              "00:b0:52:00:00:01"  and  "00b052:000001"  are  all  valid  and  equivalent.    For
              convenience,  the  symbolic address "local" resolves to "00:b0:52:00:00:01" and the
              symbolic addresses "all" and "broadcast" both resolve to "ff:ff:ff:ff:ff:ff".

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  command polls the local device until firmware stops running then polls the
       device until firmware starts running again.  This command can be  inserted  into  a  shell
       script at a point where the device must reset and reboot before proceeding.  Observer that
       the program waits up to 60 seconds for each event, in turn.  The 60 seconds is the product
       of 60 poll attempts spaced 1 second apart.

          # int6kwait -rs
          eth0 00:B0:52:BA:BA:01 Allow 60 seconds for Reset
          eth0 00:B0:52:BA:BA:01 Allow 60 seconds for Start

       The  following  example  specifies 5 poll attempts spaced 10 seconds apart.  Less frequent
       polling reduces network traffic but makes the program less responsive to events.   Observe
       that the allotted time applies to each event in turn.

          # int6kwait -rs -p 10 -c 5
          eth0 00:B0:52:BA:BA:01 Allow 50 seconds for Reset
          eth0 00:B0:52:BA:BA:01 Allow 50 seconds for Start

       The next example reports the actual amount of time taken for each event to occur.  Observe
       that the last event, device association, did not occur within the allotted time.

          # int6kwait -rsat
          eth0 00:B0:52:BA:BA:01 Allow 60 seconds for Reset
          etho 00:B0:52:BA:BA:01 Waited 22 seconds to Reset
          eth0 00:B0:52:BA:BA:01 Allow 60 seconds for Start
          etho 00:B0:52:BA:BA:01 Waited 4 seconds to Start
          eth0 00:B0:52:BA:BA:01 Allow 60 seconds for Assoc
          etho 00:B0:52:BA:BA:01 Waited 60 seconds for Assoc
          etho 00:B0:52:BA:BA:01 Device did not Assoc

       The following example  illustrates  use  of  the  revision  string  to  detect  mismatched
       firmware.   In this example, we reset the device first, using program int6k, then wait for
       it to reset then start up again.  There are also operation that can cause  the  device  to
       reset.

          # int6k -R
          # int6kwait -xrsf INT6000-MAC-3-1-3143-1690-20071107-FINAL-B
          eth0 00:B0:52:BA:BA:01 Device started wrong firmware

       Immediately after a reset we wait for the firmware to stop responding, with option -r, and
       then start responding, with option -s, and then perform a string  comparison  against  the
       actual  firmware  revision  string,  with  option -f.  If the strings do not match then an
       error is reported.  In this case, the program will exit with a non-zero return code  since
       option -x is present.

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.

SEE ALSO

       plc(1),   int6k(1),   int6kf(1),  int6khost(1),  int6kid(1),  int6krate(1),  int6krule(1),
       int6kstat(1)

CREDITS

        Charles Maier