Simple Test

All examples in this document are using Server in debug mode. This mode is useful for development, but it is not recommended to use it in production. More about Debug mode at the end of Examples section.

This is the minimal example of using the library. This example is serving a simple static text message.

It also manually connects to the WiFi network.

examples/httpserver_simpletest_manual.py

# SPDX-FileCopyrightText: 2022 Dan Halbert for Adafruit Industries
#
# SPDX-License-Identifier: Unlicense

import os

import socketpool
import wifi

from adafruit_httpserver import Server, Request, Response

ssid = os.getenv("WIFI_SSID")
password = os.getenv("WIFI_PASSWORD")

print("Connecting to", ssid)
wifi.radio.connect(ssid, password)
print("Connected to", ssid)

pool = socketpool.SocketPool(wifi.radio)
server = Server(pool, "/static", debug=True)


@server.route("/")
def base(request: Request):
    """
    Serve a default static plain text message.
    """
    return Response(request, "Hello from the CircuitPython HTTP Server!")


server.serve_forever(str(wifi.radio.ipv4_address))

Although there is nothing wrong with this approach, from the version 8.0.0 of CircuitPython, it is possible to use the environment variables defined in settings.toml file to store secrets and configure the WiFi network.

This is the same example as above, but it uses the settings.toml file to configure the WiFi network.

From now on, all the examples will use the settings.toml file to configure the WiFi network.

settings.toml

# Setting these variables will automatically connect board to WiFi on boot
CIRCUITPY_WIFI_SSID="Your WiFi SSID Here"
CIRCUITPY_WIFI_PASSWORD="Your WiFi Password Here"

Note that we still need to import socketpool and wifi modules.

examples/httpserver_simpletest_auto.py

# SPDX-FileCopyrightText: 2022 Dan Halbert for Adafruit Industries
#
# SPDX-License-Identifier: Unlicense

import socketpool
import wifi

from adafruit_httpserver import Server, Request, Response


pool = socketpool.SocketPool(wifi.radio)
server = Server(pool, "/static", debug=True)


@server.route("/")
def base(request: Request):
    """
    Serve a default static plain text message.
    """
    return Response(request, "Hello from the CircuitPython HTTP Server!")


server.serve_forever(str(wifi.radio.ipv4_address))

Serving static files

It is possible to serve static files from the filesystem. In this example we are serving files from the /static directory.

In order to save memory, we are unregistering unused MIME types and registering additional ones. More about MIME types.

examples/httpserver_static_files_serving.py

# SPDX-FileCopyrightText: 2022 Dan Halbert for Adafruit Industries
#
# SPDX-License-Identifier: Unlicense


import socketpool
import wifi

from adafruit_httpserver import Server, MIMETypes


MIMETypes.configure(
    default_to="text/plain",
    # Unregistering unnecessary MIME types can save memory
    keep_for=[".html", ".css", ".js", ".png", ".jpg", ".jpeg", ".gif", ".ico"],
    # If you need to, you can add additional MIME types
    register={".foo": "text/foo", ".bar": "text/bar"},
)

pool = socketpool.SocketPool(wifi.radio)
server = Server(pool, "/static", debug=True)

# You don't have to add any routes, by default the server will serve files
# from it's root_path, which is set to "/static" in this example.

# If you don't set a root_path, the server will not serve any files.

server.serve_forever(str(wifi.radio.ipv4_address))

You can also serve a specific file from the handler. By default FileResponse looks for the file in the server’s root_path directory, but you can change it.

examples/httpserver_handler_serves_file.py

# SPDX-FileCopyrightText: 2022 Dan Halbert for Adafruit Industries
#
# SPDX-License-Identifier: Unlicense


import socketpool
import wifi

from adafruit_httpserver import Server, Request, FileResponse


pool = socketpool.SocketPool(wifi.radio)
server = Server(pool, "/static", debug=True)


@server.route("/home")
def home(request: Request):
    """
    Serves the file /www/home.html.
    """

    return FileResponse(request, "home.html", "/www")


