RIOT-OS/RIOT
RIOT-OS/RIOT
1
0
Fork 0
mirror of https://github.com/RIOT-OS/RIOT.git synced 2024-12-29 04:50:03 +01:00
Code Releases Activity
af89824cfd
RIOT/drivers/atwinc15x0/doc.txt
Mikolai Gütschow f0e6776d40
treewide: apply codespell corrections
2024-10-09 13:03:52 +02:00

175 lines
8.3 KiB
Plaintext
Raw Blame History

/*
* Copyright (C) 2020 Gunar Schorcht
*
* This file is subject to the terms and conditions of the GNU Lesser
* General Public License v2.1. See the file LICENSE in the top level
* directory for more details.
*/
/**
* @defgroup drivers_atwinc15x0 ATWINC15x0 WiFi module driver
* @ingroup drivers_netdev
* @brief Network device driver for the Microchip ATWINC15x0 WiFi Module
*
* @author Gunar Schorcht <gunar@schorcht.net>
### Introduction
This module implements a `netdev` device driver for the Microchip ATWINC15x0
WiFi module. The ATWINC15x0 WiFi module is widely used as WiFi interface on
various boards and extension boards. Examples are:
- [Adafruit Feather M0 WiFi](https://learn.adafruit.com/adafruit-feather-m0-wifi-atwinc1500/)
(also supported by [RIOT](https://doc.riot-os.org/group__boards__feather-m0.html))
- [ATWIN1500-XPRO](https://www.microchip.com/DevelopmentTools/ProductDetails/ATWINC1500-XPRO)
for the extension of Atmel Xplained PRO boards (also supported by RIOT)
- [Adafruit ATWINC1500 WiFi breakout](https://learn.adafruit.com/adafruit-atwinc1500-wifi-module-breakout)
- [Watterott ATWINC1500-Breakout](https://github.com/watterott/ATWINC1500-Breakout)
Since the ATWINC15x0 WiFi module is also the only module supported by the
standard [Arduino WiFi101 library](https://github.com/arduino-libraries/WiFi101),
there are a number of Arduino shields with the ATWINC15x0 WiFi module, e.g.
[Adafruit WINC1500 WiFi Shield for Arduino](https://learn.adafruit.com/adafruit-winc1500-wifi-shield-for-arduino).
Using this 'netdev' driver together with an ATWINC15x0 WiFi module enables
the connection via WiFi in RIOT.
### Microchip ATWINC15x0 WiFi module
The ATWINC15x0 WiFi module is a low-power IEEE 802.11 b/g/n module with a
bandwidth of 20 MHz in the 2,4 GHz ISM band. It supports the IEEE 802.11i/WPA2
personal and enterprise modes. In enterprise mode it supports
- EAP-TLS
- EAP-PEAPv0/1 with TLS
- EAP-TTLSv0 with MSCHAPv2
- EAP-PEAPv0/1 with MSCHAPv2
The WiFi module ATWINC15x0 is connected via SPI and supports SPI clock speeds
of up to 48 MHz. Although the module also has an I2C and a UART interface,
these interfaces are only used for debugging.
The ATWINC15x0 WiFi module implements a complete TCP/IP protocol stack which is
not used in RIOT.
### Driver Details
The ATWINC15x0 WiFi `netdev` driver doesn't directly use the ATWINC15x0 WiFi
module. Instead, it uses the ATWINC15x0 vendor driver
[WINC1500 Wifi](http://asf.atmel.com/docs/latest/sam4s/html/group__winc1500__group.html).
from Microchip's Advanced Software Framework. For that purpose, the
[Arduino WiFi101 library](https://github.com/arduino-libraries/WiFi101) which
also includes this vendor library is used as a package.
Although the ATWINC15x0 vendor driver is complex and quite large, there is
no other way to do it because the ATWINC15x0 WiFi module's programming
interface is not documented. At the very least, the ATWINC15x0 WiFi `netdev`
driver uses only those parts of the vendor driver that are absolutely
necessary.
The ATWINC15x0 vendor driver consists of several parts:
- the M2M WiFi library, which implements high-level WiFi connection management
Functions
- the HIF (Host Interface) library, which implements the interface with the
ATWINC15x0 module
- the BSP (Bus Support Package) as an abstraction layer for platform-specific
Functions
- the bus wrapper interface for access to the SPI
In addition to these parts, the ATWINC15x0 vendor driver contains a
socket library and a library for accessing the SPI flash of the ATWINC15x0
module, but these are not used in RIOT.
The ATWINC15x0 WiFi `netdev` driver replaces the BSP and the Bus Wrapper
Interface by RIOT specific parts and interacts with ATWINC15x0 vendor driver
as shown in the following figure.
```
+-----------------+ +---------------+ +----------+ +------------+
| RIOT ATWINC15x0 | | ATWINC15x0 | | RIOT Bus | | ATWINC15x0 |
| netdev driver | | vendor driver | | Wrapper | | module |
+-----------------+ +---------------+ +----------+ +------------+
| | | |
| m2m_wifi_func | command | SPI(command) |
|------------------------->|--------------->|--------------->|
| return | | |
|<-------------------------| | |
| | | |
| | | |
| | | |
|<------------------------------- IRQ -----------------------|
| | | |
| m2m_wifi_handle_events | request | SPI(request) |
|------------------------->|--------------->|--------------->|
| | response | SPI(response) |
| atwinc15x0_wifi_cb |<---------------|<---------------|
|<-------------------------| | |
| | | |
| | | |
| | | |
| | | |
|<------------------------------- IRQ -----------------------|
| | | |
| m2m_wifi_handle_events | request | SPI(request) |
|------------------------->|--------------->|--------------->|
| | response | SPI(response) |
| atwinc15x0_eth_cb |<---------------|<---------------|
|<-------------------------| | |
```
As shown, the ATWINC15x0 WiFi module operates asynchronously. This means
that when an API function of the ATWINC15x0 driver is called, it simply
sends a command to the ATWINC15x0 WiFi module and returns immediately.
The command is then executed asynchronously by the ATWINC15x0 WiFi module.
As soon as the execution of the command is completed or one or more events
are pending, the module interrupts the host. Since the ISR is executed in
the interrupt context, the ATWINC15x0 'netdev' driver simply indicates
that an interrupt has occurred. The interrupt is handled later in the
thread context by calling 'm2m_wifi_handle_events'. This in turn fetches
available information from the ATWINC15x0 WiFi module and then calls
various callback functions according to the state, all of which are
executed in the thread context.
## Configuration
The ATWINC15x0 'netdev' driver requires the configuration ATWINC15x0 WiFi
module as WiFi settings:
### Hardware Configuration
The default configuration is defined in atwinc15x0_params.h and can be
overridden either by the board definition or by environment variables in
make command line.
Symbol | Default | Description
:------------------------------|:-----------------|:---------------------
`ATWINC15X0_PARAM_SPI` | `SPI_DEV(0)` | Used SPI device
`ATWINC15X0_PARAM_SPI_CLK` | `SPI_CLK_10MHZ` | Used SPI clock speed
`ATWINC15X0_PARAM_SSN_PIN` | `GPIO_PIN(1, 4)` | SPI slave select pin
`ATWINC15X0_PARAM_RESET_PIN` | `GPIO_PIN(4, 3)` | `RESET` pin
`ATWINC15X0_PARAM_IRQ_PIN` | `GPIO_PIN(7, 4)` | `IRQ` pin
`ATWINC15X0_PARAM_CHIP_EN_PIN` | `GPIO_UNDEF` | `CHIP_EN` pin
`ATWINC15X0_PARAM_WAKE_PIN` | `GPIO_UNDEF` | WAKE pin
### WiFi Configuration
At the moment only WPA2 Personal Mode is supported. The required settings are:
Parameter | Default | Description
:---------|:----------|:------------
WIFI_SSID | "RIOT_AP" | SSID of the AP to be used.
WIFI_PASS | - | Passphrase used for the AP as clear text (max. 64 chars).
The following example shows the make command with the setting of different GPIOs and the WiFi parameters.
```
USEMODULE='atwinc15x0' \
CFLAGS='-DWIFI_SSID=\"ssid\" -DWIFI_PASS=\"pass\" \
-DATWINC15X0_PARAM_SSN_PIN=GPIO_PIN\(1,6\) \
-DATWINC15X0_PARAM_RESET_PIN=GPIO_PIN\(1,4\) \
-DATWINC15X0_PARAM_IRQ_PIN=GPIO_PIN\(0,8\)' \
make BOARD=... -C examples/gnrc_networking flash term
```
*/
View Git Blame Copy Permalink