\documentclass[aspectratio=169,obeyspaces,spaces,hyphens,dvipsnames]{beamer}
\usepackage[utf8]{inputenc}
\usepackage{lmodern}% http://ctan.org/pkg/lm
\usepackage{minted}
\usepackage{hyperref}
\usepackage{xcolor}
\usepackage{pgfplots}
\usepackage{tikz}
\usepackage[normalem]{ulem}

\mode<presentation>
\usetheme{Bootlin}

\def\signed #1{{\leavevmode\unskip\nobreak\hfil\penalty50\hskip2em
  \hbox{}\nobreak\hfil(#1)
  \parfillskip=0pt \finalhyphendemerits=0 \endgraf}}

\newsavebox\mybox
\newenvironment{aquote}[1]
  {\savebox\mybox{#1}\begin{quotation}}
  {\signed{\usebox\mybox}\end{quotation}}

\title{Improving IEEE 802.15.4 MAC management support}
\authors{Miquel Raynal}
\email{miquel.raynal@bootlin.com}
\slidesurl{https://bootlin.com/pub/conferences/}
\institute{Bootlin}
\conference{Embedded Linux Conference, Fall 2022}

\begin{document}

\addtocontents{toc}{\protect\setcounter{tocdepth}{-1}}
\section{Improving \\IEEE 802.15.4 MAC management support in the Linux kernel}
\addtocontents{toc}{\protect\setcounter{tocdepth}{2}}

\begin{frame}{Miquel Raynal}
  \begin{itemize}
  \item Embedded Linux engineer at Bootlin
    \begin{itemize}
    \item Embedded Linux {\bf expertise}
    \item {\bf Development}, consulting and training
    \item Strong open-source focus
    \end{itemize}
  \item Open-source contributor
    \begin{itemize}
    \item Maintainer of the NAND subsystem
    \item Co-maintainer of the MTD subsystem
    \item Kernel support for various ARM SoCs
    \item {\bf Active contributor to the WPAN subsystem} with Qorvo support
    \end{itemize}
  \item Living in {\bf Toulouse}, France
  \end{itemize}
\end{frame}

\subsection{A walk through the IEEE 802.15.4 specification}

\begin{frame}{Functional description}
  \begin{columns}
    \column{0.5\textwidth}
    \begin{itemize}
    \item Defines the PHY layer and the MAC sublayer
    \item Introduced to build Wireless Personal Area Networks (WPAN)
    \item Low power, low range (10m), low rate (up to 250kib/s)
    \item Easy connection between sensors and actuators
      \begin {itemize}
      \item home automation
      \item infrastructure monitoring
      \item medical body area
      \item RFID tags tracking
      \item ...
      \end{itemize}
    \item A base for Zigbee and 6LowPan
    \end{itemize}
    \column{0.5\textwidth}
    \begin{center}
      \includegraphics[width=0.9\textwidth]{osi.pdf}
                      {\tiny\break IEEE 802.15.4 stack integration in the OSI model}
    \end{center}
  \end{columns}
\end{frame}

\begin{frame}{The PHY layer}
  The PHY layer manages:
  \begin{columns}
    \column{0.5\textwidth}
    \begin{itemize}
    \item Channel switches across multiple frequency bands
    \item Energy Detection (ED)
      % Occupied channels
      % Free timeslot research
    \item Medium Access\\ {\footnotesize CSMA-CA, TSCH-CCA, LECIM ALOHA...}
      % Carrier Sense Multiple Access - Collision Avoidance
    \item Transmitting/receiving packets
    \item Link Quality Indicators (LQI)
    \item Physical data encoding\\ {\footnotesize O-QPSK, BPSK, GFSK,...}
    \item Ranging (UWB PHYs only)
    \end{itemize}
    \column{0.6\textwidth}
    \begin{itemize}
    \item Encapsulating payloads into\\PHY Protocol Data Units (PPDU)
    \end{itemize}
    \begin{center}
      \includegraphics[width=1\textwidth]{psdu.png}
                      {\tiny IEEE 802.15.4 specification screenshot}
    \end{center}
  \end{columns}
\end{frame}

\begin{frame}{The MAC sublayer}
  The MAC sublayer offers:
  \begin{columns}
    \column{0.6\textwidth}
    \begin{itemize}
    \item MAC data services
      \begin{itemize}
      \item Encapsulating payloads into\\MAC Protocol Data Units (MPDU)
      \end{itemize}
    \end{itemize}
    \begin{center}
      \includegraphics[width=1\textwidth]{mpdu.png}
                      {\tiny IEEE 802.15.4 specification screenshot}
    \end{center}
    \column{0.5\textwidth}
    \begin{itemize}
    \item MAC management services through the use of the MAC subLayer Management Entity (MLME):
      \begin{itemize}
      \item Channel choice
      \item Frames validation
      \item Beacon and scan management
      \item Associations/dis-associations
      \item Security mechanisms
      \item Acknowledgments
      \end{itemize}
    \end{itemize}
  \end{columns}
\end{frame}

\begin{frame}{RFD vs. FFD}
  \begin{itemize}
  \item Reduced Function Device (RFD)
    \begin{itemize}
    \item Limited devices, usually just able to send a few bytes of data and return to sleep
    \item Typically battery powered
    \item Possibly only working in Rx or only in Tx
    \item Leaf nodes in a network
    \end{itemize}
    \vfill
  \item Full Function Device (FFD)
    \begin{itemize}
    \item Expected to support much more features
    \item Typically mains powered
    \item Either coordinators or leaf nodes
      \begin{itemize}
      \item Coordinators provide synchronization services
      \end{itemize}
    \end{itemize}
  \end{itemize}
\end{frame}

\begin{frame}{Personal Area Networks (PAN)}
  Several networks can live together on the same channel thanks to PAN IDs.
  \begin{itemize}
  \item If a coordinator does not detect any surrounding PAN or decides to create its own, it may start a PAN and act as PAN coordinator:
    \begin{itemize}
    \item Picking a PAN ID (16-bit), apparently unused
    \item Picking a short address (16-bit)
    \end{itemize}
  \item Maintaining the PAN
    \begin{itemize}
    \item Advertising the PAN to the surrounding devices
    \item Allowing devices to associate
      \begin{itemize}
      \item Possibly allocating short addresses
      \item Can handover the ``PAN coordinator'' role
      \end{itemize}
    \end{itemize}
  \end{itemize}
\end{frame}

\begin{frame}{Discovery}
  \begin{itemize}
  \item Coordinators and PAN coordinators shall advertise their PAN by sending beacons
    \begin{itemize}
    \item Either upon reception of a \code{BEACON REQUEST}
    \item Or ``passively'' at a given rate, in beacon-enabled PANs
    \end{itemize}
  \item Beacons are short frames with information about the emitting device and its PAN
  \end{itemize}
  \begin{columns}
    \column{0.5\textwidth}
    \begin{itemize}
    \item Devices can scan the various channels they support
      \begin{itemize}
      \item Energy Detection (ED) scans to know which channels are used
      \item Passive scans to detect surrounding beacon enabled PANs with their LQI
      \item Active scans to detect surrounding beacon and non-beacon enabled PANs with their LQI
      \end{itemize}
    \end{itemize}
    \column{0.5\textwidth}
    \begin{center}
    \includegraphics[width=0.8\textwidth]{alex-network.png}
                    {\tiny \\Alexandre Belloni's IEEE 802.15.4 based home network}
    \end{center}
  \end{columns}
\end{frame}

\begin{frame}{Beacon enabled PANs}
  Beacons enabled PANs are more energy efficient, because they allow battery powered devices to synchronize:
  \begin{itemize}
    \item Beacon are sent at a fixed rate, the beacon interval, based on the beacon order
    \item A beacon transmission starts a superframe
      \begin{itemize}
      \item Superframe duration depend on the superframe order, advertised in the beacon
      \item The superframe is the active portion between each beacon
      \item The remaining part is the inactive portion, when radios can be turned off
      \end{itemize}
  \end{itemize}
  \begin{columns}
    \column{0.5\textwidth}
    Superframes are divided into time sections, themselves divided into timeslots
    \begin{itemize}
    \item The Contention Aware Period (CAP):\\ {\small devices compete for the medium access}
    \item The Contention Free Period (CFP):\\ {\small Guaranteed Time Slots (GTS) for critical and low-latency devices}
    \end{itemize}
    \code{ACK}s are unslotted (answered immediately)
    \column{0.5\textwidth}
    \begin{center}
      \includegraphics[width=1\textwidth]{bi.png}
                      {\tiny IEEE 802.15.4 specification screenshot}
    \end{center}
  \end{columns}
  %Enhanced Beacon frames -> useful for advances features such as channel hopping timings and parameters, or additional filtering
\end{frame}

\begin{frame}{Hardware filtering}
  \begin{itemize}
  \item A device can be addressed either with:
    \begin{itemize}
    \item its extended address (8 bytes)
    \item its short address (2 bytes) if part of a PAN
    \item the broadcast address
    \end{itemize}
  \item Most transceivers are capable of different hardware filtering levels defined by the specification:
    \begin{itemize}
    \item no filtering
    \item promiscuous mode (checks the frame integrity only)
    \item address filters (checks the frame validity)
    \end{itemize}
  \item These address filters must be kept in sync with the device association state
  \end{itemize}
  Caution: the linux-wpan community used the word ``promiscuous'' differently: to define the total absence of filtering, with sniffing interfaces in mind
  % All devices are not capable of all filtering levels, so we need to keep track of the desired filtering level for each interface on a single PHY, apply the lowest one by hardware and compensate by software. The hardware may not be capable of achieving the desired level, software filtering shall take over in this case.
\end{frame}

\begin{frame}{MLME operations}
  \begin{itemize}
  \item MAC management commands
    \begin{itemize}
    \item Discovering surrounding devices
    \item Enlarging/shrinking the network
    \item Keeping all devices synchronized
    \item Handling faulty situations (loss of contact, conflicts, etc)
    \end{itemize}
  \end{itemize}
\end{frame}

\begin{frame}{Scanning}
  \begin{itemize}
  \item Any device may enter scan mode upon MLME request
    \begin{itemize}
    \item Transmissions shall be paused
    \item Use of a specific filter mode
      \begin{itemize}
      \item Only beacon frames are accepted
      \item Beacons have no destination field
      \end{itemize}
    \item The MLME request specifies the channels to scan
    \item Scanning a channel involves waiting for a known period of time
    \end{itemize}
  \item Beacon frames sent by other coordinators with their information must be parsed and forwarded to the upper layers
    \begin{itemize}
    \item Devices build this way a list of the surrounding coordinators
    \item Parameters like the LQI during beacon reception may be used to pick the right coordinator to associate with
    \end{itemize}
  \end{itemize}
\end{frame}

\begin{frame}{Associations}
  In order to create networks, devices shall associate with each other
  \begin{itemize}
  \item Associations can be attempted by RFD and FFD devices
    \vfill
    \includegraphics[height=0.5\textheight]{association.pdf}
    \vfill
  \item \code{ASSOCIATION RESPONSE} payload:
    \begin{itemize}
    \item Status: Success, PAN coordinator at capacity, PAN coordinator rejected the request
    \item Short address (0xFFFE if not requested)
    \end{itemize}
  \end{itemize}
\end{frame}

\begin{frame}{Dis-associations}
  \begin{itemize}
  \item Usable by both the parent and the child
    \begin{itemize}
    \item The coordinator can inform a child that it has been kicked out
    \end{itemize}
    \begin{center}
      \includegraphics[height=0.2\textheight]{homer-bye.jpg}
    \end{center}
    \vfill
    \begin{itemize}
    \item A child may inform the coordinator that it leaves
    \end{itemize}
    \begin{center}
      \includegraphics[height=0.2\textheight]{homer-leaving.png}
    \end{center}
    \vfill
  \item In both cases, address filters must be updated
  \end{itemize}
\end{frame}

\begin{frame}{PAN ID conflicts}
  \begin{itemize}
  \item Two situations may lead to a PAN ID conflict
    \begin{itemize}
    \item The PAN coordinator receives a beacon from another coordinator
    \item The other coordinator says it is the PAN coordinator
    \end{itemize}
  \item or
    \begin{itemize}
    \item Any node in the network receiving beacons with the PAN coordinator bit set from a node that is not its known PAN coordinator
    \item A \code{CONFLICT NOTIFICATION} command must be sent
    \end{itemize}
  \item Upon detection of a conflict, the concerned PAN controller should resolve the situation by:
    \begin{itemize}
    \item Scanning for an available channel/PAN ID
    \item Send a \code{COORDINATOR REALIGNMENT} command
    \end{itemize}
  \end{itemize}
\end{frame}

\begin{frame}{Internal realignments}
  \begin{itemize}
  \item Devices receiving a \code{COORDINATOR REALIGNMENT} command shall:
    \begin{itemize}
    \item Change their internal parameters (PAN Information Base, PIB)
    \item Follow the channel/PAN ID change
    \item Except TSCH devices
      \begin{itemize}
      \item Channel hoping is part of their common actions
      \item They can safely ignore the realignment commands
      \end{itemize}
    \end{itemize}
  \item Devices loosing the sync with their coordinator (no more \code{ACK}s?) shall
    \begin{itemize}
    \item Iterate over all their supported channels
    \item Generate \code{ORPHAN NOTIFICATIONS}
    \item Expect a \code{COORDINATOR REALIGNMENT} from the coordinator which recognized the orphaned device in return
    \item Otherwise look for a new coordinator
    \end{itemize}
  \end{itemize}
\end{frame}

\subsection{The Linux kernel IEEE 802.15.4 stack}

\begin{frame}{Architecture}
  \begin{center}
    \includegraphics[height=0.85\textheight]{linux-stack.pdf}
  \end{center}
\end{frame}

\begin{frame}{Hardware offloading}
  Most supported devices in Linux are bare transceivers driven by the softMAC layer (single exception). These transceivers may usually perform some of the MAC operations by hardware:
  \begin{itemize}
  \item Frame validation
    \begin{itemize}
    \item Depend on the configuration of the address filters
      \begin{itemize}
      \item short address, extended address, PAN ID
      \end{itemize}
    \item A promiscuous mode is usually available to bypass the filters upon request
    \item Other filtering levels are described by the specification
    \end{itemize}
  \item Acknowledgment
    \begin{itemize}
    \item Time critical operation
    \item Done only if:
      \begin{itemize}
      \item The frame passes the filters
      \item The frame has the \code{Acknowledgment Request} (AR) bit enabled
      \item Not disabled by the user
      \end{itemize}
    \end{itemize}
  \end{itemize}
\end{frame}

\begin{frame}{Current state of the support}
  \begin{itemize}
  \item Defining networks and addresses can only be done statically:
    \begin{itemize}
    \item PAN ID and short address can be manually set
    \item No discovery/no dynamic network management
    \item The administrator shall provide a static list of devices and their addresses
    \item The PAN ID shall be picked-up in advance
    \end{itemize}
  \item But...
    \begin{itemize}
    \item Devices can move, appear, disappear
    \item Static descriptions are no longer relevant
    \end{itemize}
  \item Need for a dynamic way to discover the peers around and possibly associate with them dynamically as well
    \begin{itemize}
    \item There are MAC commands for that!
    \end{itemize}
  \end{itemize}
\end{frame}

\begin{frame}{The scanning interface 1/2}
  Trigger: netlink user request with:
  \begin{itemize}
  \item The type of scan: passive? active? ED?
  \item The range of channels to scan, possibly the page
  \item The duration (Beacon Interval, BI)
  \end{itemize}
  The request will be forwarded to the MAC layer:
  \begin{itemize}
  \item The Tx traffic on the interface is stopped
  \item The Tx queue gets flushed
  \item The hardware filters must be configured for the scan
    \begin{itemize}
    \item Any non-beacon frame gets dropped
    \end{itemize}
  \item A background thread is started
  \end{itemize}
\end{frame}

\begin{frame}{The scanning interface 2/2}
  \begin{itemize}
  \item The background thread shall:
    \begin{itemize}
    \item Iterate over all the requested channels
    \item Send \code{BEACON REQUEST}s during active scans (only)
    \item Wait for incoming beacons
    \end{itemize}
  \item Upon reception, the Rx logic will:
    \begin{itemize}
    \item Check the beacon validity
    \item Forward its content to the upper layers
    \end{itemize}
  \item Scans can be aborted at any moment
  \item An end of scan information is sent back to the user
  \item The interface is set back in its original state
  \end{itemize}
\end{frame}

\begin{frame}{The beaconing interface}
  Trigger: netlink user request with:
  \begin{itemize}
  \item The duration (Beacon Interval)
    \begin{itemize}
    \item The maximum duration is 15
    \item 15 means beacons are only sent upon \code{BEACON REQUEST}s
    \item Otherwise the sending rate is not impacted by \code{BEACON REQUEST}s
    \end{itemize}
  \item A delayed background job is started
  \item Can be modified or stopped at any moment
  \end{itemize}
\end{frame}

\begin{frame}[fragile]{iwpan -h}
  \begin{block}{}
    \fontsize{9}{9}\selectfont
    \begin{minted}{shell}
iwpan dev <devname> scan type <type> [page <page>]
                                     [channels <bitfield>]
                                     [duration <duration-order>]
iwpan dev <devname> scan trigger type <type> [page <page>]
                                             [channels <bitfield>]
                                             [duration <duration-order>]
iwpan dev <devname> scan abort

iwpan dev <devname> beacons send [interval <interval-order>]
iwpan dev <devname> beacons stop

iwpan monitor [-t|-r] [-f]
    \end{minted}
  \end{block}
\end{frame}

\begin{frame}{Associating}
  \begin{itemize}
  \item The list of devices in our range is now known
    \begin{itemize}
    \item Their LQI as well
    \end{itemize}
  \item Upper layers may device to associate with an available coordinator
    \begin{itemize}
      \item User to provide a PAN ID and coordinator address to connect to
    \end{itemize}
  \item The request is translated to the MAC layer which will:
    \begin{itemize}
    \item Change the address filters to accept the new PAN ID
    \item Send an \code{ASSOCIATION REQUEST} and wait for it to be \code{ACK}ed
    \end{itemize}
  \item The peer coordinator shall answer with an \code{ASSOCIATION RESPONSE}
  \item Upon reception the frame is parsed:
    \begin{itemize}
    \item In the payload, a status indicates whether the association is successful
    \item If yes and if requested, a short address to use is also provided
    \end{itemize}
  \item Address filters shall again be updated to match the new short address
  \item The parent device is saved for future reference
  \end{itemize}
\end{frame}

\begin{frame}{Processing associations requests}
  \begin{itemize}
  \item Associations can be refused for two reasons:
    \begin{itemize}
    \item The maximum number of devices is reached
      \begin{itemize}
      \item Return a \code{PAN AT CAPACITY} status
      \item Configurable with a netlink command
      \end{itemize}
    \item We do not want this device in our network
      \begin{itemize}
      \item Not highly time critical, the question can be asked to userspace
      \item API not implemented yet, currently we allow all associations
      \end{itemize}
    \item A list of associated devices must be maintained
    \end{itemize}
  \end{itemize}
\end{frame}

\begin{frame}{Disassociation notifications}
  \begin{itemize}
  \item Both ends can notify a disassociation
  \item The user must provide the peer address (short or long)
  \item An \code{ACK} is expected from the remote device
    \begin{itemize}
    \item Choice in the code: assume the device disassociated anyway
    \end{itemize}
  \end{itemize}
\end{frame}

\begin{frame}[fragile]{iwpan -h}
  \begin{block}{}
    \fontsize{9}{9}\selectfont
    \begin{minted}{shell}
iwpan dev <devname> associate pan_id <pan_id> coord <coord>
iwpan dev <devname> disassociate short_addr|ext_addr <addr>
iwpan dev <devname> list_associations
iwpan dev <devname> set max_associations <max_associations>
    \end{minted}
  \end{block}
\end{frame}

\begin{frame}{Upstream proposals, discussions ongoing}
  \begin{itemize}
  \item Kernel patches:
    \begin{itemize}
    \item v2 {\tiny\url{https://lore.kernel.org/all/20220826144049.256134-1-miquel.raynal@bootlin.com/}}
    \item v3/only filtering {\tiny\url{https://lore.kernel.org/all/20220905203412.1322947-1-miquel.raynal@bootlin.com/}}
    \item Latest version {\tiny\url{https://github.com/miquelraynal/linux/tree/wpan-next/scan}}
    \end{itemize}
  \item wpan-tools patches:
    \begin{itemize}
    \item Last patches {\tiny\url{https://lore.kernel.org/all/20220701143434.1267864-1-miquel.raynal@bootlin.com/}}
    \item Latest version {\tiny\url{https://github.com/miquelraynal/wpan-tools/tree/wpan-master/scan}}
    \end{itemize}
  \item Zephyr changes {\tiny\url{https://github.com/zephyrproject-rtos/zephyr/pull/49947}}
  \end{itemize}
  No support for orphan notifications/coordinator realignments yet
\end{frame}

\begin{frame}{Live wild: demo time!}
  Hardware setup:
  \begin{itemize}
  \item One ATUSB device acting like a PAN coordinator (wpan0/coord0)
  \item One ATUSB device acting like a node (wpan1/coord1)
  \item One ATUSB device monitoring (wpan2/mon2)
  \item One Arduino Nano 33 BLE running Zephyr being a leaf node
  \end{itemize}
  \begin{center}
    \includegraphics[height=0.5\textheight]{hw.jpg}
  \end{center}
\end{frame}

\questionslide

\end{document}
