Category Archives: IoT

ESP32 MicroPython APA102/DotStar Library

ESP32 APA102/DotStar Test Harness

Up until a few weeks ago the ESP32 version of MicroPython was missing support for APA102/DotStar LEDs. Now there are two drivers to choose from. One written by Matt T that focuses on simplicity and performance. Matt’s library is based on the Adafruit DotStar library back ported to MicroPython. The main difference between Matt’s code and Adafruit’s is that Matt’s code requires an SPI object and Adafruit’s requires separate Pin objects for Clock and Data. I look forward to trying this library on my next project after I upgrade to MicroPython 1.10. You can find Matt’s library here: https://github.com/mattytrentini/micropython-dotstar

The other MicroPython ESP32 APA102/Dotstar library was written by me. At the time I started the project I didn’t know that Matt was working on his library. In any case I needed a working APA102/DotStar library for a project using MicroPython 1.9.4. so I wrote one!
At this point my library is probably only of historical interest.

My class implements the Adafruit DotStar API, the MicroPython ESP8266 APA102 API, and the MicroPython SPI DotStar API. The code is derived from the Adafruit DotStar CircuitPython class and back ported to MicroPython. The focus of this implementation is backward compatibility, performance was a secondary goal. If GPIO pins are specified for clock and data the older lower performance “bit banging” technique is used rather than the newer software SPI technique. This preserved the existing API that only required clock and data pins instead of an SPI object.

This implementation has only been tested on the ESP32 and MicroPython 1.9.4

Two example/test files are included. The examples show simple class usage and some variations on the Adafruit DotStar examples that are more compact.

The files are available here: https://github.com/RobertJBabb/micropython_generic_apa102

IoT on the Cheap: ESP MicroPython Tools: Simple IDE uPyCraft

I just discovered a new (to me) MicroPython IDE, uPyCraft by DFRobot. It’s a great little IDE modeled along the lines of the Arduino IDE. It has cross platform support: Windows, Linux, and Mac. It supports multiple ESP versions. I tested with a WEMOS D1 Mini Lite with no issues. However, I did not try to flash the firmware.

I had one minor issue with the uPyCraft installation on Windows. uPyCraft requires the SourceCodePro font and has trouble locating the version I had installed.

If you click “OK” you can install the font. If you click “Cancel” the font file is copied to your desktop. You can right click the font file to install it. Once the font is installed uPyCraft ran without issues.

To connect to your ESP board click on the ESP serial port, Tools->Serial-><COMx> . You can also click on the Connect/Disconnect icon, the chain icon, on the right tool bar.

DFRobot includes a nice set of examples with uPyCraft. The REPL window supports editing keys and command recall. The files on your ESP are listed on the left under “Device”.  Right clicking on a file gives you a list of options, including editing in place, running, deleting.
Very nice, clean, easy to use design. In my limited testing uPyCraft was reliable with no issues.

You can download uPyCraft from GitHub: https://github.com/DFRobot/uPyCraft

DFRobot also provides a nice tutorial here: http://docs.dfrobot.com/upycraft/

Source code is available here: https://github.com/DFRobot/uPyCraft_src

IoT on the Cheap: ESP MicroPython Tools: IDE and Command Line

To complete our ESP on the cheap development  environment we need some additional tools to turbocharge our productivity. I did a survey of available tools and found two that meet the criteria for Windows, Mac, and Linux cross platform support and have multiple ESP board vendor support. The first tool is a command line utility that makes it a breeze to perform file operations and run MicroPython programs on the ESP:  Adafruit’s ampy. The second tool is the Pycharm IDE with the MicroPython plugin.

First, let’s take a look at “ampy”.  “ampy” provides simple, but vital, ESP file system functionality, reliably. The usage information below spells it out clearly.

ampy - Adafruit MicroPython Tool

Ampy is a tool to control MicroPython boards over a serial connection.Using ampy you can manipulate files on the board's internal filesystem and even run scripts.

Options:
-p, --port PORT Name of serial port for connected board. Can optionally
specify with AMPY_PORT environment variable. [required]
-b, --baud BAUD Baud rate for the serial connection (default 115200).
Can optionally specify with AMPY_BAUD environment
variable.
-d, --delay DELAY Delay in seconds before entering RAW MODE (default 0).
Can optionally specify with AMPY_DELAY environment
variable.
--version Show the version and exit.
--help Show this message and exit.

