Getting Started

This section describes how to start utilising some of the MicroPython specific features of your board by itself, before we start adding more hardware into the mix in the coming pages.

LED Basics

The traditional first program for hobby electronics is a blinking light - so let’s stick with tradition and try to build that!

The boards you have actually have an LED built-in, so we can use that. It actually has three in fact - a red “power” LED, a blue “battery charge” LED, and a green LED that we can control (it defaults to off so it may not be easy to find until you enable it!).

One side of the green LED is connected to the GND (0 volts) pin internally, and the other side is connected to D1. We should be able to make that LED shine with our program by making D1 behave like the 3V3 (3.3 volt) pins. We need to “set the D1 pin high”, or in other words, make it connected to 3V3. Let’s try that:

from machine import Pin
import d1_mini

led = Pin(d1_mini.LED, Pin.OUT)
led.on()

The first line “imports” the “Pin” function from the “machine” module. In Python, to use any libraries, you first have to import them. The “machine” module contains most of the hardware-specific functions in Micropython.

The second line imports a helper “d1_mini” module that provides the pin mappings to easily interact with specific pins on the board. Note that that is the number one after the letter d, not a lower case L! Each of the digital pins (Dx) on the board can be found in this module, as well as some hardware-role-specific pins (such as those used for I2C or SPI communications). Note that this module is specifically for D1 Mini form factor boards, such as the Wemos D1 Mini and the TTGO MINI 32 - if you were to use a different board, you would likely need a different helper module!

Once we have the “Pin” function imported, we use it to create a pin object, with the first parameter telling it to use the LED value from our helper module, and the second parameter telling it to switch it into output mode (instead of the input mode it would default to otherwise). Once created, the pin is assigned to the variable we called “led”.

Finally, we set the pin high, by calling the “on” method on the “led” variable. At this point the LED should start shining - exciting!

Now, how to make the LED stop shining? There are two ways. We could switch it back into “input” mode, where the pin is not connected to anything. Or we could turn the microcontroller pin “off”. If we do that, both ends of the LED will be connected to GND, and the current won’t flow. We do that with:

led.off()

LED Blinking

Now, how can we make the LED blink 10 times? We could of course type led.on() and led.off() ten times quickly, but that’s a lot of work and we have computers to do that for us. We can repeat a command or a set of commands using the “for” loop:

for i in range(10):
    led.on()
    led.off()

What happened? Nothing interesting, the LED just shines like it did. That’s because the program blinked that LED as fast as it could – so fast, that we didn’t even see it. We need to make it wait a little before the blinks, and for that we are going to use the “time” module. First we need to import it:

import time

And then we will repeat our program, but with the waiting included:

for i in range(10):
    led.on()
    time.sleep(0.5)
    led.off()
    time.sleep(0.5)

Now the LED should turn on and off every half second!

Networking

One of the exciting features of the ESP32 microcontroller (the heart of the TTGO MINI 32) is built-in Wi-Fi. While Wi-Fi itself may be a complicated beast, luckily for us MicroPython makes it simple to use! First of all lets connect to the network:

import network
sta_if = network.WLAN(network.STA_IF)
sta_if.active(True)
sta_if.connect('<your SSID>', '<your password>')

You will have to replace <your SSID> and <your password> with the relevant login details for your network.

This creates a reference to the STAtion InterFace of the board (type of Wi-Fi connection that connects to an Access Point), enables it, and then attempts to connect to the defined network. The success of this can be checked with:

sta_if.isconnected()

Note that isconnected() will immediately return the current status of the network (whether it has connected or not) - if you want your code to pause until the network is connected, then it is common to have a while loop that will do nothing until the network connects. Safer implementations will include a timeout in the check in case of a missing network!

Once a connection is established, the details of this can be checked with:

sta_if.ifconfig()

Which provides the device IP, device netmask, default gateway, and DNS server.

More network control commands can be found in the MicroPython WLAN documentation. There is also an Access Point interface (network.AP_IF) which allows other devices to connect to your device. This can be very useful, but for the moment we’re just going to focus on connecting to another network - as this allows us to reach out to harness the power of the internet!

This Jen, is The Internet

Now that we’ve got a network connection (and that network extends out to the World Wide Web), it’s a relatively simple matter to make web requests, utilising the urequests library. This is a MicroPython implementation of the Python requests library. It’s had some features gutted to make it more microcontroller friendly, but it is still powerful!

To test it out, lets retrieve a random activity from the Bored API:

import urequests
req = urequests.get('https://www.boredapi.com/api/activity/')

And with that, we should now have the response to our activity request request! The text of the response can be found in req.text – check it out!

This is a JSON API, and so we can see the text of our request result is a string encoded JSON response. Turning a JSON string into a Python dict is pretty easy in Python (and MicroPython), and even easier when dealing with a request, as we can simply call the .json() method on it:

>>> req_dict = req.json()
>>> print(req_dict['activity'])
'Make homemade ice cream'

As simply as that, we can now harness information from the internet, and the myriad of public APIs out there (like those on this list of public APIs I found). Not only that, by using query strings we can pass information to websites, either for storage or for a customised response. We also have access to PUT requests, not just GET requests. I won’t go into that here, but be aware that it is a simple thing to do if you need to!

Now that we’ve got the basic functions of the board under control, lets get some more hardware involved!