Skip to content

Commit 879bc41

Browse files
dpgeorgedpgeorge
committed
docs/esp8266: Add ESP8266 tutorial.
1 parent 5e94f0b commit 879bc41

13 files changed

Lines changed: 960 additions & 1 deletion

File tree

‎docs/esp8266/tutorial/adc.rst‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
Analog to Digital Conversion
2+
============================
3+
4+
The ESP8266 has a single pin (separate to the GPIO pins) which can be used to
5+
read analog voltages and convert them to a digital value. You can construct
6+
such an ADC pin object using::
7+
8+
>>> import machine
9+
>>> adc = machine.ADC(0)
10+
11+
Then read its value with::
12+
13+
>>> adc.read()
14+
58
15+
16+
The values returned from the ``read()`` function are between 0 (for 0.0 volts)
17+
and 1024 (for 1.0 volts). Please note that this input can only tolerate a
18+
maximum of 1.0 volts and you must use a voltage divider circuit to measure
19+
larger voltages.

‎docs/esp8266/tutorial/filesystem.rst‎

Lines changed: 70 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,70 @@
1+
The internal filesystem
2+
=======================
3+
4+
If your devices has 1Mbyte or more of storage then it will be set up (upon first
5+
boot) to contain a filesystem. This filesystem uses the FAT format and is
6+
stored in the flash after the MicroPython firmware.
7+
8+
Creating and reading files
9+
--------------------------
10+
11+
MicroPython on the ESP8266 supports the standard way of accessing files in
12+
Python, using the built-in ``open()`` function.
13+
14+
To create a file try::
15+
16+
>>> f = open('data.txt', 'w')
17+
>>> f.write('some data')
18+
9
19+
>>> f.close()
20+
21+
The "9" is the number of bytes that were written with the ``write()`` method.
22+
Then you can read back the contents of this new file using::
23+
24+
>>> f = open('data.txt')
25+
>>> f.read()
26+
'some data'
27+
>>> f.close()
28+
29+
Note that the default mode when opening a file is to open it in read-only mode,
30+
and as a text file. Specify ``'wb'`` as the second argument to ``open()`` to
31+
open for writing in binary mode, and ``'rb'`` to open for reading in binary
32+
mode.
33+
34+
Listing file and more
35+
---------------------
36+
37+
The os module can be used for further control over the filesystem. First
38+
import the module::
39+
40+
>>> import os
41+
42+
Then try listing the contents of the filesystem::
43+
44+
>>> os.listdir()
45+
['boot.py', 'port_config.py', 'data.txt']
46+
47+
You can make directories::
48+
49+
>>> os.mkdir('dir')
50+
51+
And remove entries::
52+
53+
>>> os.remove('data.txt')
54+
55+
Start up scripts
56+
----------------
57+
58+
There are two files that are treated specially by the ESP8266 when it starts up:
59+
boot.py and main.py. The boot.py script is executed first (if it exists) and
60+
then once it completes the main.py script is executed. You can create these
61+
files yourself and populate them with the code that you want to run when the
62+
device starts up.
63+
64+
Accessing the filesystem via WebREPL
65+
------------------------------------
66+
67+
You can access the filesystem over WebREPL using the provided command-line
68+
tool. This tool is found at `<https://github.com/micropython/webrepl>`__
69+
and is called webrepl_cli.py. Please refer to that program for information
70+
on how to use it.

‎docs/esp8266/tutorial/index.rst‎

Lines changed: 27 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,4 +3,30 @@
33
MicroPython tutorial for ESP8266
44
================================
55

6-
TBD
6+
This tutorial is intended to get you started using MicroPython on the ESP8266
7+
system-on-a-chip. If it is your first time it is recommended to follow the
8+
tutorial through in the order below. Otherwise the sections are mostly self
9+
contained, so feel free to skip to those that interest you.
10+
11+
The tutorial does not assume that you know Python, but it also does not attempt
12+
to explain any of the details of the Python language. Instead it provides you
13+
with commands that are ready to run, and hopes that you will gain a bit of
14+
Python knowledge along the way. To learn more about Python itself please refer
15+
to `<https://www.python.org>`__.
16+
17+
.. toctree::
18+
:maxdepth: 1
19+
:numbered:
20+
21+
intro.rst
22+
repl.rst
23+
filesystem.rst
24+
network_basics.rst
25+
network_tcp.rst
26+
pins.rst
27+
pwm.rst
28+
adc.rst
29+
powerctrl.rst
30+
onewire.rst
31+
neopixel.rst
32+
nextsteps.rst

‎docs/esp8266/tutorial/intro.rst‎

