ESP32 Picoweb: Changing the returned HTTP code

The objective of this post is to explain how to return specific HTTP codes on a MicroPython Picoweb app. The tests were performed using a DFRobot’s ESP-WROOM-32 device integrated in a ESP32 development board.

Introduction

The objective of this post is to explain how to return specific HTTP codes on a MicroPython Picoweb app.

As we will see below, we will use a function called http_error. Nonetheless, we can use it to return other types of HTTP codes, such as the ones in the range of 2xx, which are success codes. You can check here a list of the available HTTP response codes.

The tests were performed using a DFRobot’s ESP-WROOM-32 device integrated in a ESP32 development board. The code development was done on uPyCraft, a MicroPython IDE. You can check how to use uPyCraft in this previous post.

Although we are going to use a specific function to return the status code, the start_response function that we have been using on previous tutorials to return the first part of the HTTP response to the client also has an optional status parameter to return a specific HTTP code. By default, it has the value 200, which corresponds to OK [1].

The code

First of all, we will import the picoweb module, needed for setting up our HTTP server, and the network module, needed to establish the connection of the ESP32 to a WiFi network.

	import picoweb
import network

Next we will take care of connecting to the WiFi network. This piece of code is generic and was explained in more detail on this previous post. You just need to change the values of the ssid and password variables to the credentials of your WiFi network and then the ESP32 should be able to connect to it.

Note that at the end of the procedure we will store the IP assigned to the ESP32 in a variable, in order for later pass it to the app instance run method.

	ssid = "yourNetworkName"
password =  "yourPassword"
station = network.WLAN(network.STA_IF)
station.active(True)
station.connect(ssid, password)
while station.isconnected() == False:
  pass
ip = station.ifconfig()

	app = picoweb.WebApp(__name__)
@app.route("/internalerror")
def internalError(req, resp):
   ##Handling function code

To keep things simple, our routing handling function will immediately return the HTTP error. Naturally, in a real application scenario, we would most likely have some logic associated before returning an error on a specific endpoint.

To return the error code, we simply call the http_error function of the picoweb module, passing as input the client stream writer object and the error code, in string format. The internal server error corresponds to 500 [1]. You can test other status codes.

Since under the hood this function uses the awrite method of the stream writer, we need to use the yield from keywords.

	yield from picoweb.http_error(resp, "500")

	import picoweb
import network
ssid = "yourNetworkName"
password =  "yourPassword"
station = network.WLAN(network.STA_IF)
station.active(True)
station.connect(ssid, password)
while station.isconnected() == False:
  pass
ip = station.ifconfig()
app = picoweb.WebApp(__name__)
@app.route("/internalerror")
def internalError(req, resp):
    yield from picoweb.http_error(resp, "500")
app.run(debug=True, host =ip[0])

Testing the code

To test the code, simply upload the previous script to your ESP32 and run it. Upon executing, a message should be printed to the console, indicating the root path where the server is listening.

You just need to copy that URL to a web browser and append the internalerror word, which corresponds to the route where our app is listening. Upon executing, you should get an output similar to figure 1. Note that I’ve opened Chrome’s developer tools to check the request in more detail.

Figure 1 – Internal server error HTTP code returned.

As mentioned in the introductory section, despite the function name being http_error, we can use it to return non-error codes, such as the 201, which corresponds to a new resource being created [1]. You can confirm this at figure 2, where this HTTP code is being returned. Note that I’ve simply changed the status code passed to the http_error from 500 to 201 in the previous code, which is why the route is still called “internalerror”.

Figure 2 – Created HTTP code.