2. Writing and uploading firmware to EMIT - ControlBits/EMIT GitHub Wiki

2.1 Structuring our MicroPython code

OK, so we are just about ready to start programming EMIT but before we write and upload our first code, it's worth having a brief discussion about structuring our MicroPython code.

When the ESP32 starts up for the first time, or after a reset/power-cycle, it executes it's MicroPython code in a very structured way:

First, the ESP32 runs a file called 'boot.py'
Then, it runs a second file called 'main.py'

To help us structure our code efficiently, we'll use the first of these boot.py to:

import the modules and packages we need for our application
set up any global variables and constants
configure the hardware, and
hold any hardware specific functions

This will then leave main.py for our main application code.

Structuring our code in this way means that once EMIT has been set up correctly, you only need to work with the main.py file. In fact, if you prefer, you can download the example boot.py files from our GitHub repository leaving you free to jump into your main code development.

For the sake of this firmware development guide, we'll cover the development of the code needed for both files.

2.2 Useful MicroPython resources

The last thing to share before we get started, is the official MicroPython document library, this will be an invaluable reference as you develop EMIT's firmware:

General MicroPython information can be found at: https://docs.micropython.org/en/latest/index.html
ESP32 Specific information can be found at: https://docs.micropython.org/en/latest/esp32/quickref.html

OK, let's get started!

2.3 Writing our first code for EMIT

So, finally we're ready to write some (very simple) test code to check that our IDE and EMIT is all set up and ready to go. Over the next few tutorials, we'll add to this code to build our complete Environmental Monitoring Sensor firmware.

In this first example, we're simply going to make the Red LED on EMIT flash and print the code "LED ON" and "LED OFF" to the shell in the Thonny IDE. Let's start with importing the modules we'll use and setting up EMIT's Red LED pin:

As we said above, we'll do all of the setup in the boot.py file.

First, we need to import the modules we're going to use, in this case we need two modules:

the machine module is required to set up the GPIO (General Purpose Input/Output) pins of the ESP32, and
the time module, which includes several time and timer related functions, which we'll use later to determine the 'ON' and 'OFF' time of the flashing LED

Both modules can be imported with a single line of code (the module names are separated by a comma):

import machine, time

Next we need to configure the ESP32's GPIO pin that is connected to the Red LED - in this case it's GPIO 16.

MicroPython lets us assign our own variable names to hardware which really helps to make our code easier to understand. In this case, we'll create a variable called "RedLED" and use the 'machine' module we imported above to assign it to GPIO 16 and set the direction of the pin as an Output.

RedLED = machine.Pin(16, machine.Pin.OUT)

Finally, we set the default value of the RedLED pin to 0 (OFF) - changing this to 1 would turn the LED ON.

RedLED.value(0)

Our complete boot.py setup code (with some comments added) should look like this:

# general board setup
import machine, time

# configure GPIO pins
RedLED = machine.Pin(16, machine.Pin.OUT)
RedLED.value(0)

Hint: To make our code easier to read, we'll include lots of comments. In Python & MicroPython, a comment is identified by a leading '#' symbol. Anything after the first # will be ignored by the MicroPython interpreter.

OK, let's move onto our main application code, which will be held in main.py.

As we want our LED to flash ON and OFF continuously, we'll place all of our main application code within a 'while' loop using the line:

while True:

Next we want to wait for 1 second (using the time.sleep function which was imported with the time module) before turning the Red LED ON by assigning the value of '1' to the RedLED variable.

At the same time, we also want to print the message "LED ON" to the Shell window, so that we can see that the code is running correctly. This is achieved with the following 3 lines of code:

  time.sleep(1)     # wait 1 second 
    
  RedLED.value(1)   # turn RedLED ON
  print("LED ON")

Finally we want to wait for another 1 second, turn the Red LED OFF (by assigning the value of '0' to the RedLED variable) and print the message "LED OFF" to the Shell window:

  time.sleep(1)     # wait 1 second
  
  RedLED.value(0)   # turn RedLED OFF
  print("LED OFF")