server.serve_forever(str(wifi.radio.ipv4_address))

www/home.html

<html lang="en">
    <head>
        <meta charset="UTF-8">
        <meta http-equiv="X-UA-Compatible" content="IE=edge">
        <meta name="viewport" content="width=device-width, initial-scale=1.0">
        <title>Adafruit HTTPServer</title>
    </head>
    <body>
        <p>Hello from the <strong>CircuitPython HTTP Server!</strong></p>
    </body>
</html>

Tasks between requests

If you want your code to do more than just serve web pages, use the .start()/.poll() methods as shown in this example.

Between calling .poll() you can do something useful, for example read a sensor and capture an average or a running total of the last 10 samples.

examples/httpserver_start_and_poll.py

# SPDX-FileCopyrightText: 2022 Dan Halbert for Adafruit Industries
#
# SPDX-License-Identifier: Unlicense

import socketpool
import wifi

from adafruit_httpserver import Server, Request, FileResponse


pool = socketpool.SocketPool(wifi.radio)
server = Server(pool, "/static", debug=True)


@server.route("/")
def base(request: Request):
    """
    Serve the default index.html file.
    """
    return FileResponse(request, "index.html")


# Start the server.
server.start(str(wifi.radio.ipv4_address))

while True:
    try:
        # Do something useful in this section,
        # for example read a sensor and capture an average,
        # or a running total of the last 10 samples

        # Process any waiting requests
        server.poll()

        # If you want you can stop the server by calling server.stop() anywhere in your code
    except OSError as error:
        print(error)
        continue

Server with MDNS

It is possible to use the MDNS protocol to make the server accessible via a hostname in addition to an IP address. It is worth noting that it takes a bit longer to get the response from the server when accessing it via the hostname.

In this example, the server is accessible via http://custom-mdns-hostname/ and http://custom-mdns-hostname.local/.

examples/httpserver_mdns.py

# SPDX-FileCopyrightText: 2022 Dan Halbert for Adafruit Industries
#
# SPDX-License-Identifier: Unlicense

import mdns
import socketpool
import wifi

from adafruit_httpserver import Server, Request, FileResponse


mdns_server = mdns.Server(wifi.radio)
mdns_server.hostname = "custom-mdns-hostname"
mdns_server.advertise_service(service_type="_http", protocol="_tcp", port=80)

pool = socketpool.SocketPool(wifi.radio)
server = Server(pool, "/static", debug=True)


@server.route("/")
def base(request: Request):
    """
    Serve the default index.html file.
    """

    return FileResponse(request, "index.html", "/www")


server.serve_forever(str(wifi.radio.ipv4_address))

Get CPU information

You can return data from sensors or any computed value as JSON. That makes it easy to use the data in other applications.

examples/httpserver_cpu_information.py

# SPDX-FileCopyrightText: 2022 Dan Halbert for Adafruit Industries
#
# SPDX-License-Identifier: Unlicense

import microcontroller
import socketpool
import wifi

from adafruit_httpserver import Server, Request, JSONResponse

pool = socketpool.SocketPool(wifi.radio)
server = Server(pool, debug=True)


@server.route("/cpu-information", append_slash=True)
def cpu_information_handler(request: Request):
    """
    Return the current CPU temperature, frequency, and voltage as JSON.
    """

    data = {
        "temperature": microcontroller.cpu.temperature,
        "frequency": microcontroller.cpu.frequency,
        "voltage": microcontroller.cpu.voltage,
    }

    return JSONResponse(request, data)


server.serve_forever(str(wifi.radio.ipv4_address))

Handling different methods

On every server.route() call you can specify which HTTP methods are allowed. By default, only GET method is allowed.

You can pass a list of methods or a single method as a string.

It is recommended to use the the values in adafruit_httpserver.methods module to avoid typos and for future proofness.

If you want to route a given path with and without trailing slash, use append_slash=True parameter.

In example below, handler for /api and /api/ route will be called when any of GET, POST, PUT, DELETE methods is used.

