ESP32/ESP8266: MicroPython OTA Updates via PHP Server

In this project, we’ll show you an example of how you can do OTA (over-the-air) updates to your ESP32/ESP8266 boards running MicroPython code via a PHP server. In summary, you’ll create a PHP server in which you can submit a new code that you want to run on the ESP. When there is a new code/update available, the ESP downloads the new code, reboots, and starts running the newly downloaded code.

This project was created by one of our readers: David Flory. Thank you for your contributions. He provided the example codes and some explanations, and we’re documenting the whole process in this tutorial.

Note: for the latest version of his OTA project, please check this repository on his GitHub page.

Not familiar with MicroPython? Start here.

Project Overview

OTA (Over-the-Air) update is the process of loading new firmware to the ESP32 or ESP8266 board using a Wi-Fi connection rather than a serial communication. This functionality is extremely useful in case of no physical access to the board.

There are different ways to perform OTA updates. We have several examples for OTA updates using the ESP32/ESP8266 boards with Arduino IDE. In this tutorial, we’ll create a PHP server that will host new/updated code. The ESP will periodically communicate with the server to check if there is a new updated code available and download it to the board if that’s the case.

The following diagram explains how everything works.

1. The ESP32 or ESP8266 executes whatever tasks you define.
2. Meanwhile, you upload a new python file that you want to run on your ESP to the Rpi PHP server.
3. The ESP checks for updates periodically by making a request to the get_ESP_data.php URL to search for a new program.py.
4. If there is a new file available, the ESP will download it to its filesystem and reboot.
5. When it restarts, it will be running the newly uploaded python file.
6. This new file has an instruction at the beginning of the code to make a request to the delete_ESP_data.php URL to delete the python file from the PHP server because it is already running the most updated code.
7. When you upload a new code, the process repeats. Note that the new python file must also contain the instructions to delete the previous file from the PHP server and to check for updates.

Alternative method:

Here’s an alternative method that doesn’t require deleting previous files and allows you to update multiple boards.

1. The ESP32 or ESP8266 executes whatever tasks you define.
2.  The files you upload have a version number on the name.
3. The URL for updates is taken directly from the new program you upload (it should indicate what the next uploaded file will be called).
4. You don’t need to delete any files because all versions have a unique name. So, multiple boards running the same code can update themselves as we no longer delete the files from code, so the delete_ESP_data.php file can be removed.

We provide the files for this method at the end of the tutorial.

Taking it further:

A better way to do it might be to create an SQL database on your server, with a record for each ESP with fields for ID (could be MAC address), the version running, time file downloaded (instructions not included).

The PHP could be adjusted to:

• Ask for ID;
• Supply the update;
• Update the record for the ESP making the request.

Prerequisites

Before proceeding, make sure you check the following prerequisites.

1) MicroPython Programming

In this tutorial, we’ll program the ESP32/ESP8266 boards using MicroPython. Your boards must be burned with MicroPython firmware and you must have a MicroPython IDE to program your boards. We’ll use Thonny IDE, but you can use any other MicroPython-compatible software.

1. Getting Started with MicroPython on ESP32 and ESP8266
2. Choose a MicroPython IDE for ESP32 and ESP8266
3. Burn MicroPyhon firmware using the selected IDE

2) PHP Server

The ESP will communicate with the PHP server periodically to check if there are any updates (a new file with a new MicroPython code). You can create a local PHP server on a Raspberry Pi, for example, or alternatively, you can create a PHP server on the cloud (hosting + domain name) that can be accessed from anywhere.

Local PHP Server

For this example, we’ll create a local PHP server on a Raspberry Pi. So, you also need a Raspberry Pi for this tutorial:

1. Get a Raspberry Pi Board: check the best Raspberry Pi Starter Kits

After getting a Raspberry Pi, follow the next instructions to set it up:

2. Install Raspberry Pi OS, Set Up Wi-Fi, Enable and Connect with SSH

We’ll provide the instructions to create the local PHP server in this tutorial. You’ll also need a way to upload files to your PHP server remotely. We’ll use Filezilla. You can use any other suitable method.