Our complete main.py application code should look like this:

# this is the main program loop
while True:

  time.sleep(1)     # wait 1 second 
    
  RedLED.value(1)   # turn RedLED ON
  print("LED ON")
  
  time.sleep(1)     # wait 1 second
  
  RedLED.value(0)   # turn RedLED OFF
  print("LED OFF")

IMPORTANT: Don't forget that the code we want to run within the 'while TRUE:' loop must be indented correctly. The Thonny IDE helps by automatically adding an indent to the first line after the while loop statement. Please check that all subsequent lines in the loop have the same level of indentation - if your code doesn't work first time, this is one of the first things to check!

OK, so now we're ready to upload the code we've just written to EMIT using the Thonny IDE and get that LED flashing!

2.4 Uploading our first code to EMIT

Open Thonny and in the main editing window (called "untitled" by default) copy and paste the boot.py code from below.

boot.py

# general board setup
import machine, time

# configure GPIO pins
RedLED = machine.Pin(16, machine.Pin.OUT)
RedLED.value(0)

It should look something like this:

EMIT example 1 boot.py unsaved

Click the 'Save' button (the diskette icon) and you should be asked where you would like to save your code.

EMIT example 1 boot.py where to save

Click the 'MicroPython Device' button and a new 'Save to MicroPython device' dialog box will open.

EMIT example 1 boot.py enter file name

Enter the file name, in this case "boot.py" and click 'OK'. A 'Working...' dialog box should briefly appear.

EMIT example 1 boot.py saving dialog

HINT: Sometimes your ESP32 may not be ready to receive your code and the working box just sits there ... if that is the case, simply reboot the ESP32-DEVKITv1 module by pressing the tiny 'EN' button next to the USB connector.

OK, that's boot.py uploaded, now repeat exactly the same steps for main.py ...

main.py

# this is the main program loop
while True:

  time.sleep(1)     # wait 1 second 
    
  RedLED.value(1)   # turn RedLED ON
  print("LED ON")
  
  time.sleep(1)     # wait 1 second
  
  RedLED.value(0)   # turn RedLED OFF
  print("LED OFF")

Create a new file by clicking the 'new file' button (white page icon in the top, left-hand corner) and copy and past the main.py code (from above) into the new file window.

EMIT example 1 main.py unsaved

Click the 'Save' button (the diskette icon) and you should be asked where you would like to save your code.

EMIT example 1 main.py where to save

Click the 'MicroPython Device' button and a new 'Save to MicroPython device' dialog box will open.

EMIT example 1 main.py enter file name

Enter the file name, in this case "main.py" and click 'OK'.

We're now ready to run our code for the first time!

To do this, we need to reboot our ESP32 so that it will run through boot.py and main.py in the right sequence. To do this, simply press the tiny 'EN' button next to the USB connector.

Alternatively, if you prefer, you can do a 'Soft reboot' through the IDE by selecting 'Run' and then 'Send EOF/Soft reboot'.

EMIT Thonny soft reboot

All being well .. the Red LED on your EMIT development board should now be flashing and the words "LED ON" and "LED OFF" appearing in the shell window as shown below.

EMIT example 1 running

2.4 Reconnecting EMIT to Thonny after a re-start

Once the ESP32 is running your code or if you re-start EMIT or the Thonny IDE for any reason, the Thonny IDE will not be able to access the files on the ESP32 because the serial port will be busy - this is because the serial port will be controlled by the ESP32s application code.

To take back control of the serial port, all you need to do is press the red 'STOP' button on the IDE interface. Once stopped, the ESP32 will show the MicroPython version number and command prompt in the Shell window.

EMIT Thonny stopped

Once the ESP32 and Thonny IDE are in this state, you will be able to open, edit and save the files on the ESP32 as described above.

Congratulations! you're now ready to move on to: 3. Measuring Temperature & Humidity