Commands:
get           Retrieve a file from the board.
ls              List contents of a directory on the board.
mkdir     Create a directory on the board.
put          Put a file or folder and its contents on the...
reset       Perform soft reset/reboot of the board.
rm           Remove a file from the board.
rmdir     Forcefully remove a folder and all its...
run         Run a script and print its output

Installing ampy is also straightforward:

pip install adafruit-ampy

To upgrade to the latest version:

pip install adafruit-ampy --upgrade

The source and documentation for ampy is available in github:
https://github.com/adafruit/

“ampy”, it simply works. Nice.

At the opposite end of the power and complexity spectrum we have PyCharm. PyCharm is a full featured, professional, powerful, integrated development environment (IDE) for Python. The community edition is FREE. There is great documentation available for PyCharm so I am not going to discuss all its features and installation instructions here. I am just going to focus on the MicroPython plugin. The plugin is available on github: https://github.com/vlasovskikh/intellij-micropython

However, you can install and configure the Micropython plugin from within PyCharm. That’s what we are going to do.

Go to File->Settings->Plugins->Install JetBrains Plugins, search for MicroPython and install the plugin.

Next, go to File->Settings->Languages & Frameworks->MicroPython

On Windows the plugin did not detect my WEMOS D1 MINI ESP8285. I had to enter the COM port manually. In my case COM4. Select your device type, the ESP8285 is equivalent to an ESP8266. Enable MicroPython support.

Plug in your ESP board if you haven’t already. We will bring up the ESP REPL to verify that our installation is working. Select Tools->MicroPython->MicroPython REPL.

I had to hit the reset button on my ESP to get it to work the first time. After that I didn’t have any issues.I found that none of the text editing keys worked in the REPL window, backspace, command recall, etc. So keep that in mind if you are planning to do extensive work in REPL. You may want to just open a terminal session (PuTTY on Windows).

To transfer files to the ESP you create a “flash” configuration, by right clicking on the file.

Once created it is a simple matter to run the configuration and copy the file to the ESP.

You can now work directly with your ESP (or other) MicroPython board without having to leave PyCharm!

But wait, there is more! The MicroPython plugin also includes support for context aware completion and documentation (ctrl-Q), syntax checking, and type checking. Go PyCharm!

IoT on the Cheap: ESP WebREPL Access

In this post we will be covering how to connect to the MicroPython interpreter (REPL) over the wireless network. MicroPython includes a web interface to REPL and file transfer. MicroPython supports a web interface that provides REPL (Read Execute Print Loop) access and file transfer capability. Before we can access WebREPL we need to bring up the ESP’s wireless access point.

The ESP family supports both station and access point WiFi operation and a wide variety of encryption algorithms for WiFI security. In this post we are just going to cover bringing up the ESP as an access point to get WebREPL running.

Connect to your ESP REPL via USB and serial terminal. See the previous post if you need to flash and configure your ESP for access via USB.

At the REPL prompt:

>>> import network
>>> ap_if = network.WLAN(network.AP_IF)
>>> ap_if.active(True)
>>> ap_if.ifconfig()
('192.168.4.1', '255.255.255.0', '192.168.4.1', '208.67.222.222')
>>> import webrepl_setup
WebREPL daemon auto-start status: disabled

Would you like to (E)nable or (D)isable it running on boot?
(Empty line to quit)
> E
To enable WebREPL, you must set password for it
New password (4-9 chars): upythoN
Confirm password: upythoN
Changes will be activated after reboot
Would you like to reboot now? (y/n) y

... ( bunch of build dependent output ) ...

WebREPL daemon started on ws://192.168.4.1:8266
Started webrepl in normal mode

ESP32 Notes: As of 7/2018 the stable 5/11/2018 ESP32 build “webrepl_setup” import didn’t work for me. However, the daily ESP32 build did work correctly.
See the previous post if you need to flash your ESP32 with a new build. Another difference between the ESP32 build and ESP8266 build, the ESP32 network came up as an Open network, the ESP8266 as secure. I’m not sure if this behavior will change in a future build, just something to be aware of. This is OK for quick prototyping but in a production environment you would want to configure WiFI security.