Lines changed: 95 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,95 @@
1+
Introduction to MicroPython on the ESP8266
2+
==========================================
3+
4+
Using MicroPython is a great way to get the most of your ESP8266 board. And
5+
vice versa, the ESP8266 chip is a great platform for using MicroPython. This
6+
tutorial will guide you through setting up MicroPython, getting a prompt, using
7+
WebREPL, connecting to the network and communicating with the Internet, using
8+
the hardware peripherals, and controlling some external components.
9+
10+
Let's get started!
11+
12+
Requirements
13+
------------
14+
15+
The first thing you need is a board with an ESP8266 chip. The MicroPython
16+
software supports the ESP8266 chip itself and any board should work. The main
17+
characteristic of a board is how much flash it has, how the GPIO pins are
18+
connected to the outside world, and whether it includes a built-in USB-serial
19+
convertor to make the UART available to your PC.
20+
21+
The minimum requirement for flash size is 512k. A board with this amount of
22+
flash will not have room for a filesystem, but otherwise is fully functional.
23+
If your board has 1Mbyte or more of flash then it will support a filesystem.
24+
25+
Names of pins will be given in this tutorial using the chip names (eg GPIO0)
26+
and it should be straightforward to find which pin this corresponds to on your
27+
particular board.
28+
29+
Powering the board
30+
------------------
31+
32+
If your board has a USB connector on it then most likely it is powered through
33+
this when connected to your PC. Otherwise you will need to power it directly.
34+
Please refer to the documentation for your board for further details.
35+
36+
Deploying the firmware
37+
----------------------
38+
39+
The very first thing you need to do is put the MicroPython firmware (compiled
40+
code) on your ESP8266 device. There are two main steps to do this: first you
41+
need to put your device in boot-loader mode, and second you need to copy across
42+
the firmware. The exact procedure for these steps is highly dependent on the
43+
particular board and you will need to refer to its documentation for details.
44+
45+
If you have a board that has a USB connector, a USB-serial convertor, and has
46+
the DTR and RTS pins wired in a special way then deploying the firmware should
47+
be easy as all steps can be done automatically. Boards that have such features
48+
include the Adafruit Feather HUZZAH and NodeMCU boards.
49+
50+
For best results it is recommended to first erase the entire flash of your
51+
device before putting on new MicroPython firmware.
52+
53+
Currently we only support esptool.py to copy across the firmware. You can find
54+
this tool here: `<https://github.com/themadinventor/esptool/>`__ . Any other
55+
flashing program should work, so feel free to try them out, or refer to the
56+
documentation for your board to see its recommendations.
57+
58+
Using esptool.py you can erase the flash with the command::
59+
60+
esptool.py --port /dev/ttyUSB0 erase_flash
61+
62+
And then deploy the new firmware using::
63+
64+
esptool.py --port /dev/ttyUSB0 --baud 460800 write_flash --flash_size=8m 0 mp-esp8266-firmware.bin
65+
66+
You might need to change the "port" setting to something else relevant for your
67+
PC. You may also need to reduce the baudrate if you get errors when flashing
68+
(eg down to 115200).
69+
70+
If you have a NodeMCU board, you may need to use the following command to deploy
71+
the firmware (note the "-fm dio" option)::
72+
73+
esptool.py --port /dev/ttyUSB0 --baud 460800 write_flash --flash_size=8m -fm dio 0 mp-esp8266-firmware.bin
74+
75+
If the above commands run without error then MicroPython should be installed on
76+
your board!
77+
78+
Serial prompt
79+
-------------
80+
81+
Once you have the firmware on the device you can access the REPL (Python prompt)
82+
over UART0 (GPIO1=TX, GPIO3=RX), which might be connected to a USB-serial
83+
convertor, depending on your board. The baudrate is 115200. The next part of
84+
the tutorial will discuss the prompt in more detail.
85+
86+
WiFi
87+
----
88+
89+
After a fresh install and boot the device configures itself as a WiFi access
90+
point (AP) that you can connect to. The ESSID is of the form MicroPython-xxxxxx
91+
where the x's are replaced with part of the MAC address of your device (so will
92+
be the same everytime, and most likely different for all ESP8266 chips). The
93+
password for the WiFi is micropythoN (note the upper-case N). Its IP address
94+
will be 192.168.4.1 once you connect to its network. WiFi configuration will
95+
be discussed in more detail later in the tutorial.

‎docs/esp8266/tutorial/neopixel.rst‎

