AdafruitWSGI Library Documentation

AdafruitWSGI Library DocumentationRelease 1.0

Matthew Costi

Sep 24, 2021

Contents

1 Dependencies 3

2 Installing from PyPI 5

3 Contributing 73.1 Sphinx documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7

4 Table of Contents 94.1 Simple test . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94.2 wsgi_app . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

4.2.1 Implementation Notes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

5 Indices and tables 13

Python Module Index 15

Index 17

i

ii

AdafruitWSGI Library Documentation, Release 1.0

CircuitPython framework for creating WSGI compatible web server applications.

Contents 1

AdafruitWSGI Library Documentation, Release 1.0

2 Contents

CHAPTER 1

Dependencies

This driver depends on:

• Adafruit CircuitPython

Please ensure all dependencies are available on the CircuitPython filesystem. This is easily achieved by downloadingthe Adafruit library and driver bundle.

3

AdafruitWSGI Library Documentation, Release 1.0

4 Chapter 1. Dependencies

CHAPTER 2

Installing from PyPI

Note: This library is not available on PyPI yet. Install documentation is included as a standard element. Stay tunedfor PyPI availability!

On supported GNU/Linux systems like the Raspberry Pi, you can install the driver locally from PyPI. To install forcurrent user:

pip3 install adafruit-circuitpython-wsgi

To install system-wide (this may be required in some cases):

sudo pip3 install adafruit-circuitpython-wsgi

To install in a virtual environment in your current project:

mkdir project-name && cd project-namepython3 -m venv .envsource .env/bin/activatepip3 install adafruit-circuitpython-wsgi

5

AdafruitWSGI Library Documentation, Release 1.0

6 Chapter 2. Installing from PyPI

CHAPTER 3

Contributing

Contributions are welcome! Please read our Code of Conduct before contributing to help this project stay welcoming.

3.1 Sphinx documentation

Sphinx is used to build the documentation based on rST files and comments in the code. First, install dependencies(feel free to reuse the virtual environment from above):

python3 -m venv .envsource .env/bin/activatepip install Sphinx sphinx-rtd-theme

Now, once you have the virtual environment activated:

cd docssphinx-build -E -W -b html . _build/html

This will output the documentation to docs/_build/html. Open the index.html in your browser to view them. Itwill also (due to -W) error out on any warning like Travis will. This is a good way to locally verify it will pass.

7

AdafruitWSGI Library Documentation, Release 1.0

8 Chapter 3. Contributing

CHAPTER 4

Table of Contents

4.1 Simple test

Ensure your device works with this simple test.

Listing 1: examples/wsgi_simpletest.py

1 # SPDX-FileCopyrightText: 2021 ladyada for Adafruit Industries2 # SPDX-License-Identifier: MIT3

4 import board5 import busio6 from digitalio import DigitalInOut7 import neopixel8

9 from adafruit_esp32spi import adafruit_esp32spi10 import adafruit_esp32spi.adafruit_esp32spi_wifimanager as wifimanager11 import adafruit_esp32spi.adafruit_esp32spi_wsgiserver as server12 from adafruit_wsgi.wsgi_app import WSGIApp13

14 # Get wifi details and more from a secrets.py file15 try:16 from secrets import secrets17 except ImportError:18 print("WiFi secrets are kept in secrets.py, please add them there!")19 raise20

21 # This example depends on a WSGI Server to run.22 # We are using the wsgi server made for the ESP3223

24 print("ESP32 SPI simple web app test!")25

26

27 # If you are using a board with pre-defined ESP32 Pins:

(continues on next page)

9

AdafruitWSGI Library Documentation, Release 1.0

(continued from previous page)

28 esp32_cs = DigitalInOut(board.ESP_CS)29 esp32_ready = DigitalInOut(board.ESP_BUSY)30 esp32_reset = DigitalInOut(board.ESP_RESET)31

32 # If you have an externally connected ESP32:33 # esp32_cs = DigitalInOut(board.D9)34 # esp32_ready = DigitalInOut(board.D10)35 # esp32_reset = DigitalInOut(board.D5)36

37 spi = busio.SPI(board.SCK, board.MOSI, board.MISO)38 esp = adafruit_esp32spi.ESP_SPIcontrol(39 spi, esp32_cs, esp32_ready, esp32_reset40 ) # pylint: disable=line-too-long41