D1 Mini Lite AP

You should now see an ESP access point available. Don’t connect to it yet! We need to copy a few files from GitHub before we disconnect from the internet connected WiFi ( assuming you are connected to a WiFi access point).

The MicroPython WebREPL uses a WebSocket to communication so we need to download a web client to access the board. You can download the WebREPL client from GitHub here. Unzip the file and navigate to the directory containing “webrepl.html”

webrepl files

Switch your WiFi connection to the ESP_XXXX access point (AP).

Open “webrepl.html”  in your browser, chrome or firefox is recommended. The ip address is preset to match the MicroPython AP defaults. Click on the connect button. You should now have a working WebREPL session over WiFi to your ESP! You are no longer limited to a tethered connection! Freedom! WebREPL is great for updates, quick changes, and interactive testing. Here are a few useful command to test that your ESP and WebREPL are working correctly:

Webrepl Session

Congratulate yourself! You now have a working MicroPython ESP board with WiFi and wireless access to REPL and file transfer.  We showed some commands to explore the ESP MicroPython environment, checking on the amount for free memory, listing files, and accessing system information.

Resources:

https://docs.micropython.org/en/latest/esp8266/esp8266/tutorial/repl.html#webrepl-a-prompt-over-wifi
https://docs.micropython.org/en/latest/esp8266/library/index.html

ESP8285, ESP8266, ESP32

IoT on the Cheap: The ESP8266 Family

The Expressif ESP8266 is THE inexpensive IoT platform for makers and professional IoT developers. Over 100 million ESP chips have been sold.

What makes the ESP8266 family so special? Why should you bother with it? The answer is: it has WiFi, a capable processor, great development options, great support, and finally, PRICE. All the Expressif SOCs (System On a Chip) are available on boards costing under $10 US in 2018.

The Expressif ESP family of SOCs launched a revolution in low cost WiFi development boards.

In 2014 Expressif released the ESP8266EX a SOC combining processor and WiFi in a low cost package. In 2016 the more powerful ESP32, adding Bluetooth, was released. A lower cost version of the ESP8266EX, the ESP8285 with 1MB of integrated flash was also released in 2016. A wide variety of development languages and environments support the ESP family: C/C++, Python, LUA, Arduino, MicroPython, MongooseOS, FreeRTOS. We are only going to be looking at Python for now.

ESP8285, ESP8266, ESP32
From the left: ESP8285, ESP8266, ESP32

So, how do you choose a Python development board and environment?

We will show you how! It’s easy!

We are only focused on Python, so that eliminates all the other development environments and leaves us with only Micropython and CircuitPython.

Adafruit developed CircuitPython, a variation of MicroPython, focused on supporting Adafruit boards, such as the Circuit Playground, Huzzah32, etc.

You can find out more about Adafruit CircuitPython boards here.

The next criteria is cost. Adafruit makes a great product, but they cost more than a mystery brand board available on ebay or Amazon. Don’t get me wrong I love Adafruit products and CircuitPython. Adafruit has some great low cost boards that support CircuitPython, the Trinket M0 is only $8.95! Unfortunately, the Trinket M0 doesn’t include WiFi. The Adafruit boards provide extra features for that additional cost, built in RGB LEDs, battery connectors, builtin sensors. Details of the differences between MicroPython and CircuitPython can be found here.

So, For “IoT on the Cheap” that leaves us with MicroPython and “generic” ESP boards. We still have three choices of boards based on Expressif chips: ESP8285, ESP8266, and ESP32. To keep costs low support circuitry around the ESP chips is kept to a minimum. The board designs are open source.

Wemos D1 Mini Lite HiLetgo ESP8266 NodeMCU HiLetgo ESP32 NodeMCU
Cost $4.00 $6.00 $10.00
MCU ESP-8285 ESP-8266 ESP-32S
ADC 1 10-Bit 1 10-Bit 18 12-Bit
GPIO 11 17 36
Wifi Yes Yes Yes
Bluetooth No No Yes
CPU Xtensa 1 core L106 Xtensa 1 core L106 Xtensa 2 core LX6
Speed 80Mhz 80Mhz 160Mhz
SRAM ~50KB ~50KB ~520KB
Flash 1MB 4MB 4MB
Touch Sensor No No Yes
SPI/I2C/I2S/UART 2/1/2/2 2/1/2/2 4/2/2/2
Temperature Sensor No No Yes