Lines changed: 70 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,70 @@
1+
Controlling NeoPixels
2+
=====================
3+
4+
NeoPixels, also known as WS2812 LEDs, are full-colour LEDs that are connected in
5+
serial, are individually addressable, and can have their red, green and blue
6+
components set between 0 and 255. They require precise timing to control them
7+
and there is a special neopixel module to do just this.
8+
9+
To create a NeoPixel object do the following::
10+
11+
>>> import machine, neopixel
12+
>>> np = neopixel.NeoPixel(machine.Pin(4), 8)
13+
14+
This configures a NeoPixel strip on GPIO4 with 8 pixels. You can adjust the
15+
"4" (pin number) and the "8" (number of pixel) to suit your set up.
16+
17+
To set the colour of pixels use::
18+
19+
>>> np[0] = (255, 0, 0) # set to red, full brightness
20+
>>> np[1] = (0, 128, 0) # set to green, half brightness
21+
>>> np[2] = (0, 0, 64) # set to blue, quarter brightness
22+
23+
Then use the ``write()`` method to output the colours to the LEDs::
24+
25+
>>> np.write()
26+
27+
The following demo function makes a fancy show on the LEDs::
28+
29+
import time
30+
31+
def demo(np):
32+
n = np.n
33+
34+
# cycle
35+
for i in range(4 * n):
36+
for j in range(n):
37+
np[j] = (0, 0, 0)
38+
np[i % n] = (255, 255, 255)
39+
np.write()
40+
time.sleep_ms(25)
41+
42+
# bounce
43+
for i in range(4 * n):
44+
for j in range(n):
45+
np[j] = (0, 0, 128)
46+
if (i // n) % 2 == 0:
47+
np[i % n] = (0, 0, 0)
48+
else:
49+
np[n - 1 - (i % n)] = (0, 0, 0)
50+
np.write()
51+
time.sleep_ms(60)
52+
53+
# fade in/out
54+
for i in range(0, 4 * 256, 8):
55+
for j in range(n):
56+
if (i // 256) % 2 == 0:
57+
val = i & 0xff
58+
else:
59+
val = 255 - (i & 0xff)
60+
np[j] = (val, 0, 0)
61+
np.write()
62+
63+
# clear
64+
for i in range(n):
65+
np[i] = (0, 0, 0)
66+
np.write()
67+
68+
Execute it using::
69+
70+
>>> demo(np)

‎docs/esp8266/tutorial/network_basics.rst‎

Lines changed: 81 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,81 @@
1+
Network basics
2+
==============
3+
4+
The network module is used to configure the WiFi connection. There are two WiFi
5+
interfaces, one for the station (when the ESP8266 connects to a router) and one
6+
for the access point (for other devices to connect to the ESP8266). Create
7+
instances of these objects using::
8+
9+
>>> import network
10+
>>> sta_if = network.WLAN(network.STA_IF)
11+
>>> ap_if = network.WLAN(network.AP_IF)
12+
13+
You can check if the interfaces are active by::
14+
15+
>>> sta_if.active()
16+
False
17+
>>> ap_if.active()
18+
True
19+
20+
You can also check the network settings of the interface by::
21+
22+
>>> ap.ifconfig()
23+
('192.168.4.1', '255.255.255.0', '192.168.4.1', '8.8.8.8')
24+
25+
The returned values are: IP address, netmask, gateway, DNS.
26+
27+
Configuration of the WiFi
28+
-------------------------
29+
30+
Upon a fresh install the ESP8266 is configured in access point mode, so the
31+
AP_IF interface is active and the STA_IF interface is inactive. You can
32+
configure the module to connect to your own network using the STA_IF interface.
33+
34+
First activate the station interface::
35+
36+
>>> sta_if.active(True)
37+
38+
Then connect to your WiFi network::
39+
40+
>>> sta_if.connect('<your ESSID>', '<your password>')
41+
42+
To check if the connection is established use::
43+
44+
>>> sta_if.isconnected()
45+
46+
Once established you can check the IP address::
47+
48+
>>> sta_if.ifconfig()
49+
('192.168.0.2', '255.255.255.0', '192.168.0.1', '8.8.8.8')
50+
51+
You can then disable the access-point interface if you no longer need it::
52+
53+
>>> ap_if.active(False)
54+
55+
Here is a function you can run (or put in your boot.py file) to automatically
56+
connect to your WiFi network::
57+
58+
def do_connect():
59+
import network
60+
sta_if = network.WLAN(network.STA_IF)
61+
if not sta_if.isconnected():
62+
print('connecting to network...')
63+
sta_if.active(True)
64+
sta_if.connect('<essid>', '<password>')
65+
while not network.isconnected():
66+
pass
67+
print('network config:', sta_if.ifconfig())
68+
69+
Sockets
70+
-------
71+
72+
Once the WiFi is set up the way to access the network is by using sockets.
73+
A socket represents an endpoint on a network device, and when two sockets are
74+
connected together communication can proceed.
75+
Internet protocols are built on top of sockets, such as email (SMTP), the web
76+
(HTTP), telnet, ssh, among many others. Each of these protocols is assigned
77+
a specific port, which is just an integer. Given an IP address and a port
78+
number you can connect to a remote device and start talking with it.
79+
80+
The next part of the tutorial discusses how to use sockets to do some common
81+
and useful network tasks.

0 commit comments

Comments
 (0)