examples/httpserver_methods.py

# SPDX-FileCopyrightText: 2022 Dan Halbert for Adafruit Industries
#
# SPDX-License-Identifier: Unlicense

import socketpool
import wifi

from adafruit_httpserver import Server, Request, JSONResponse, GET, POST, PUT, DELETE


pool = socketpool.SocketPool(wifi.radio)
server = Server(pool, debug=True)

objects = [
    {"id": 1, "name": "Object 1"},
]


@server.route("/api", [GET, POST, PUT, DELETE], append_slash=True)
def api(request: Request):
    """
    Performs different operations depending on the HTTP method.
    """

    # Get objects
    if request.method == GET:
        return JSONResponse(request, objects)

    # Upload or update objects
    if request.method in [POST, PUT]:
        uploaded_object = request.json()

        # Find object with same ID
        for i, obj in enumerate(objects):
            if obj["id"] == uploaded_object["id"]:
                objects[i] = uploaded_object

                return JSONResponse(
                    request, {"message": "Object updated", "object": uploaded_object}
                )

        # If not found, add it
        objects.append(uploaded_object)
        return JSONResponse(
            request, {"message": "Object added", "object": uploaded_object}
        )

    # Delete objects
    if request.method == DELETE:
        deleted_object = request.json()

        # Find object with same ID
        for i, obj in enumerate(objects):
            if obj["id"] == deleted_object["id"]:
                del objects[i]

                return JSONResponse(
                    request, {"message": "Object deleted", "object": deleted_object}
                )

        # If not found, return error
        return JSONResponse(
            request, {"message": "Object not found", "object": deleted_object}
        )

    # If we get here, something went wrong
    return JSONResponse(request, {"message": "Something went wrong"})


server.serve_forever(str(wifi.radio.ipv4_address))

Change NeoPixel color

There are several ways to pass data to the handler function:

• In your handler function you can access the query/GET parameters using request.query_params

• You can also access the POST data directly using request.body or if you data is in JSON format, you can use request.json() to parse it into a dictionary

• Alternatively for short pieces of data you can use URL parameters, which are described later in this document For more complex data, it is recommended to use JSON format.

All of these approaches allow you to pass data to the handler function and use it in your code.

For example by going to /change-neopixel-color?r=255&g=0&b=0 or /change-neopixel-color/255/0/0 you can change the color of the NeoPixel to red. Tested on ESP32-S2 Feather.

examples/httpserver_neopixel.py

# SPDX-FileCopyrightText: 2022 Dan Halbert for Adafruit Industries
#
# SPDX-License-Identifier: Unlicense

import board
import neopixel
import socketpool
import wifi

from adafruit_httpserver import Server, Request, Response, GET, POST


pool = socketpool.SocketPool(wifi.radio)
server = Server(pool, "/static", debug=True)

pixel = neopixel.NeoPixel(board.NEOPIXEL, 1)


@server.route("/change-neopixel-color", GET)
def change_neopixel_color_handler_query_params(request: Request):
    """Changes the color of the built-in NeoPixel using query/GET params."""

    # e.g. /change-neopixel-color?r=255&g=0&b=0

    r = request.query_params.get("r") or 0
    g = request.query_params.get("g") or 0
    b = request.query_params.get("b") or 0

    pixel.fill((int(r), int(g), int(b)))

    return Response(request, f"Changed NeoPixel to color ({r}, {g}, {b})")


@server.route("/change-neopixel-color", POST)
def change_neopixel_color_handler_post_body(request: Request):
    """Changes the color of the built-in NeoPixel using POST body."""

    data = request.body  # e.g b"255,0,0"
    r, g, b = data.decode().split(",")  # ["255", "0", "0"]

    pixel.fill((int(r), int(g), int(b)))

    return Response(request, f"Changed NeoPixel to color ({r}, {g}, {b})")


