FAIFA(8)

💖 FAIFA — the faifa(8) manual but make it cute 💖

okay bestie, sit down, hydrate, and let me tell you about faifa — the configure HomePlug 1.0/AV devices girlie. this is the User manual page for section 8 (system administration commands, iykyk), and she is lowkey iconic. ✨

---

🌸 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 ✨

so here's the tea: faifa can configure any Intellon-based PowerLine Communication device using the Intellon INT5000 and INT6000 HomePlug AV (200Mbits) chips. she supports all Intellon-specific management and control frames. no crumbs left. 💅

---

🦋 MENU COMMANDS 🦋

• -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. literally doing the most. 😮‍💨

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. main character energy fr fr. 🌉

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

---

💜 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. she's organized, she's got a whole array. 💅

---

🌈 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. so you can absolutely make this your whole personality in your own C project. 🫶

---

🍓 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. do not skip this step, bestie, the linker will simply not slay. 😤

---

🧚 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. so like, check your return codes, it's giving responsible. 💀

---

👑 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. threads! pcap! the drama of it all. 🔥

---

🌸 SEE ALSO 🌸

• ifconfig(8)

---

💖 AUTHORS 💖

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

---

okay that's the whole page, bestie, you ate that. 🫶 this one shipped on Linux back in April 2011 as part of the FAIFA(8) manual — shoutout to the og authors for writing it, and shoutout to you for reading all the way to the end. no cap, that's dedication. 💜✨🎀