The decision of which board to use is fairly straight forward, if you need more I/O, processing power, or storage, you need to move to a more expensive board.

The tool chains for all the boards are identical. However, there are some critical differences in the settings required to setup the boards. The ESP32 MicroPython image also has different defaults on some values than the ESP8266 boards.

Next steps: Setting up the boards for MicroPython on Windows.

What you will need:

Download and install Python 3 from here.

Make sure Python is in the path and environment variables are set if needed.

Detailed Python installation instructions for Windows can be found here.

Verify Python by install right-clicking the start menu: Run->cmd

Enter python into the text box. You should see a command prompt and Python version information displayed.

Python REPL Prompt
Python Prompt

At the Windows Command Prompt type:

>pip install esptool

pip esptool install
esptool install

Verify esptool is working correctly by displaying it’s help:

>esptool.py --help

usage: esptool [-h] [--chip {auto,esp8266,esp32}] [--port PORT] [--baud BAUD]
[--before {default_reset,no_reset,no_reset_no_sync}]
[--after {hard_reset,soft_reset,no_reset}] [--no-stub]
[--trace] [--override-vddsdio [{1.8V,1.9V,OFF}]]

The esptool -h  command will also display version and full usage information.

Now for some fun! Connect the ESP board to your PC using a USB cable.
You should see a new serial port in the device manager. The ESP board should appear as a COM port under “Ports”.

Device Manager ESP8266
Device Manager ESP8266

Dowload latest micropython stable version.
For ESP8285 and ESP8266 use: http://micropython.org/download#esp8266

For ESP32 use: http://micropython.org/download#esp32

Try to use the stable versions of the firmware. If you use a daily version of the firmware you will probably want to disable MicroPython debug output.

Next erase the flash memory on the ESP board. I like to specify the COM port as displayed in Device Manager.

esptool.py --port COM3 erase_flash

For the ESP32 you will need to specify the chip type as the default is the 8266.
You may need to press the flash button on some boards.

esptool.py --port COM3 --chip esp32 erase_flash

Write the new firmware to the ESP board:

esptool.py --port COM3 --baud 460800 write_flash --flash_size=detect 0 esp8266-xxxxxx-vX.Y.Z.bin

For Wemos D1 Mini Lite (ESP8285) you might need to lower the baud rate to 115200 and add the flash mode option:

>esptool.py --port COM4 --baud 115200 write_flash --flash_mode=dout --flash_size=detect 0 esp8266-xxxxxxxx-vX.Y.Z.bin

Here again the ESP32  requires a slightly different command to update the flash:

esptool.py --chip esp32 --port COM3 write_flash -z 0x1000 esp32-20180621-v1.9.4-189-g34344a41.bin

If the firmware was written successfully you will see output similar to the following:

esptool.py v2.4.0
Connecting....
Detecting chip type... ESP8266
Chip is ESP8285
Features: WiFi, Embedded Flash
MAC: 60:01:94:b0:f9:56
Uploading stub...
Running stub...
Stub running...
Configuring flash size...
Auto-detected Flash size: 1MB
Flash params set to 0x0320
Compressed 604872 bytes to 394893...
Wrote 604872 bytes (394893 compressed) at 0x00000000 in 35.2 seconds (effective 137.6 kbit/s)...
Hash of data verified.

Install Putty (Tera Term can be used as an alternative. However, I found setup more error prone.) I created and saved my settings as “MicroPython”. The next time you connect you can just load the correct settings.

Putty ESP8266 Connect
Putty ESP8266 Connect

Make sure the Serial settings are configured as no parity or flow control.

Putty ESP8266 Settings
Putty ESP8266 Settings

Connect to the board. You should now see a REPL prompt.
A quick check of the Python version will verify that REPL is working.

>>> import sys
>>> sys.version
'3.4.0'

Congratulations you now have a working MicroPython installation!

Further Reading:
https://docs.micropython.org/en/latest/esp8266/index.html
https://learn.adafruit.com/micropython-basics-how-to-load-micropython-on-a-board/overview
https://learn.adafruit.com/micropython-basics-what-is-micropython/overview
http://docs.python-guide.org/en/latest/intro/learning/