1---
2title: Getting started with MicroPython and ESP8266
3url: esp8266-and-micropython-guide.html
4date: 2020-09-06T12:00:00+02:00
5type: post
6draft: false
7---
8
9## Introduction
10
11A while ago I bought some
12[ESP8266](https://www.espressif.com/en/products/socs/esp8266) and
13[ESP32](https://www.espressif.com/en/products/socs/esp32) dev boards to play
14around with and I finally found a project to try it out.
15
16For my project, I used [ESP32](https://www.espressif.com/en/products/socs/esp32)
17but I could easily choose
18[ESP8266](https://www.espressif.com/en/products/socs/esp8266). This guide
19contains which tools I use and how I prepared my workspace to code for
20[ESP8266](https://www.espressif.com/en/products/socs/esp8266).
21
22
23
24This guide covers:
25
26- flashing SOC
27- install proper tooling
28- deploying a simple script
29
30> Make sure that you are using **a good USB cable**. I had some problems with
31mine and once I replaced it everything started to work.
32
33## Flashing the SOC
34
35Plug your ESP8266 to USB port and check if the device was recognized with
36executing `dmesg | grep ch341-uart`.
37
38Then check if the device is available under `/dev/` by running `ls
39/dev/ttyUSB*`.
40
41> **Linux users**: if a device is not available be sure you are in `dialout`
42> group. You can check this by executing `groups $USER`. You can add a user to
43> `dialout` group with `sudo adduser $USER dialout`.
44
45After these conditions are meet go to the navigate to
46[https://micropython.org/download/esp8266/](https://micropython.org/download/esp8266/)
47and download `esp8266-20200902-v1.13.bin`.
48
49```sh
50mkdir esp8266-test
51cd esp8266-test
52
53wget https://micropython.org/resources/firmware/esp8266-20200902-v1.13.bin
54```
55
56After obtaining firmware we will need some tooling to flash the firmware to the
57board.
58
59```sh
60sudo pip3 install esptool
61```
62
63You can read more about `esptool` at
64[https://github.com/espressif/esptool/](https://github.com/espressif/esptool/).
65
66Before flashing the firmware we need to erase the flash on device. Substitute
67`USB0` with the device listed in output of `ls /dev/ttyUSB*`.
68
69```sh
70esptool.py --port /dev/ttyUSB0 erase_flash
71```
72
73If flash was successfully erased it is now time to flash the new firmware to it.
74
75```sh
76esptool.py --port /dev/ttyUSB0 --baud 460800 write_flash --flash_size=detect 0 esp8266-20200902-v1.13.bin
77```
78
79If everything went ok you can try accessing MicroPython REPL with ` screen
80/dev/ttyUSB0 115200` or `picocom /dev/ttyUSB0 -b115200`.
81
82> Sometimes you will need to press `ENTER` in `screen` or `picocom` to access
83> REPL.
84
85When you are in REPL you can test if all is working properly following steps.
86
87```py
88> import machine
89> machine.freq()
90```
91
92This should output a number representing a frequency of the CPU (mine was
93`80000000`).
94
95When you are in `screen` or `picocom` these can help you a bit.
96
97| Key | Command |
98| -------- | -------------------- |
99| CTRL+d | preforms soft reboot |
100| CTRL+a x | exits picocom |
101| CTRL+a \ | exits screen |
102
103
104## Install better tooling
105
106Now, to make our lives a little bit easier there are couple of additional tools
107that will make this whole experience a little more bearable.
108
109There are twq cool ways of uploading local files to SOC flash.
110
111- ampy → [https://github.com/scientifichackers/ampy](https://github.com/scientifichackers/ampy)
112- rshell → [https://github.com/dhylands/rshell](https://github.com/dhylands/rshell)
113
114### ampy
115
116```bash
117# installing ampy
118sudo pip3 install adafruit-ampy
119```
120
121Listed below are some common commands I used.
122
123```bash
124# uploads file to flash
125ampy --delay 2 --port /dev/ttyUSB0 put boot.py
126
127# lists file on flash
128ampy --delay 2 --port /dev/ttyUSB0 ls
129
130# outputs contents of file on flash
131ampy --delay 2 --port /dev/ttyUSB0 cat boot.py
132```
133
134> I added `delay` of 2 seconds because I had problems with executing commands.
135
136### rshell
137
138Even though `ampy` is a cool tool I opted with `rshell` in the end since it's
139much more polished and feature rich.
140
141```bash
142# installing ampy
143sudo pip3 install rshell
144```
145
146Now that `rshell` is installed we can connect to the board.
147
148```bash
149rshell --buffer-size=30 -p /dev/ttyUSB0 -a
150```
151
152This will open a shell inside bash and from here you can execute multiple
153commands. You can check what is supported with `help` once you are inside of a
154shell.
155
156```bash
157m@turing ~/Junk/esp8266-test
158$ rshell --buffer-size=30 -p /dev/ttyUSB0 -a
159
160Using buffer-size of 30
161Connecting to /dev/ttyUSB0 (buffer-size 30)...
162Trying to connect to REPL connected
163Testing if ubinascii.unhexlify exists ... Y
164Retrieving root directories ... /boot.py/
165Setting time ... Sep 06, 2020 23:54:28
166Evaluating board_name ... pyboard
167Retrieving time epoch ... Jan 01, 2000
168Welcome to rshell. Use Control-D (or the exit command) to exit rshell.
169/home/m/Junk/esp8266-test> help
170
171Documented commands (type help <topic>):
172========================================
173args cat connect date edit filesize help mkdir rm shell
174boards cd cp echo exit filetype ls repl rsync
175
176Use Control-D (or the exit command) to exit rshell.
177```
178
179> Inside a shell `ls` will display list of files on your machine. To get list
180> of files on flash folder `/pyboard` is remapped inside the shell. To list files
181> on flash you must perform `ls /pyboard`.
182
183#### Moving files to flash
184
185To avoid copying files all the time I used `rsync` function from the inside of
186`rshell`.
187
188```bash
189rsync . /pyboard
190```
191
192#### Executing scripts
193
194It is a pain to continuously reboot the device to trigger `/pyboard/boot.py` and
195there is a better way of testing local scripts on remote device.
196
197Lets assume we have `src/freq.py` file that displays CPU frequency of a remote
198device.
199
200```py
201# src/freq.py
202
203import machine
204print(machine.freq())
205```
206
207Now lets upload this and execute it.
208
209```bash
210# syncs files to remove device
211rsync ./src /pyboard
212
213# goes into REPL
214repl
215
216# we import file by importing it without .py extension and this will run the script
217> import freq
218
219# CTRL+x will exit REPL
220```
221
222## Additional resources
223
224- https://randomnerdtutorials.com/getting-started-micropython-esp32-esp8266/
225- http://docs.micropython.org/en/latest/esp8266/quickref.html