• A quick word
• Installing MicroPython
  • Serial connections
  • Connections over wi-fi

As said the home automation platform I have chose for this project is Home Assistant and, for what concerns this tutorial, I will assume you have a working installation of it.More precisely I installed Hass.io (a dedicated OS) on my raspberry pi 3.Just to be on the safe side I will also give you some information on hoe I did set up the MQTT server.Home Assistant is written in Python but this does not mean that the code for devices like our sensor has to be written in Python. It can be in any language you want, as long as it support the functionalities we are interested in, namely:

INSTALLING MICROPYTHON 

 

We want to start with an update system so we can be sure that our Pi or other Linux machine (I am using a laptop with Ubuntu) is up to date with the following command

$ sudo apt-get update && sudo apt-get upgrade

To install MicroPython on the ESP we will use ‘esptool’. In order to do this we type the following in the terminal. In my case I have Python 3.

$ sudo pip3 install esptool

We then connect our use-serial adapter and we want to find its location. We use

$ dmesg | grep ttyUSB

You should get something like:

[ 11.263101] usb 1-1.4: cp210x converter now attached to ttyUSB0

showing the location of our converter equipped with cp201x. The part you are interested is “ttyUSB0” which may be different in your case.

Until this point I have been literally following the excellent tutorial by Rototron but, as Rototron’s tutorial is assuming the use of ESP32 and I am using ESP8266-01, a little diversion is needed.

You need the ESP8266 to be in flash mode, which I obtain linking the ‘EN’ pin to the 3V and the ‘IO0’  pin to the GND.
(If in doubt look at the flash configuration in Build the sensor).

Important note
Now – with the hope of avoiding you hours of frustration – an important thing I found about ESP8266-01, at least with the USB-serial converter I use: it likes to be disconnected and reconnected, a lot (everyone has perversions). If it is already been plugged in the USB port for a while and you try to communicate with it your attempt will often fail. But if you disconnect it, reconnect and you are ready with your command on the terminal and immediately hit Enter, chances are higher that it will work.

This applies also to the next command, used to check that you ESP is in flash mode, that everything is fine and to know a bit more about our controller.

$ esptool.py --port /dev/ttyUSB0 flash_id

We want a clean ESP8266 and to get that we run

$ esptool.py --port /dev/ttyUSB0 erase_flash

Again this operation may, if it fails otherway, benefit of the unplug-replug cycle I was just talking about.

Ta-da!, it is time to install MicroPython and, at this point, I will also make frequent reference to the official documentation.

After you downloaded you copy of the firmware from http://micropython.org/download#esp8266 you can install it using the following command line (obviously using the name of the release you are using).

$ sudo esptool.py --port /dev/ttyUSB0 --baud 115200 write_flash --flash_size=detect 0 esp8266-20180309-v1.9.3-409-g72adc381.bin

If this runs without error then MicroPython should be installed on your board 🙂

Now you want to be able to communicate with MicroPython and upload scripts you want it to execute.
MicroPython boards have a Read-Eval-Print Loop (REPL) which is a simple interactive programming environment. It’s similar to the Python Idle shell. It can be accessed via the serial connection or over wifi.

Important!!
Before you go mental you may want to know that ESP8266-01 DOES NOT support rshell or REPL while in flash mode. So you have to unplug the USB converter, disconnect EN and IO0, plug it again. I found it by myself, with detriment of my mental health.

Back to the top

Serial connections

• rshell

Rototron suggests “rshell”, which can be installed using

sudo pip3 install rshell

you then run the following command, where you specify the size of the buffer (30) and the port to which you converter is plugged.

rshell --buffer-size=30 -p /dev/ttyUSB0

Note. In order for it to work I had to run it with sudo.

You then have a prompt which doesn’t look any different, except for the fact that it ends with ‘>’.
To exit rshell, simply Control-C.

A first thing you can do with rshell working is to type boards, which will get a list of connected boards. The first line returned should start with the board ID which for my ESP8266 is pyboard.

It looks like:
pyboard @ /dev/ttyUSB0 connected Dirs: /boot.py /pyboard/boot.py

As you can see it shows you the internal partition and what files are in there. Which is a very useful thing!
About that ‘boot.py’ file, quoting Rototron:

The boot.py file is automatically run at startup and contains low level code to set up the board and finish booting. You typically don’t want to edit it. However, you can add a file called main.py if you need your own code to run at start up after the boot.py.

Which is exactly what we’ll do later on.

Now to access your REPL, well, type repl. And you get a terminal which can chew Python commands. Control-X to exit.

Going back to rshell, you can easily use it to create folders and copy files on your ESP8266.
To do this, navigate to the folder where the file is saved. You can use cd and ls just like in a regular terminal. Then use cp to copy the program file to the ESP8266 which you specify with ‘/pyboard’. For example, if you want to copy a main.py file:

[yourfolder]> cp main.py /pyboard

you can easily create folders:

[yourfolder]> mkdir /pyboard/new_folder

and then write in them:

[yourfolder]> cp file.py /pyboard/new_folder/

 

• picocom

In the MicroPython documentation ‘picocom’ is mentioned a good REPL option. (‘TeraTerm’ is suggested for Windows users and ‘screen’ for Mac. Another one available to Linux users is ‘minicom’).

To start picocom, simply type:

picocom /dev/ttyUSB0 -b 115200

where ‘USB0’ will match yous specific case and the number indicates the BAUD rate (basically the speed) of the connection you want to establish. Also in this case I had to use sudo.

In case you do not have picocom installed it should not be a problem as you should see a message in the terminal telling you what to do.

Picocom shows a few more options than the REPL of rshell. To exit Control-X followed by Control-A.

To start the repl Control-C

Back to the top

Connection over wi-fi

• WebREPL

Another option mentioned in the documentation is that of using WebREPL, which allows you to communicate with your MicroPython device via wireless.

From the documentation:

“After a fresh install and boot the device configures itself as a WiFi access point (AP) that you can connect to. The ESSID is of the form MicroPython-xxxxxx where the x’s are replaced with part of the MAC address of your device (so will be the same everytime, and most likely different for all ESP8266 chips). The password for the WiFi is rshell –buffer-size=30 -p /dev/ttyUSB0 (note the upper-case N). Its IP address will be 192.168.4.1 once you connect to its network.”

As described here you can both either install it or use the WebREPL client you can find at http://micropython.org/webrepl. In the second case you will need to open your client page while connected to the Internet and then connect to the ESP8266 – as said above – before connecting to it.

Different situation when you have instructed your ESP not configure as an access point but to connect to one.

I haven’t used much WebREPL, also because my plan was to have the wi-fi staying on as little as possible, but I reckon it can be a very useful idea as you can even upload files on your micro-controller. This, for example, would be handy if you had your controller in a case, maybe with terminal soldered to other components, making access to it quite difficult.

Back to the top

Go back to: Build the sensor || Go to: The code