cosmetic fix for docs/ prereq check

[openwrt/staging/wigyori.git] / docs / wireless.tex

diff --git a/docs/wireless.tex b/docs/wireless.tex
index 67be1d2aa0c31b1e5f72429cdf821c0f98f05955..bc9df11411d572c26b5d7f8ed7f109ea7fa5cda4 100644 (file)
--- a/docs/wireless.tex
+++ b/docs/wireless.tex
@@ -1,8 +1,14 @@
 The WiFi settings are configured in the file \texttt{/etc/config/wireless}
 The WiFi settings are configured in the file \texttt{/etc/config/wireless}

-(currently supported on Broadcom and Atheros). When booting the router for the first time
+(currently supported on Broadcom, Atheros and mac80211). When booting the router for the first time

 it should detect your card and create a sample configuration file. By default '\texttt{option network  lan}' is
 commented. This prevents unsecured sharing of the network over the wireless interface.
 
 it should detect your card and create a sample configuration file. By default '\texttt{option network  lan}' is
 commented. This prevents unsecured sharing of the network over the wireless interface.
 

+Each wireless driver has its own configuration script in \texttt{/lib/wifi/driver\_name.sh} which handles
+driver specific options and configurations. This script is also calling driver specific binaries like wlc for
+Broadcom, or hostapd and wpa\_supplicant for atheros.
+
+The reason for using such architecture, is that it abstracts the driver configuration. 
+

 \paragraph{Generic Broadcom wireless config:}
 
 \begin{Verbatim}
 \paragraph{Generic Broadcom wireless config:}
 
 \begin{Verbatim}


@@ -36,6 +42,22 @@ config wifi-iface
     option encryption   "none"
 \end{Verbatim}
 
     option encryption   "none"
 \end{Verbatim}
 

+\paragraph{Generic mac80211 wireless config:}
+
+\begin{Verbatim}
+config wifi-device      "wifi0"
+    option type         "mac80211"
+    option channel      "5"
+
+config wifi-iface
+    option device       "wlan0"
+#   option network  lan
+    option mode         "ap"
+    option ssid         "OpenWrt"
+    option hidden       "0"
+    option encryption   "none"
+\end{Verbatim}
+

 \paragraph{Generic multi-radio Atheros wireless config:}
 
 \begin{Verbatim}
 \paragraph{Generic multi-radio Atheros wireless config:}
 
 \begin{Verbatim}


@@ -72,7 +94,7 @@ A full outline of the wireless configuration file with description of each field
 
 \begin{Verbatim}
 config wifi-device     wifi device name
 
 \begin{Verbatim}
 config wifi-device     wifi device name

-    option type     broadcom, atheros
+    option type     broadcom, atheros, mac80211

     option country  us, uk, fr, de, etc.
     option channel  1-14
     option maxassoc 1-128 (broadcom only)
     option country  us, uk, fr, de, etc.
     option channel  1-14
     option maxassoc 1-128 (broadcom only)


@@ -82,7 +104,7 @@ config wifi-device     wifi device name
 config wifi-iface
     option network  the interface you want wifi to bridge with 
     option device   wifi0, wifi1, wifi2, wifiN
 config wifi-iface
     option network  the interface you want wifi to bridge with 
     option device   wifi0, wifi1, wifi2, wifiN

-    option mode     ap, sta, adhoc, or wds
+    option mode     ap, sta, adhoc, monitor, or wds

     option ssid     ssid name
     option bssid    bssid address
     option encryption none, wep, psk, psk2, wpa, wpa2 
     option ssid     ssid name
     option bssid    bssid address
     option encryption none, wep, psk, psk2, wpa, wpa2 


@@ -144,6 +166,9 @@ config wifi-iface
             \item \texttt{adhoc} \\
                 Ad-Hoc mode
 
             \item \texttt{adhoc} \\
                 Ad-Hoc mode
 

+            \item \texttt{monitor} \\
+                Monitor mode
+

             \item \texttt{wds} \\
                 WDS point-to-point link
 
             \item \texttt{wds} \\
                 WDS point-to-point link
 


@@ -175,7 +200,7 @@ config wifi-iface
         The RADIUS server ip address
 
     \item \texttt{port} (wpa) \\
         The RADIUS server ip address
 
     \item \texttt{port} (wpa) \\

-        The RADIUS server port
+        The RADIUS server port (defaults to 1812)

 
     \item \texttt{hidden} \\
         0 broadcasts the ssid; 1 disables broadcasting of the ssid
 
     \item \texttt{hidden} \\
         0 broadcasts the ssid; 1 disables broadcasting of the ssid


