How To Run A Program At Boot

Up to now, you have been programing the ESP32 by having it constantly connected to the computer. From Thonny, you click on the green "play" button to trigger the selected program to run.

Imagine that you have finished working on your program, and want your ESP32 to be independent of your computer. You want the ESP32 and to be able to automatically execute a given program when power is applied.

There are a couple of ways by which you can do that.

In this lesson, I will show you both of them. 

Both involve the boot.py file.

boot.py

In MicroPython, "boot.py" is a special-purpose file.

If it exists in the root of the MicroPython filesystem, the ESP32 will try to read it and execute the program it contains.

When you install a fresh instance of the MicroPython firmware on your ESP32 or other hardware target, a boot.py file will be written in the filesystem. You can open this file in Thonny to have a look. As you can see in the screenshot above, the default boot.py file does contain some code, but it is commented out, and therefore inactive.

You can replace this code with yours.

Let's do that now.

Experiment 1: using boot.py

To demonstrate how boot.py works, I'll use the sample code from the previous lecture.

Here's the code:

from machine import Pin
from utime import sleep

led = Pin(21, Pin.OUT)

while True:
    print(".")
    led.on()
    sleep(0.5)
    led.off()
    sleep(0.5)

Copy this code in the boot.py file so that it looks like this (I did not replace the existing commented-out code):

Now that this code exists in the boot.py file, it will execute automatically next time I power-up the device. I don't need to connect the device to the computer, and I don't need to click on the play button in Thonny to run the program.

To test this, follow this process:

1. Disconnect the device from the computer by unplugging the USB cable from the computer USB port (leave the cable connected to the device).
   
2. Connect the USB cable to a USB power supply, like a phone charger. This will power up the device.
   
3. The program stored in boot.py will start , and the LED connected to GPIO 21 will start to blink.
   

What you have achieved is to make your ESP32 independent of your computer.

Problem: boot.py takes over your ESP32 (and how to deal with this)

Because the example code in boot.py contains an infinite loop, when you reconnect the ESP32 to your computer so that you can continue your work in Thonny, the ESP32 will be busy blinking the LED and will not give you a MicroPython shell, allow you to modify the program, or interact with the filesystem. Essentially, your ESP32 is locked up in the infinite loop.

To stop the program from running, use the Ctrl-C method.

Type Ctrl-C on your keyboard to interrupt the execution of the running program as you learned earlier in this series.

Note: clicking on the Stop button will have no effect. It will simply hard-reset the ESP32 which will then proceed to re-execute boot.py (and then you'll be back to where you started).

Type Ctrl-C to interrupt boot.py so that we can try out the second experiment in this lesson.

Experiment 2: import a program into boot.py

When you have a small program to run at boot up, copying it into the boot.py file is not a problem; it just works.

Imagine that you have a larger and more complicated program. You've been working on it for a while, and it works well enough to deploy in the field.

Copying a large file into boot.py is an option but it is messy. You will end up with two copies of the same file. If you need to make changes, you'll have to remember to apply the changes to both files.

That's a recipe for problems down the track that is easily avoided using an import statement.

You have already learned how to use the import statement.

In this example, the program that you want to execute in boot up is stored in the file titled "led_blink.py".

Inside boot.py, simply use this line of code:

import led_blink

At boot up, the ESP32 will read boot.py which contains the import statement. Then, the ESP32 will import the code stored in led_blink.py and execute it. The result will be, predictably, a blinking LED.

To test that this method works, repeat the same 3 steps as listed in Experiment 1 in this lesson. Power up the ESP32 from an external power supply (not your computer), to confirm that the LED on GPIO21 is blinking.

How to stop auto-execution of a program

As long as the boot.py file exists and it contains executable code (that is, code that is not commented out), your ESP32 will always execute this code at boot up.

If you don't want this to happen, you should do one of these:

1. Delete the boot.py file (you can always create it again later if needed).

2. Keep boot.py, but comment out all its contents.

Once you do one of the above, your ESP32 will boot into the MicroPython shell at boot up instead of executing the program stored in boot.py.

These are the two methods you can use to automatically run a program when your ESP32 is powered up.

The next thing that I want to show you is how to do simple debugging of your MicroPython scripts using Thonny IDE. Let's do that in the next lecture.