3. To download Filezilla, click here and download the FileZilla client.

Cloud PHP Server

Alternatively, you can create your PHP server on the cloud using web hosting and a domain name. We recommend Bluehost or Digital Ocean. This tutorial doesn’t provide the instructions for this, but if you’re familiar with hosting your PHP server, you’ll easily figure out how to do it.

PART 1 – Creating the PHP Server

In this tutorial, we’ll create a local PHP server on a Raspberry Pi. Alternatively, you can create a cloud PHP server (instructions not included).

Before proceeding make sure you have installed the Raspberry Pi OS, set up Wi-Fi and SSH.

You can either run the next commands on a Raspberry Pi set as a desktop computer or using an SSH connection.

Updating and Upgrading

 Run the following commands to update your Pi. It will take a few minutes to complete.

pi@raspberrypi:~ $ sudo apt update && sudo apt upgrade -y

Change permissions so that the pi user can make modifications to files.

pi@raspberrypi:~ $ sudo chown pi:pi*

Installing Apache2

Next, install Apache2. Apache2 is the most widely used web server software. To install Apache2 on your Raspberry Pi, run the next command:

pi@raspberrypi:~ $ sudo apt install apache2 -y

That’s it! Apache is now installed. To test your installation, change to the /var/www/html directory and list the files:

pi@raspberrypi:~ $ cd /var/www/html
pi@raspberrypi:/var/www/html $ ls -al
index.html

You should have an index.html file in that folder. To open that page in your browser, you need to know the Raspberry Pi IP address. Use:

pi@raspberrypi:/var/www/html $ hostname -I

