jammy (8) faifa.8.gz

Provided by: faifa_0.2~svn82-2build1_amd64 bug

NAME

       faifa - configure HomePlug 1.0/AV devices

SYNOPSIS

       faifa [OPTIONS]
       -i   specify network interface to use
       -m   show the menu asking for known MM types
       -a   destination MAC address to send frames to
       -k   network key to set
       -v   be verbose (default: no)
       -e   set error stream (default: stderr)
       -o   set output stream (default: stdout)
       -s   set input stream (default: stdin)
       -h   show the usage

DESCRIPTION

       faifa  can  configure any Intellon-based PowerLine Communication device using the Intellon
       INT5000 and INT6000 HomePlug  AV  (200Mbits)  chips.  It  supports  all  Intellon-specific
       management and control frames.

       -i   specify network interface to use
       -m   show the menu asking for known MM types
       -a   destination MAC address to send frames to
       -k   network key to set
       -v   be verbose (default: no)
       -e   set error stream (default: stderr)
       -o   set output stream (default: stdout)
       -s   set input stream (default: stdin)
       -h   show the usage

       HomePlug AV protocol

              The  HomePlug AV protocol was developed by Intellon and specifies how the powerline
              PHY layer and HPAV MAC layer can converge to allow Ethernet frames to  be  sent  on
              the medium. It handles all the low-level modulation and constellation building plus
              the Medium Access Control  handling  between  devices.   The  HomePlug  AV  network
              topology  consists of one coordinator (called CCo) for a given logical HPAV network
              (i.e: with the same Network Encryption Key) and none or  several  stations  (called
              STAs).  Other  devices  can have a specific role which is a bridge, between several
              logical networks.

              ------------------------------------
              | HomePlug PHY                     |
              ------------------------------------
              | HomePlug MAC convergence layer   |
              ------------------------------------
              | Ethernet MAC layer               |
              ------------------------------------

              It is possible to configure the  HPAV  MAC  convergence  layer  by  using  specific
              Ethernet  frames  with the 0x88e1 Ethertype. Such frames will be interpreted by the
              Intellon controller present in the devices and are known as control  or  management
              frames.

              Such   frames   can   be   either  protocol  specific  (i.e:  common  to  all  HPAV
              implementations) or vendor specific. There is no convention to specify  whether  an
              HPAV   configuration   and  management  frame  is  vendor  specific  or  not.  Most
              implementations will share a  common  format  for  basic  network  operations  like
              setting the Network Management Key or the Encryption Key.

              A HomePlug AV management frame is described below :

                   8 bits         16 bits
              ---------------------------------------------------
              | MM version |           MM type                  |
              ---------------------------------------------------
              |         OUI (24 bits)                           |
              ---------------------------------------------------
              |         Payload   (var)                         |
              ---------------------------------------------------

              The  payload is highly dependent on the implementation though most vendors will try
              to define a common template for it. Such management frame should be encapsulated in
              standard ethernet frames with the 0x88e1 ethertype.

              Faifa operations

              Faifa basically performs 3 main operations :

              - send all vendor and protocol specific frames with the corresponding parameters
              - dump all vendor and HomePlug 1.0/AV frames with the appropriate frame parsing
              - discover the HPAV network topology

              The  available  vendor  specific  operations  are  stored  in  an  array  of struct
              hpav_frame_ops. For each entry the mmtype and the description  is  specified,  with
              possible callbacks to handle frame initialization and dump function.

              Using the faifa library

              Faifa  is  also provided as shared library (so file) and static library so that you
              can link programs with  to  send  HomePlug  AV  frames.  The  library  allows  you,
              specifying a given mmtype to send the corresponding HPAV frame to a given device.

              Linking with faifa

              You  should  include faifa.h into your C source file and then you can directly call
              functions that are provided by the faifa  library.  When  linking  with  the  faifa
              library,  make sure your linker flags include "-lfaifa" or the absolute path of the
              shared object to make sure your program will successfully link.

              Sending frames using do_frame

              The main function you want  to  call  is  do_frame  and  pass  it  the  MMtype  and
              destination MAC address you want to send the frame to. This function will :

              - lookup the mmtype by reading the array containing available frame operations
              -  initialize  the  frame  header  (MM  version,  type,  source and destination MAC
              addresses)
              - call the initialisation function (if needed) to let the user input the parameters
              (or any other input method)
              - calculate the appropriate frame size
              - send it to the device
              - close the network socket descriptor

              This  function  propagates  the  return  code  from the write command on the socket
              descriptor.

              Receiving frames using do_receive_frame

              This function will listen for received frames on the specified interface and will :

              - check that the ethertype is set to 0x88e1 otherwise it will discard the frame
              - cast the received packet to an HPAV management frame structure
              - lookup for the received MM type into the arrays of known response/indications
              - call the frame parsing function (based on the mmtype) accordingly

              You will probably want to set the network descriptor in reading mode  non-blocking.
              Faifa  uses  this  function  with  a  call to a pcap_loop method inside a dedicated
              thread to receive all frames.

SEE ALSO

       ifconfig(8)

AUTHORS

       Florian  Fainelli  <florian@openwrt.org>,  Xavier  Carcelle   <xavier.carcelle@gmail.com>,
       Nicolas Thill <nico@openwrt.org>