@@ -198,6 +223,7 @@ Only the following mode combinations are supported:
             \item 1x \texttt{sta}, 0-3x \texttt{ap}
             \item 1-4x \texttt{ap}
             \item 1x \texttt{adhoc}
             \item 1x \texttt{sta}, 0-3x \texttt{ap}
             \item 1-4x \texttt{ap}
             \item 1x \texttt{adhoc}

+            \item 1x \texttt{monitor}

         \end{itemize}
 
         WDS links can only be used in pure AP mode and cannot use WEP (except when sharing the
         \end{itemize}
 
         WDS links can only be used in pure AP mode and cannot use WEP (except when sharing the


@@ -205,8 +231,111 @@ Only the following mode combinations are supported:
 
     \item \textbf{Atheros}: \\
         \begin{itemize}
 
     \item \textbf{Atheros}: \\
         \begin{itemize}

-            \item 1x \texttt{sta}, 0-4x \texttt{ap}
-            \item 1-4x \texttt{ap}
+            \item 1x \texttt{sta}, 0-Nx \texttt{ap}
+            \item 1-Nx \texttt{ap}

             \item 1x \texttt{adhoc}
         \end{itemize}
             \item 1x \texttt{adhoc}
         \end{itemize}

+
+       N is the maximum number of VAPs that the module allows, it defaults to 4, but can be
+       changed by loading the module with the maxvaps=N parameter.
+\end{itemize}
+
+\paragraph{Adding a new driver configuration}
+
+Since we currently only support two different wireless drivers : Broadcom and Atheros,
+you might be interested in adding support for another driver like Ralink RT2x00, 
+Texas Instruments ACX100/111.
+
+The driver specific script should be placed in \texttt{/lib/wifi/<driver>.sh} and has to
+include several functions providing :
+
+\begin{itemize}
+       \item detection of the driver presence
+       \item enabling/disabling the wifi interface(s)
+       \item configuration reading and setting
+       \item third-party programs calling (nas, supplicant)

 \end{itemize}
 \end{itemize}

+
+Each driver script should append the driver to a global DRIVERS variable :
+
+\begin{Verbatim}
+append DRIVERS "driver name"
+\end{Verbatim}
+
+\subparagraph{\texttt{scan\_<driver>}}
+
+This function will parse the \texttt{/etc/config/wireless} and make sure there
+are no configuration incompatibilities, like enabling hidden SSIDS with ad-hoc mode
+for instance. This can be more complex if your driver supports a lof of configuration
+options. It does not change the state of the interface.
+
+Example:
+\begin{Verbatim}
+scan_dummy() {
+       local device="$1"
+
+       config_get vifs "$device" vifs
+       for vif in $vifs; do
+               # check config consistency for wifi-iface sections
+       done
+       # check mode combination
+}
+\end{Verbatim}
+
+\subparagraph{\texttt{enable\_<driver>}}
+
+This function will bring up the wifi device and optionally create application specific
+configuration files, e.g. for the WPA authenticator or supplicant.
+
+Example:
+\begin{Verbatim}
+enable_dummy() {
+       local device="$1"
+
+       config_get vifs "$device" vifs
+       for vif in $vifs; do
+               # bring up virtual interface belonging to
+               # the wifi-device "$device"
+       done
+}
+\end{Verbatim}
+
+\subparagraph{\texttt{disable\_<driver>}}
+
+This function will bring down the wifi device and all its virtual interfaces (if supported).
+
+Example:
+\begin{Verbatim}
+disable_dummy() {
+       local device="$1"
+
+       # bring down virtual interfaces belonging to
+       # "$device" regardless of whether they are
+       # configured or not. Don't rely on the vifs
+       # variable at this point
+}
+\end{Verbatim}
+
+\subparagraph{\texttt{detect\_<driver>}}
+
+This function looks for interfaces that are usable with the driver. Template config sections
+for new devices should be written to stdout. Must check for already existing config sections
+belonging to the interfaces before creating new templates.
+
+Example:
+\begin{Verbatim}
+detect_dummy() {
+       [ wifi-device = "$(config_get dummydev type)" ] && return 0
+       cat <<EOF
+config wifi-device dummydev
+       option type dummy
+       # REMOVE THIS LINE TO ENABLE WIFI:
+       option disabled 1
+
+config wifi-iface
+       option device dummydev
+       option mode ap
+       option ssid OpenWrt
+EOF
+}
+\end{Verbatim}