In my case, the Raspberry Pi IP address is 192.168.1.86. If you open your RPi IP address in any browser in your local network, a similar web page should load (http://192.168.1.86):

Installing PHP on Raspberry Pi

PHP is a server side scripting language. PHP (Hypertext Preprocessor) is used to develop dynamic web applications. A PHP file contains <?php … ?> tags and ends with the extension .PHP.

To install PHP on Raspberry Pi, run:

pi@raspberrypi:/var/www/html $ sudo apt install php -y

You can remove the index.html and create a PHP script to test the installation:

pi@raspberrypi:/var/www/html $ sudo rm index.html
pi@raspberrypi:/var/www/html $ sudo nano index.php

In your index.php file add the following code to echo the “hello world” message:

<?php echo "hello world"; ?>

To save your file: press Ctrl+X, followed by y, and press Enter to exit.

Finally, restart Apache2:

pi@raspberrypi:/var/www/html $ sudo service apache2 restart

To test if Apache2 is serving .php files, open the Raspberry Pi IP address and it should display the “hello world” message from the index.php script created earlier.

If everything is working, you can remove index.php file from the /var/www/html directory:

pi@raspberrypi:/var/www/html $ sudo rm index.php

Creating the php server – get_ESP_data.php

Now, create a file called get_ESP_data.php.

pi@raspberrypi: sudo nano get_ESP_data.php

Enter the following PHP code:

<?php
  $file = $_GET['file'];
  $dir = getcwd();
  $file = $dir.'/'.$file;
  $myfile = fopen($file, "r") or die("FAIL");
  echo file_get_contents($file);
  fclose($myfile);
?>

Press Ctrl+X, followed by y, and press Enter to exit and save the file. This previous script reads the updated file (new code uploaded to the same directory that those files are located) and echo’s it back in response to a request made by the ESP when it calls the check_for_updates function as we’ll see later on.

Creating the php server – delete_ESP_data.php

Create another file called delete_ESP_data.php.

pi@raspberrypi: sudo nano delete_ESP_data.php

Enter the following PHP code:

<?php
  $file = $_GET['file'];
  $dir = getcwd();
  $file = $dir.'/'.$file;
  unlink($file);
?>

Press Ctrl+X, followed by y, and press Enter to exit and save the file. This file will delete the update file from the PHP server after the ESP has downloaded it.

That’s it. The PHP server is created and able to echo a new file to the ESP and delete it in response to different requests.

PART 2 – Programming the ESP32/ESP8266

Before proceeding make sure you burned your boards with MicroPython firmware.

To test the PHP server and integrate it with the ESP boards to make OTA updates, we’ll show you a simple example. This example needs three files: boot.py, main.py, and program.py.

boot.py

Using your favorite MicroPython IDE, create a file called boot.py with the following content and upload it to your board.

# OTA updater for ESP32 running Micropython by David Flory
# Tutorial: https://randomnerdtutorials.com/esp32-esp8266-micropython-ota-updates/

try:
  import usocket as socket
except:
  import socket

try:
  import urequests as requests
except:
  import requests
import os 
import sys
import esp
esp.osdebug(None)
import gc
gc.collect()
from utime import sleep
from utime import sleep_ms
import network

OTA = 0

View raw code

This file imports the required libraries for network connection. It also creates a boolean variable called OTA that indicates whether it’s time to perform an OTA update (download the new file from the PHP server).

OTA = 0

The ESP runs the boot.py first. The first time it runs, there aren’t any available updates, so we set the OTA variable to 0.

main.py

Create a file called main.py with the following content and upload it to your board. You need to modify the file to include your own network credentials and the PHP server URL for the updates.

"""
OTA updater for ESP32 running Micropython by David Flory.
Tutorial: https://randomnerdtutorials.com/esp32-esp8266-micropython-ota-updates/

This is a simple way to run a python program on the ESP32 and download updates or a different program
to run from an HTTP server, either from the web or your local network.

Put all the imports needed for internet in boot, plus a global variable called OTA
The main file creates the internet connection then runs whatever program is required. I call the program 'program.py'

program.py is the main program, and can be whatever you want. The only requisite for this to work with OTA is that
it must be imported into the module 'main' and it must check periodically for updates.
The Program should have a function that can be called by 'main' to start it.

We can overwrite program.py while it is running, because it has been imported on boot into the namespace of 'main'.
All that is required is a reboot after a new Program.py is downloaded. In this case the deep sleep function will reboot the ESP32.

"""
#When prog.py finishes, if OTA = True, main downloads it and overwrites program.py, then effectively reboots.
#If OTA is false main just exits.

#this is the program to be executed. Note we do not use the '.py' extension.
import program

import machine #needed for the deep sleep function

#URLs for the updates
#replace with your PHP server URL or local IP address (Raspberry Pi IP Address)
upd_url="http://192.168.1.XXX/get_ESP_data.php?file=program.py"


#change your wifi credentials here. 
ssid = 'REPLACE_WITH_YOUR_SSID'
password = 'REPLACE_WITH_YOUR_PASSWORD'

print('OTA is ' + str(OTA))#debug

#here we set up the network connection
station = network.WLAN(network.STA_IF)
station.active(False)
station.active(True)
#station.config(reconnects = 5)

station.connect(ssid,password)

while station.isconnected() == False:
  pass

#print board local IP address
print(station.ifconfig())

if OTA == 0:
    print('starting program')
    OTA = program.mainprog(OTA)
    
#mainprog() is the starting function for my program. OTA is set to 0 on boot so the first time this code
#is run, it sets up the network connection and then runs the program.
#The following code only runs when program.py exits with OTA = 1

if OTA == 1:
    print('Downloading update')
    #download the update and overwrite program.py
    response = requests.get(upd_url)
    x = response.text.find("FAIL")
    if x > 15:
        #download twice and compare for security
        x = response.text
        response = requests.get(upd_url)
        if response.text == x:
            f = open("program.py","w")
            f.write(response.text)
            f.flush()
            f.close
            
            #soft reboot 
            print('reboot now')
            machine.deepsleep(5000)

View raw code

Here’s a summary of what this file does:

• connects your board to the internet;
• runs your program tasks (whatever you define in the program.py file we’ll take a look later)
• when you’re done with your tasks, if there is an updated, it will download it and overwrite the existing program.py file
• after that, it goes into deep sleep for a few seconds;
• after waking from deep sleep, it starts all over again with the new downloaded code (OTA update successful).

Let’s take a quick look at the code.

The following line imports the program.py> file—this is the program to be executed, it must contain the tasks that you want your ESP to do. Note that we do not use the .py extension.

import program

Then, import the machine module that is needed for deep sleep function.

import machine

Modify the upd_url variable with your PHP server IP address or URL. In my case, the Raspberry Pi server PHP address is 192.168.1.86, so the upd_url should be as follows:

upd_url="http://192.168.1.86/get_ESP_data.php?file=program.py"

Insert your network credentials in the following variables, so that the ESP can connect to your network.

ssid = 'REPLACE_WITH_YOUR_SSID'
password = 'REPLACE_WITH_YOUR_PASSWORD'

The following line prints the current state of the OTA variable for debugging purposes.

print('OTA is ' + str(OTA))

The next snippet of code connects the board to your local network and prints its IP address:

#here we set up the network connection
station = network.WLAN(network.STA_IF)
station.active(False)
station.active(True)
station.config(reconnects = 5)

station.connect(ssid,password)

while station.isconnected() == False:
  pass

#print board local IP address
print(station.ifconfig())

Finally, it checks the value of the OTA variable. If it is 0, it runs the main program that contains your tasks (main.py).

mainprog() is the starting function for our program. OTA is set to 0 on boot so the first time this code runs, it sets up the network connection and then runs the program.

if OTA == 0:
    print('starting program')
    OTA = program.mainprog(OTA)

The following code only runs when program.py exits with OTA = 1. This section of the code gets the content from the program.py that is in the PHP server and saves it on the board in the program.py program, so it overwrites the currently existing program.py file. After that, it goes to sleep for five seconds (it’s like a soft reboot). The next time the board reboots, it will run the new code.

if OTA == 1:
    print('Downloading update')
    #download the update and overwrite program.py
    response = requests.get(upd_url)
    x = response.text.find("FAIL")
    if x > 15:
        #download twice and compare for security
        x = response.text
        response = requests.get(upd_url)
        if response.text == x:
            f = open("program.py","w")
            f.write(response.text)
            f.flush()
            f.close
            
            #soft reboot 
            print('reboot now')
            machine.deepsleep(5000)

program.py

Create a file called program.py. Modify the code to include your local server IP address. Then, upload it to your board.

This is a simple program to demonstrate OTA update functionality in conjunction with main.py. The program can be as simple or complicated as you like but must contain these functions: check_for_updates(), mainprog() and program_tasks().

"""
OTA updater for ESP32 running Micropython by David Flory.
Tutorial: https://randomnerdtutorials.com/esp32-esp8266-micropython-ota-updates/

A simple program to demonstrate OTA update functionality in conjunction with main.py
The program can be as simple or complicated as you like, but must contain these functions.
The variable 'url' should be the full web address to the location of the update file and the PHP script which
returns it. below is the PHP script, named 'get_ESP_data.php'.

<?php
    $file = $_GET['file'];
    $dir = getcwd();
    $file = $dir.'/'.$file;
    $myfile = fopen($file, "r") or die("FAIL");
    echo file_get_contents($file);
    fclose($myfile);
?>

The script reads the update file and echo's it back in response to the request made by the
'check_for_updates' function.

Here is the delete script for deleting the updates.
<?php
    $file = $_GET['file'];
    $dir = getcwd();
    $file = $dir.'/'.$file;
    unlink($file);
?>

"""
import urequests
from utime import sleep
#The URL to use to get updates, full path to the PHP script (Raspberry Pi IP Address). The update file must be in the same
#directory as the PHP script.
#REPLACE WITH YOUR RASPBERRY PI IP ADDRESS
upd_url="http://192.168.1.XXX/get_ESP_data.php?file=program.py"
del_url = "http://192.168.1.XXX/delete_ESP_data.php?file=program.py"

def check_for_updates(OTA):
    try:
        #print ('Checking for updates')
        response = urequests.get(upd_url)
        x = response.text.find("FAIL")
        if x > 15:
            OTA = 1
            print('There is an update available')
            return(OTA)
        else:
            print('There are no updates available.')
            return(OTA)

    except:
        print('unable to reach internet')
        return(OTA)


def mainprog(OTA):
    print('Mainprog - OTA is' + str(OTA))
    #This is the entry point for your program code
    #first delete any update files on server. The reasoning here is that if this program is an update we
    #do not want to download it again. If this program is not an update, it is unlikely there will be an
    #update present anyway. If we do not delete it, the program will keep on updating on every loop and rebooting.
    response = urequests.get(del_url)
    print('Program start')
    while OTA == 0:
        program_tasks()
        OTA = check_for_updates(OTA)
        if OTA == 1:
           return(OTA)
        print('OTA = ' + str(OTA))

def program_tasks():
    #do program tasks. If continuous loop, use counter or sleep to pass some time between
    #update checks. At your designated point, check for updates.
    sleep(2)
    print('Tasks completed, entering loop 2')
    sleep(2)
    print('Tasks completed, entering loop 3')
    sleep(2)
    print('Tasks completed, entering loop 4')
    sleep(2)
    print('Tasks completed, entering loop 5')
    sleep(2)
    print('5 loops completed, checking for updates')

View raw code

Let’s take a quick look at the code to see how it works.

First, import any modules that might be required for your tasks. You must include the urequests library so that the ESP can make requests to the PHP server.

import urequests
from utime import sleep

Update the following variables to include the IP address of your local PHP server or the URL of your cloud web server. Only change the section with the IP address. The rest of the URL should remain as shown.

upd_url="http://192.168.1.86/get_ESP_data.php?file=program.py"
del_url = "http://192.168.1.86/delete_ESP_data.php?file=program.py"

The check_for_updates() function checks if there are updates available by making a request on the upd_url. It returns the OTA variable value: 0 if there aren’t any updates, or 1 if there is an update:

def check_for_updates(OTA):
    try:
        #print ('Checking for updates')
        response = urequests.get(upd_url)
        x = response.text.find("FAIL")
        if x > 15:
            OTA = 1
            print('There is an update available')
            return(OTA)
        else:
            print('There are no updates available.')
            return(OTA)

    except:
        print('unable to reach internet')
        return(OTA)

The mainprog() is the entry point for your program code (this function is called on the main.py file).

def mainprog(OTA):
    print('Mainprog - OTA is' + str(OTA))
    response = urequests.get(del_url)
    print('Program start')
    while OTA == 0:
        program_tasks()
        OTA = check_for_updates(OTA)
        if OTA == 1:
           return(OTA)
        print('OTA = ' + str(OTA))

First, it deletes any update files on the server by making a request on the del_url. The reasoning here is that if this program is an update we do not want to download it again. If this program is not an update, it is unlikely there will be an update present anyway. If we do not delete it, the program will keep on updating on every loop and rebooting.

Finally, the program_tasks() function should include the tasks you want to do with your board like sensor readings, data logging, controlling outputs, or any other tasks. For simplicity, we’re simply printing messages on the MicropPython shell.

def program_tasks():
    #do program tasks. If continuous loop, use counter or sleep to pass some time between
    #update checks. At your designated point, check for updates.
    sleep(2)
    print('Tasks completed, entering loop 2')
    sleep(2)
    print('Tasks completed, entering loop 3')
    sleep(2)
    print('Tasks completed, entering loop 4')
    sleep(2)
    print('Tasks completed, entering loop 5')
    sleep(2)
    print('5 loops completed, checking for updates')

If you’ll use a continuous loop, use a counter or sleep to pass some time between update checks. At your designated point, check for updates.

If you haven’t yet, upload all the previous files to your board in this order: boot.py, main.py and program.py. Reset your board so that it starts running the code. It should be printing the following messages on the shell (this is in the program_tasks function).

Let the board connected to your computer so that we can see on the shell if the updates are successful and for you to understand how it works. This example is solely for demonstration purposes as the aim of OTA is that you don’t need to have your board connected to your computer.

PART 3 – Demonstration: OTA Updates

Now, create a new file also called program.py and save it on your computer. This file will contain the updated code. In our case, we’ll only change the messages printed on the Shell. We’ll upload this code over-the-air to your ESP board via the PHP server.

# OTA updater for ESP32 running Micropython by David Flory
# Tutorial: https://randomnerdtutorials.com/esp32-esp8266-micropython-ota-updates/

#This program essentially identical to program1, except the tasks are slightly
#different to demonstrate a different program is now running.

import urequests
from utime import sleep
#The URL to use to get updates, full path to the PHP script (Raspberry Pi IP Address). The update file must be in the same
#directory as the PHP script.
#REPLACE WITH YOUR RASPBERRY PI IP ADDRESS
upd_url="http://192.168.1.XXX/get_ESP_data.php?file=program.py"
del_url = "http://192.168.1.XXX/delete_ESP_data.php?file=program.py"

def check_for_updates(OTA):
    try:
        #print ('Checking for updates')
        response = urequests.get(upd_url)
        x = response.text.find("FAIL")
        if x > 15:
            OTA = 1
            print('There is an update available')
            return(OTA)
        else:
            print('There are no updates available.')
            return(OTA)

    except:
        print('unable to reach internet')
        return(OTA)


def mainprog(OTA):
    print('Mainprog - OTA is' + str(OTA))
    #This is the entry point for your program code
    #first delete any update files on server. The reasoning here is that if this program is an update we
    #do not want to download it again. If this program is not an update, it is unlikely there will be an
    #update present anyway. If we do not delete it, the program will keep on updating on every loop and rebooting.
    response = urequests.get(del_url)
    print(response)
    print('Program start')
    while OTA == 0:
        program_tasks()
        OTA = check_for_updates(OTA)
        if OTA == 1:
           return(OTA)
        print('OTA = ' + str(OTA))

def program_tasks():
    #do program tasks. If continuous loop, use counter or sleep to pass some time between
    #update checks. At your designated point, check for updates.
    sleep(2)
    print('Updated Program 2, entering loop 2')
    sleep(2)
    print('Updated Program 2, entering loop 3')
    sleep(2)
    print('Updated Program 2, entering loop 4')
    sleep(2)
    print('Updated Program 2, entering loop 5')
    sleep(2)
    print('5 loops completed, checking for updates')

View raw code

Note: in a practical application, make sure your code is working properly before making an over-the-air update. If the new code crashes, you might need to connect your board again to your computer to be able to fix the issue.

To upload the new program to the PHP server, we’ll use Filezilla. You can use any other suitable method—just take into account that you must place the program.py in the same directory as the PHP files we created previously. If you’ve followed everything as in the tutorial, the file should be placed on the /var/www/html directory.

To establish a communication with the Pi, these are the settings (by default):

• Host: raspberrypi
• Username: pi
• Password: raspberry
• Port: 22

After uploading the new file to Filezilla, the ESP should detect there is a new file and will download it. Then, it will go into deep sleep, and start running the newly downloaded code. This new code prints a different message than the previous one.

Alternative Method

As mentioned previously, here’s an alternative method that doesn’t require deleting previous files and allows you to update multiple boards.

1. The ESP32 or ESP8266 executes whatever tasks you define.
2.  The files you upload have a version number.
3. The URL for updates is taken directly from the new program you upload (it should indicate what the next uploaded file will be called).
4. You don’t need to delete any files because all versions have a unique name. So, multiple boards running the same code can update themselves as we no longer delete the files from the code, so the delete_ESP_data.php file can be removed.
5. Users will have to delete their own files periodically after all boards have been updated.

The previous files were modified for this alternative method. Here are the files:

• boot.py (the same as the previous example)
• main.py
• program1.py
• program2.py

Wrapping Up

In this tutorial, you learned how to update a new code over the air to your ESP32 or ESP8266 boards (programmed with MicroPython) using a PHP server. As an example, we’ve built a local PHP web server on a Raspberry Pi.

We hope you’ve found this tutorial useful. If you want to learn more about MicroPython, check out our resources:

• MicroPython Programming with ESP32 and ESP8266 eBook
• Free MicroPython Projects and Tutorials

Thanks for reading.