42 """Use below for Most Boards"""43 status_light = neopixel.NeoPixel(44 board.NEOPIXEL, 1, brightness=0.245 ) # Uncomment for Most Boards46 """Uncomment below for ItsyBitsy M4"""47 # import adafruit_dotstar as dotstar48 # status_light = dotstar.DotStar(board.APA102_SCK, board.APA102_MOSI, 1, brightness=1)49

50 ## If you want to connect to wifi with secrets:51 wifi = wifimanager.ESPSPI_WiFiManager(esp, secrets, status_light, debug=True)52 wifi.connect()53

54 ## If you want to create a WIFI hotspot to connect to with secrets:55 # secrets = {"ssid": "My ESP32 AP!", "password": "supersecret"}56 # wifi = wifimanager.ESPSPI_WiFiManager(esp, secrets, status_light)57 # wifi.create_ap()58

59 ## To you want to create an un-protected WIFI hotspot to connect to with secrets:"60 # secrets = {"ssid": "My ESP32 AP!"}61 # wifi = wifimanager.ESPSPI_WiFiManager(esp, secrets, status_light)62 # wifi.create_ap()63

64 # Here we create our application, registering the65 # following functions to be called on specific HTTP GET requests routes66

67 web_app = WSGIApp()68

69

70 @web_app.route("/led_on/<r>/<g>/<b>")71 def led_on(request, r, g, b): # pylint: disable=unused-argument72 print("led on!")73 status_light.fill((int(r), int(g), int(b)))74 return ("200 OK", [], "led on!")75

76

77 @web_app.route("/led_off")78 def led_off(request): # pylint: disable=unused-argument79 print("led off!")80 status_light.fill(0)81 return ("200 OK", [], "led off!")82

83

84 # Here we setup our server, passing in our web_app as the application(continues on next page)

10 Chapter 4. Table of Contents

AdafruitWSGI Library Documentation, Release 1.0

(continued from previous page)

85 server.set_interface(esp)86 wsgiServer = server.WSGIServer(80, application=web_app)87

88 print("open this IP in your browser: ", esp.pretty_ip(esp.ip_address))89

90 # print(esp.get_time())91 # Start the server92 wsgiServer.start()93 while True:94 # Our main loop where we have the server poll for incoming requests95 try:96 wsgiServer.update_poll()97 # Could do any other background tasks here, like reading sensors98 except (ValueError, RuntimeError) as e:99 print("Failed to update server, restarting ESP32\n", e)

100 wifi.reset()101 continue

4.2 wsgi_app

CircuitPython framework for creating WSGI server compatible web applications. This does not include server imple-mentation, which is necessary in order to create a web application with this library.

• Circuit Python implementation of an WSGI Server for ESP32 devices: https://github.com/adafruit/Adafruit_CircuitPython_ESP32SPI.git

• Author(s): Matthew Costi

4.2.1 Implementation Notes

Software and Dependencies:

• Adafruit CircuitPython firmware for the supported boards: https://github.com/adafruit/circuitpython/releases

class adafruit_wsgi.wsgi_app.WSGIAppThe base WSGI Application class.

on_request(methods, rule, request_handler)Register a Request Handler for a particular HTTP method and path. request_handler will be called when-ever a matching HTTP request is received.

request_handler should accept the following args: (Dict environ)

request_handler should return a tuple in the shape of: (status, header_list, data_iterable)

Parameters

• methods (list) – the methods of the HTTP request to handle

• rule (str) – the path rule of the HTTP request

• request_handler (func) – the function to call

route(rule, methods=None)A decorator to register a route rule with an endpoint function. if no methods are provided, default to GET

4.2. wsgi_app 11

AdafruitWSGI Library Documentation, Release 1.0

12 Chapter 4. Table of Contents

CHAPTER 5

Indices and tables

• genindex

• modindex

• search

13

AdafruitWSGI Library Documentation, Release 1.0

14 Chapter 5. Indices and tables

Python Module Index

aadafruit_wsgi.wsgi_app, 11

15

AdafruitWSGI Library Documentation, Release 1.0

16 Python Module Index

Index

Aadafruit_wsgi.wsgi_app (module), 11

Oon_request() (adafruit_wsgi.wsgi_app.WSGIApp

method), 11

Rroute() (adafruit_wsgi.wsgi_app.WSGIApp method),

11

WWSGIApp (class in adafruit_wsgi.wsgi_app), 11

17