1.. _module_esp_8266:
2
3ESP-8266 Modules
4################
5
6Overview
7********
8
9ESP-8266 radio is a cost-effective Wi-Fi SOC module which allows any
10microcontrollers to easily access to WiFi network. This module supports
11the standard IEEE802.11 b/g/n protocol, built-in complete TCP/IP protocol
12stack. Users can use this series of modules to add networking capabilities
13to existing devices.
14
15The simplest module that uses ESP-8266 is ESP-01. This is a generic shield
16configuration that allows any ESP-8266 module variation including ESP-12E/F.
17
18.. image:: esp-01.jpg
19   :align: center
20   :alt: ESP-01
21
22Pins Assignment of the ESP-01 Module
23====================================
24
25+---------------+-------------------------------------+
26| Connector Pin | Function                            |
27+===============+=====================================+
28| GND           | POWER GND                           |
29+---------------+-------------------------------------+
30| GPIO1         | U0_TXD                              |
31+---------------+-------------------------------------+
32| GPIO2         |                                     |
33+---------------+-------------------------------------+
34| CHIP_EN       | ENABLE (VDD = RUN, GND = LOW POWER) |
35+---------------+-------------------------------------+
36| GPIO0         |                                     |
37+---------------+-------------------------------------+
38| EXT_RST       |                                     |
39+---------------+-------------------------------------+
40| GPIO3         | U0_RXD                              |
41+---------------+-------------------------------------+
42| VDD           | POWER +3.3V                         |
43+---------------+-------------------------------------+
44
45Requirements
46************
47
48This shield requires a board which provides a configuration that allows an
49UART interface. (see :ref:`shields` for more details).
50
51.. note::
52   Sometimes boards declare standard headers like Arduino R3 but not define
53   all connections.  Make sure that the board you are using have all
54   definitions to avoid build errors.
55
56The ESP-8266 should be loaded with the `ESP8266 AT Bin`_ software which is
57available at Espressif Systems web site. The ESP-01 module have up to 1MB of
58flash and the last available stack that fits on this device is ESP8266 AT Bin
59V1.6.2. This version is command compatible with ESP8266 AT Bin 1.7.x which is
60the minimal version supported by the ESP WIFI driver.
61
62The ESP-8266 Modules that have 2MB or more is highly recommended upgrade to
63version 1.7.x for better future compatibility.
64
65This tutorial won't explain how firmware must be upgraded. However, it will
66present some tips to easily success. The ESP WIFI was tested with an ESP-01
67with 1MB flash using Boot Mode and with Flash size 8Mbit: 512KB + 512KB. The
68ESP8266 AT Bin 1.7.x available requires the following partition configuration
69to works:
70
71.. image:: esp_at_173.jpg
72   :align: center
73   :alt: ESP8266 AT Bin V1.7.3
74
75- Tips
76
77        - Don't forget to erase Flash before upgrade
78        - Upgrade all binaries at same time.
79        - ESP-8266 bootloader won't send garbage. Try connect at 74880 bps if
80          you module have 26MHz crystal to detect boot fails.
81
82.. note::
83	Boards that already have a network interface:  Check network
84	documentation to understand how properly configure both interfaces.
85	To keep simple, make sure WiFi is the only interface enabled at
86	Networking -> Link Layer Options.  This will avoid problems running
87	Zephyr samples.
88
89Supported variations
90====================
91
92The below table suggests shield variation accordingly with end user
93application.  When a standard connector (arduino, mikrobus) is available on
94board, user should select the matching shield configuration. When esp_8266
95shield is used with a board that doesn't feature a standard connector, a
96dedicated <board>.overlay file should be provided.  The remaining
97configurations should be used based on the board standard headers available.
98
99+-----------------------------+------------------------------+-----------+
100| Connector Standard          | Shield Designation           | Variation |
101+=============================+==============================+===========+
102| Without standard (overlay)  | `esp_8266`_                  |     1     |
103+-----------------------------+------------------------------+-----------+
104| Arduino                     | `esp_8266_arduino`_          |     2     |
105+-----------------------------+------------------------------+-----------+
106| MikroBus                    | `esp_8266_mikrobus`_         |     3     |
107+-----------------------------+------------------------------+-----------+
108
109
110Build and Programming
111*********************
112
113Set ``--shield <shield designation>`` when you invoke ``west build``.
114
115To build shield with specific overlay:
116
117.. zephyr-app-commands::
118   :zephyr-app: samples/net/wifi
119   :board: sam4e_xpro
120   :shield: esp_8266
121   :goals: build flash
122
123To build shield with standard headers:
124
125.. zephyr-app-commands::
126   :zephyr-app: samples/net/wifi
127   :board: [disco_l475_iot1 | frdm_k64f | lpcxpresso55s69_ns | nucleo_f767zi]
128   :shield: [esp_8266_arduino | esp_8266_mikrobus]
129   :goals: build flash
130
131References
132**********
133
134.. target-notes::
135
136.. _ESP8266 AT Bin:
137   https://www.espressif.com/en/support/download/at
138
139.. _esp_8266:
140   https://github.com/zephyrproject-rtos/zephyr/blob/master/boards/shields/esp_8266/esp_8266.overlay
141
142.. _esp_8266_arduino:
143   https://github.com/zephyrproject-rtos/zephyr/blob/master/boards/shields/esp_8266/esp_8266_arduino.overlay
144
145.. _esp_8266_mikrobus:
146   https://github.com/zephyrproject-rtos/zephyr/blob/master/boards/shields/esp_8266/esp_8266_mikrobus.overlay
147