@server.route("/change-neopixel-color/json", POST)
def change_neopixel_color_handler_post_json(request: Request):
    """Changes the color of the built-in NeoPixel using JSON POST body."""

    data = request.json()  # e.g {"r": 255, "g": 0, "b": 0}
    r, g, b = data.get("r", 0), data.get("g", 0), data.get("b", 0)

    pixel.fill((r, g, b))

    return Response(request, f"Changed NeoPixel to color ({r}, {g}, {b})")


@server.route("/change-neopixel-color/<r>/<g>/<b>", GET)
def change_neopixel_color_handler_url_params(
    request: Request, r: str = "0", g: str = "0", b: str = "0"
):
    """Changes the color of the built-in NeoPixel using URL params."""

    # e.g. /change-neopixel-color/255/0/0

    pixel.fill((int(r), int(g), int(b)))

    return Response(request, f"Changed NeoPixel to color ({r}, {g}, {b})")


server.serve_forever(str(wifi.radio.ipv4_address))

Chunked response

Library supports chunked responses. This is useful for streaming large amounts of data. In order to use it, you need pass a generator that yields chunks of data to a ChunkedResponse constructor.

examples/httpserver_chunked.py

# SPDX-FileCopyrightText: 2022 Dan Halbert for Adafruit Industries
#
# SPDX-License-Identifier: Unlicense

import socketpool
import wifi

from adafruit_httpserver import Server, Request, ChunkedResponse


pool = socketpool.SocketPool(wifi.radio)
server = Server(pool, debug=True)


@server.route("/chunked")
def chunked(request: Request):
    """
    Return the response with ``Transfer-Encoding: chunked``.
    """

    def body():
        yield "Adaf"
        yield b"ruit"  # Data chunk can be bytes or str.
        yield " Indus"
        yield b"tr"
        yield "ies"

    return ChunkedResponse(request, body)


server.serve_forever(str(wifi.radio.ipv4_address))

URL parameters and wildcards

Alternatively to using query parameters, you can use URL parameters. They are a better choice when you want to perform different actions based on the URL. Query/GET parameters are better suited for modifying the behaviour of the handler function.

Of course it is only a suggestion, you can use them interchangeably and/or both at the same time.

In order to use URL parameters, you need to wrap them inside with angle brackets in Server.route, e.g. <my_parameter>.

All URL parameters values are passed as keyword arguments to the handler function.

Notice how the handler function in example below accepts two additional arguments : device_id and action.

If you specify multiple routes for single handler function and they have different number of URL parameters, make sure to add default values for all the ones that might not be passed. In the example below the second route has only one URL parameter, so the action parameter has a default value.

Keep in mind that URL parameters are always passed as strings, so you need to convert them to the desired type. Also note that the names of the function parameters have to match with the ones used in route, but they do not have to be in the same order.

It is also possible to specify a wildcard route:

• ... - matches one path segment, e.g /api/... will match /api/123, but not /api/123/456

• .... - matches multiple path segments, e.g /api/.... will match /api/123 and /api/123/456

In both cases, wildcards will not match empty path segment, so /api/.../users will match /api/v1/users, but not /api//users or /api/users.

examples/httpserver_url_parameters.py

# SPDX-FileCopyrightText: 2022 Dan Halbert for Adafruit Industries
#
# SPDX-License-Identifier: Unlicense

import socketpool
import wifi

from adafruit_httpserver import Server, Request, Response


pool = socketpool.SocketPool(wifi.radio)
server = Server(pool, debug=True)


class Device:
    def turn_on(self):  # pylint: disable=no-self-use
        print("Turning on device.")

    def turn_off(self):  # pylint: disable=no-self-use
        print("Turning off device.")


def get_device(device_id: str) -> Device:  # pylint: disable=unused-argument
    """
    This is a **made up** function that returns a `Device` object.
    """
    return Device()


