Getting started with MicroPython

Follow this guide to code with MicroPython.

To work with MicroPython, of course, it is needed to install Python and Espressif's esptool.py package on your host PC.

esptool.py is an Espressif's open source utility to communicate with the ROM bootloader in Espressif ESP8266 and ESP32 chips.
By using this tool, you can push any binary into any address of the chip.

Please refer to this official Github webpage to get further information: https://github.com/espressif/esptool/.

For work with it properly, you need to proceed with Ubuntu bash.

Click Start with mouse right button and open Windows PowerShell (Admin).
Enter the following command and reboot.

host

PS C:\WINDOWS\system32> Enable-WindowsOptionalFeature -Online -FeatureName Microsoft-Windows-Subsystem-Linux

Open Microsoft Store and search Ubuntu 18.04, install it then execute.

It installs Ubuntu subsystem on your Windows system automatically.

Then proceed with the guide for Linux using Ubuntu bash (Installing Python packages and more).

Open a terminal window and enter the following commands.

host

joshua@joshua-desktop:~$ sudo apt update
joshua@joshua-desktop:~$ sudo apt install python python3 python-pip python3-pip
joshua@joshua-desktop:~$ sudo -H pip install esptool

Download a latest ESP32 firmware from https://micropython.org/download/#esp32.
Ensure you do know where the download file located in.

Assume that the firmware file names esp32-20180710-v1.9.4-257-gfcf621b0.bin.
It may not the same as yours since MicroPython publishes its daily builds.

Connect ODROID-GO to your PC with a micro USB cable.
Assume that ODROID-GO is shown as /dev/ttyUSB0. In Windows, it may be shown as something like COM3.

Open a terminal window and enter the following commands.

host

joshua@joshua-desktop:~$ sudo usermod -a -G dialout $USER
# Login again to take effect
 
joshua@joshua-desktop:~$ esptool.py --chip esp32 -p /dev/ttyUSB0 erase_flash
joshua@joshua-desktop:~$ esptool.py --chip esp32 -p /dev/ttyUSB0 write_flash -z 0x1000 ~/Downloads/esp32-20180710-v1.9.4-257-gfcf621b0.bin

After flashing a MicroPython firmware, now you can enter its Python REPL environment.
REPL is an abbreviation for Read Eval Print Loop. This means it evaluates and results instantly when you enter a command, like a shell program such as Bash, Zsh, …

rshell(Remote Shell for MicroPython) is a utility to interact with a MicroPython board over a serial connection.
This provides some additional features to communicate conveniently.
Github: https://github.com/dhylands/rshell

Alternatively, there's another tool ampy(Adafuit MicroPython Tool) to interact with a MicroPython board.
It kinda looks like a standard but it provides only core features. So we recommend to use rshell instead.
Github: https://github.com/adafruit/ampy

We'll guide you to install rshell in this step.

First, install rshell via pip.

host

joshua@joshua-desktop:~$ sudo -H pip3 install rshell

Assume that ODROID-GO is shown as /dev/ttyUSB0.

Open with rshell for ODROID-GO.
Then the shell switches its looks that is different from before.

host

joshua@joshua-desktop:~$ rshell --buffer-size 32 -a -p /dev/ttyUSB0
Connecting to /dev/ttyUSB0 ...
Welcome to rshell. Use Control-D to exit.
/home/joshua/Development/odroid-go-micropython> 

Enter repl command to use Python REPL.

host

/home/joshua/Development/odroid-go-micropython> repl
Entering REPL. Use Control-X to exit.
repl_serial_to_stdout dev = <rshell.main.DeviceSerial object at 0x7ff4e3cea390>
>
MicroPython v1.9.4-257-gfcf621b0 on 2018-07-10; ESP32 module with ESP32
Type "help()" for more information.
>>> 
>>> 

You can exit pressing Ctrl+X from REPL, Ctrl+D from rshell.

You can do Python coding on REPL prompt.

Let's define 2 variables and add them.

host

>>> a = 10
>>> b = 20
>>> print(a + b)
30

MicroPython provides help() function to show a basic instruction shows how to code with MicroPython board using REPL prompt.
Enter help() to see that.

host

>>> help()
Welcome to MicroPython on the ESP32!
 
For generic online docs please visit http://docs.micropython.org/
 
For access to the hardware use the 'machine' module:
 