@server.route("/device/<device_id>/action/<action>")
@server.route("/device/emergency-power-off/<device_id>")
def perform_action(
    request: Request, device_id: str, action: str = "emergency_power_off"
):
    """
    Performs an "action" on a specified device.
    """

    device = get_device(device_id)

    if action in ["turn_on"]:
        device.turn_on()
    elif action in ["turn_off", "emergency_power_off"]:
        device.turn_off()
    else:
        return Response(request, f"Unknown action ({action})")

    return Response(
        request, f"Action ({action}) performed on device with ID: {device_id}"
    )


@server.route("/device/.../status", append_slash=True)
@server.route("/device/....", append_slash=True)
def device_status(request: Request):
    """
    Returns the status of all devices no matter what their ID is.
    Unknown commands also return the status of all devices.
    """

    return Response(request, "Status of all devices: ...")


server.serve_forever(str(wifi.radio.ipv4_address))

Authentication

In order to increase security of your server, you can use Basic and Bearer authentication. Remember that it is not a replacement for HTTPS, traffic is still sent in plain text, but it can be used to protect your server from unauthorized access.

If you want to apply authentication to the whole server, you need to call .require_authentication on Server instance.

examples/httpserver_authentication_server.py

# SPDX-FileCopyrightText: 2022 Dan Halbert for Adafruit Industries
#
# SPDX-License-Identifier: Unlicense

import socketpool
import wifi

from adafruit_httpserver import Server, Request, Response, Basic, Bearer


# Create a list of available authentication methods.
auths = [
    Basic("user", "password"),
    Bearer("642ec696-2a79-4d60-be3a-7c9a3164d766"),
]

pool = socketpool.SocketPool(wifi.radio)
server = Server(pool, "/static", debug=True)
server.require_authentication(auths)


@server.route("/implicit-require")
def implicit_require_authentication(request: Request):
    """
    Implicitly require authentication because of the server.require_authentication() call.
    """

    return Response(request, body="Authenticated", content_type="text/plain")


server.serve_forever(str(wifi.radio.ipv4_address))

On the other hand, if you want to apply authentication to a set of routes, you need to call require_authentication function. In both cases you can check if request is authenticated by calling check_authentication on it.

examples/httpserver_authentication_handlers.py

# SPDX-FileCopyrightText: 2022 Dan Halbert for Adafruit Industries
#
# SPDX-License-Identifier: Unlicense

import socketpool
import wifi

from adafruit_httpserver import Server, Request, Response, UNATUHORIZED_401
from adafruit_httpserver.authentication import (
    AuthenticationError,
    Basic,
    Bearer,
    check_authentication,
    require_authentication,
)


pool = socketpool.SocketPool(wifi.radio)
server = Server(pool, debug=True)

# Create a list of available authentication methods.
auths = [
    Basic("user", "password"),
    Bearer("642ec696-2a79-4d60-be3a-7c9a3164d766"),
]


@server.route("/check")
def check_if_authenticated(request: Request):
    """
    Check if the request is authenticated and return a appropriate response.
    """
    is_authenticated = check_authentication(request, auths)

    return Response(
        request,
        body="Authenticated" if is_authenticated else "Not authenticated",
        content_type="text/plain",
    )


@server.route("/require-or-401")
def require_authentication_or_401(request: Request):
    """
    Require authentication and return a default server 401 response if not authenticated.
    """
    require_authentication(request, auths)

    return Response(request, body="Authenticated", content_type="text/plain")


@server.route("/require-or-handle")
def require_authentication_or_manually_handle(request: Request):
    """
    Require authentication and manually handle request if not authenticated.
    """

    try:
        require_authentication(request, auths)

        return Response(request, body="Authenticated", content_type="text/plain")

    except AuthenticationError:
        return Response(
            request,
            body="Not authenticated - Manually handled",
            content_type="text/plain",
            status=UNATUHORIZED_401,
        )


server.serve_forever(str(wifi.radio.ipv4_address))

Redirects

Sometimes you might want to redirect the user to a different URL, either on the same server or on a different one.

You can do that by returning Redirect from your handler function.

You can specify wheter the redirect is permanent or temporary by passing permanent=... to Redirect.

examples/httpserver_redirects.py