import machine
pin12 = machine.Pin(12, machine.Pin.OUT)
pin12.value(1)
pin13 = machine.Pin(13, machine.Pin.IN, machine.Pin.PULL_UP)
print(pin13.value())
i2c = machine.I2C(scl=machine.Pin(21), sda=machine.Pin(22))
i2c.scan()
i2c.writeto(addr, b'1234')
i2c.readfrom(addr, 4)
 
Basic WiFi configuration:
 
import network
sta_if = network.WLAN(network.STA_IF); sta_if.active(True)
sta_if.scan()                             # Scan for available access points
sta_if.connect("<AP_name>", "<password>") # Connect to an AP
sta_if.isconnected()                      # Check for successful connection
 
Control commands:
  CTRL-A        -- on a blank line, enter raw REPL mode
  CTRL-B        -- on a blank line, enter normal REPL mode
  CTRL-C        -- interrupt a running program
  CTRL-D        -- on a blank line, do a soft reset of the board
  CTRL-E        -- on a blank line, enter paste mode
 
For further help on a specific object, type help(obj)
For a list of available modules, type help('modules')

We've made a module for ODROID-GO, and it would help you to do code with ODROID-GO.
Such as showing a message at the LCD, notifying a button event, playing a tone sound from its speaker.

Clone this repository to any directory.

host

joshua@joshua-desktop:~$ sudo apt install git
joshua@joshua-desktop:~$ git clone https://github.com/hardkernel/ODROID-GO-MicroPython

And to test, create a python script names boot.py in the same directory where downloaded MicroPython module locates.
The script file named as boot.py will run at the first time when a MicroPython board booted.

It imports odroid_go.py module and defines a function shows “Hello, ODROID-GO!” on the screen.

from odroid_go import GO
 
 
def hello():
    GO.lcd.fill(color=GO.lcd.colors.BLACK)
    GO.lcd.print("Hello, ODROID-GO!")

Open rshell again and transfer all of the files using rsync.
In rshell, the file system on the MicroPython board is mounted as /pyboard directory.

host

joshua@joshua-desktop:~$ rshell --buffer-size 32 -a -p /dev/ttyUSB0
Connecting to /dev/ttyUSB0 ...
Welcome to rshell. Use Control-D to exit.
/home/joshua/Development/odroid-go-micropython>

In the rshell, move to working directory using cd command.

Sync your working directory including ODROID-GO module with /pyboard directory.

host

/home/joshua/Development/odroid-go-micropython> rsync -m . /pyboard
Adding /pyboard/utils
Adding /pyboard/utils/go_pins.py
Adding /pyboard/utils/speaker
Adding /pyboard/utils/speaker/__init__.py
Adding /pyboard/utils/speaker/speaker.py
Adding /pyboard/utils/lcd
Adding /pyboard/utils/lcd/LICENSE
Adding /pyboard/utils/lcd/tt24.py
Adding /pyboard/utils/lcd/colors.py
Adding /pyboard/utils/lcd/glcdfont.py
Adding /pyboard/utils/lcd/font_to_py.py
Adding /pyboard/utils/lcd/tt32.py
Adding /pyboard/utils/lcd/m5stack.py
Adding /pyboard/utils/lcd/ili934xnew.py
Adding /pyboard/utils/lcd/tt14.py
Adding /pyboard/utils/lcd/__init__.py
Adding /pyboard/utils/lcd/README.md
Adding /pyboard/utils/lcd/main.py
Adding /pyboard/utils/button
Adding /pyboard/utils/button/__init__.py
Adding /pyboard/utils/button/button.py
Adding /pyboard/utils/battery
Adding /pyboard/utils/battery/__init__.py
Adding /pyboard/utils/battery/battery.py
Adding /pyboard/odroid_go.py
/home/joshua/Development/odroid-go-micropython/boot.py is newer than /pyboard/boot.py - copying

Enter to REPL prompt.

host

/home/joshua/Development/odroid-go-micropython> repl
Entering REPL. Use Control-X to exit.
repl_serial_to_stdout dev = <rshell.main.DeviceSerial object at 0x7ff4e3cea390>
>
MicroPython v1.9.4-257-gfcf621b0 on 2018-07-10; ESP32 module with ESP32
Type "help()" for more information.
>>> 
>>> 

Restart the board. boot.py will be read when it starts.
And call hello() function.

host

>>> hello()

Now you can see the message on the screen.

Now you're ready to write your source code.
To learn how to write source code, please refer to this guide: Hello World.