# SPDX-FileCopyrightText: 2022 Dan Halbert for Adafruit Industries
#
# SPDX-License-Identifier: Unlicense

import socketpool
import wifi

from adafruit_httpserver import Server, Request, Response, Redirect, NOT_FOUND_404


pool = socketpool.SocketPool(wifi.radio)
server = Server(pool, debug=True)

REDIRECTS = {
    "google": "https://www.google.com",
    "adafruit": "https://www.adafruit.com",
    "circuitpython": "https://circuitpython.org",
}


@server.route("/blinka")
def redirect_blinka(request: Request):
    """
    Always redirect to a Blinka page as permanent redirect.
    """
    return Redirect(request, "https://circuitpython.org/blinka", permanent=True)


@server.route("/<slug>")
def redirect_other(request: Request, slug: str = None):
    """
    Redirect to a URL based on the slug.
    """

    if slug is None or not slug in REDIRECTS:
        return Response(request, "Unknown redirect", status=NOT_FOUND_404)

    return Redirect(request, REDIRECTS.get(slug))


server.serve_forever(str(wifi.radio.ipv4_address))

Multiple servers

Although it is not the primary use case, it is possible to run multiple servers at the same time. In order to do that, you need to create multiple Server instances and call .start() and .poll() on each of them. Using .serve_forever() for this is not possible because of it’s blocking behaviour.

Each server must have a different port number.

In combination with separate authentication and diffrent root_path this allows creating moderately complex setups. You can share same handler functions between servers or use different ones for each server.

examples/httpserver_multiple_servers.py

# SPDX-FileCopyrightText: 2022 Dan Halbert for Adafruit Industries
#
# SPDX-License-Identifier: Unlicense

import socketpool
import wifi

from adafruit_httpserver import Server, Request, Response


pool = socketpool.SocketPool(wifi.radio)

bedroom_server = Server(pool, "/bedroom", debug=True)
office_server = Server(pool, "/office", debug=True)


@bedroom_server.route("/bedroom")
def bedroom(request: Request):
    """
    This route is registered only on ``bedroom_server``.
    """
    return Response(request, "Hello from the bedroom!")


@office_server.route("/office")
def office(request: Request):
    """
    This route is registered only on ``office_server``.
    """
    return Response(request, "Hello from the office!")


@bedroom_server.route("/home")
@office_server.route("/home")
def home(request: Request):
    """
    This route is registered on both servers.
    """
    return Response(request, "Hello from home!")


id_address = str(wifi.radio.ipv4_address)

# Start the servers.
bedroom_server.start(id_address, 5000)
office_server.start(id_address, 8000)

while True:
    try:
        # Process any waiting requests for both servers.
        bedroom_server.poll()
        office_server.poll()
    except OSError as error:
        print(error)
        continue

Debug mode

It is highly recommended to disable debug mode in production.

During development it is useful to see the logs from the server. You can enable debug mode by setting debug=True on Server instance or in constructor, it is disabled by default.

Debug mode prints messages on server startup, after sending a response to a request and if exception occurs during handling of the request in .serve_forever().

This is how the logs might look like when debug mode is enabled:

Started development server on http://192.168.0.100:80
192.168.0.101 -- "GET /" 194 -- "200 OK" 154
192.168.0.101 -- "GET /example" 134 -- "404 Not Found" 172
192.168.0.102 -- "POST /api" 1241 -- "401 Unauthorized" 95
Traceback (most recent call last):
    ...
    File "code.py", line 55, in example_handler
KeyError: non_existent_key
192.168.0.103 -- "GET /index.html" 242 -- "200 OK" 154
Stopped development server

This is the default format of the logs:

{client_ip} -- "{request_method} {path}" {request_size} -- "{response_status}" {response_size}

If you need more information about the server or request, or you want it in a different format you can modify functions at the bottom of adafruit_httpserver/server.py that start with _debug_....

NOTE: This is an advanced usage that might change in the future. It is not recommended to modify other parts of the code.