Updated existing and added more examples

Author: michalpokusa

docs/examples.rst

@@ -1,27 +1,64 @@
-Simple test
-------------
+Simple file serving
+-------------------
 
-Ensure your device works with this simple test.
+Serving the content of index.html from the filesystem.
 
-.. literalinclude:: ../examples/httpserver_simpletest.py
-    :caption: examples/httpserver_simpletest.py
+.. literalinclude:: ../examples/httpserver_simple_serve.py
+    :caption: examples/httpserver_simple_serve.py
     :linenos:
 
-Temperature test
---------------------
+If you want your code to do more than just serve web pages,
+use the ``.start()``/``.poll()`` methods as shown in this example.
 
-Send the microcontroller temperature back to the browser with this simple test.
+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.
 
-.. literalinclude:: ../examples/httpserver_temperature.py
-    :caption: examples/httpserver_temperature.py
+.. literalinclude:: ../examples/httpserver_simple_poll.py
+    :caption: examples/httpserver_simple_poll.py
     :linenos:
 
-Simple polling test
--------------------
+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.
+
+In this example, the server is accessible via ``http://custom-mdns-hostname/`` and ``http://custom-mdns-hostname.local/``.
+
+.. literalinclude:: ../examples/httpserver_cpu_information.py
+    :caption: examples/httpserver_cpu_information.py
+    :linenos:
+
+Change NeoPixel color
+---------------------
 
 If you want your code to do more than just serve web pages,
 use the start/poll methods as shown in this example.
 
-.. literalinclude:: ../examples/httpserver_simplepolling.py
-    :caption: examples/httpserver_simplepolling.py
+For example by going to ``/change-neopixel-color?r=255&g=0&b=0`` you can change the color of the NeoPixel to red.
+Tested on ESP32-S2 Feather.
+
+.. literalinclude:: ../examples/httpserver_neopixel.py
+    :caption: examples/httpserver_neopixel.py
+    :linenos:
+
+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.
+
+.. literalinclude:: ../examples/httpserver_cpu_information.py
+    :caption: examples/httpserver_cpu_information.py
+    :linenos:
+
+Chunked response
+---------------------
+
+Libraries supports chunked responses. This is useful for streaming data.
+To use it, you need to set the ``chunked=True`` when creating a ``HTTPResponse`` object.
+
+.. literalinclude:: ../examples/httpserver_chunked.py
+    :caption: examples/httpserver_chunked.py
     :linenos:

examples/httpserver_temperature.py renamed to examples/httpserver_chunked.py

@@ -2,31 +2,38 @@
 #
 # SPDX-License-Identifier: Unlicense
 
-from secrets import secrets  # pylint: disable=no-name-in-module
-
-import microcontroller
 import socketpool
 import wifi
 
-from adafruit_httpserver.server import HTTPServer
 from adafruit_httpserver.response import HTTPResponse
+from adafruit_httpserver.server import HTTPServer
+
+import secrets
+
+
+ssid, password = secrets.WIFI_SSID, secrets.WIFI_PASSWORD
 
-ssid = secrets["ssid"]
 print("Connecting to", ssid)
-wifi.radio.connect(ssid, secrets["password"])
+wifi.radio.connect(ssid, password)
 print("Connected to", ssid)
-print(f"Listening on http://{wifi.radio.ipv4_address}:80")
 
 pool = socketpool.SocketPool(wifi.radio)
 server = HTTPServer(pool)
 
 
-@server.route("/temperature")
-def base(request):  # pylint: disable=unused-argument
-    """Return the current temperature"""
-    # pylint: disable=no-member
-    return HTTPResponse(body=f"{str(microcontroller.cpu.temperature)}")
+@server.route("/chunked")
+def chunked(request):
+    """
+    Return the response with ``Transfer-Encoding: chunked``.
+    """
 
+    with HTTPResponse(request, chunked=True) as response:
+        response.send_chunk("Adaf")
+        response.send_chunk("ruit")
+        response.send_chunk(" Indus")
+        response.send_chunk("tr")
+        response.send_chunk("ies")
 
-# Never returns
+
+print(f"Listening on http://{wifi.radio.ipv4_address}:80")
 server.serve_forever(str(wifi.radio.ipv4_address))

examples/httpserver_cpu_information.py

@@ -0,0 +1,44 @@
+# SPDX-FileCopyrightText: 2022 Dan Halbert for Adafruit Industries
+#
+# SPDX-License-Identifier: Unlicense
+
+import json
+import microcontroller
+import socketpool
+import wifi
+
+from adafruit_httpserver.mime_type import MIMEType
+from adafruit_httpserver.response import HTTPResponse
+from adafruit_httpserver.server import HTTPServer
+
+import secrets
+
+
+ssid, password = secrets.WIFI_SSID, secrets.WIFI_PASSWORD
+
+print("Connecting to", ssid)
+wifi.radio.connect(ssid, password)
+print("Connected to", ssid)
+
+pool = socketpool.SocketPool(wifi.radio)
+server = HTTPServer(pool)
+
+
+@server.route("/cpu-information")
+def cpu_information_handler(request):
+    """
+    Return the current CPU temperature, frequency, and voltage as JSON.
+    """
+
+    data = {
+        "temperature": microcontroller.cpu.temperature,
+        "frequency": microcontroller.cpu.frequency,
+        "voltage": microcontroller.cpu.voltage,
+    }
+
+    with HTTPResponse(request, content_type=MIMEType.TYPE_JSON) as response:
+        response.send(json.dumps(data))
+
+
+print(f"Listening on http://{wifi.radio.ipv4_address}:80")
+server.serve_forever(str(wifi.radio.ipv4_address))

examples/httpserver_mdns.py

@@ -0,0 +1,44 @@
+# SPDX-FileCopyrightText: 2022 Dan Halbert for Adafruit Industries
+#
+# SPDX-License-Identifier: Unlicense
+
+import mdns
+import socketpool
+import wifi
+
+from adafruit_httpserver.mime_type import MIMEType
+from adafruit_httpserver.response import HTTPResponse
+from adafruit_httpserver.server import HTTPServer
+
+import secrets
+
+
+ssid, password = secrets.WIFI_SSID, secrets.WIFI_PASSWORD
+
+print("Connecting to", ssid)
+wifi.radio.connect(ssid, password)
+print("Connected to", ssid)
+
+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 = HTTPServer(pool)
+
+
+@server.route("/")
+def base(request):
+    """
+    Serve the default index.html file.
+    """
+    with HTTPResponse(request, content_type=MIMEType.TYPE_HTML) as response:
+        response.send_file("index.html")
+
+
+print(f"Listening on http://{wifi.radio.ipv4_address}:80")
+server.serve_forever(str(wifi.radio.ipv4_address))

examples/httpserver_neopixel.py

@@ -0,0 +1,45 @@
+# SPDX-FileCopyrightText: 2022 Dan Halbert for Adafruit Industries
+#
+# SPDX-License-Identifier: Unlicense
+
+import board
+import neopixel
+import socketpool
+import wifi
+
+from adafruit_httpserver.mime_type import MIMEType
+from adafruit_httpserver.response import HTTPResponse
+from adafruit_httpserver.server import HTTPServer
+
+import secrets
+
+
+ssid, password = secrets.WIFI_SSID, secrets.WIFI_PASSWORD
+
+print("Connecting to", ssid)
+wifi.radio.connect(ssid, password)
+print("Connected to", ssid)
+
+pool = socketpool.SocketPool(wifi.radio)
+server = HTTPServer(pool)
+
+pixel = neopixel.NeoPixel(board.NEOPIXEL, 1)
+
+
+@server.route("/change-neopixel-color")
+def change_neopixel_color_handler(request):
+    """
+    Changes the color of the built-in NeoPixel.
+    """
+    r = request.query_params.get("r")
+    g = request.query_params.get("g")
+    b = request.query_params.get("b")
+
+    pixel.fill((int(r or 0), int(g or 0), int(b or 0)))
+
+    with HTTPResponse(request, content_type=MIMEType.TYPE_TXT) as response:
+        response.send(f"Changed NeoPixel to color ({r}, {g}, {b})")
+
+
+print(f"Listening on http://{wifi.radio.ipv4_address}:80")
+server.serve_forever(str(wifi.radio.ipv4_address))

examples/httpserver_simplepolling.py renamed to examples/httpserver_simple_poll.py

@@ -2,40 +2,48 @@
 #
 # SPDX-License-Identifier: Unlicense
 
-from secrets import secrets  # pylint: disable=no-name-in-module
-
 import socketpool
 import wifi
 
-from adafruit_httpserver.server import HTTPServer
+from adafruit_httpserver.mime_type import MIMEType
 from adafruit_httpserver.response import HTTPResponse
+from adafruit_httpserver.server import HTTPServer
+
+import secrets
+
+
+ssid, password = secrets.WIFI_SSID, secrets.WIFI_PASSWORD
 
-ssid = secrets["ssid"]
 print("Connecting to", ssid)
-wifi.radio.connect(ssid, secrets["password"])
+wifi.radio.connect(ssid, password)
 print("Connected to", ssid)
-print(f"Listening on http://{wifi.radio.ipv4_address}:80")
 
 pool = socketpool.SocketPool(wifi.radio)
 server = HTTPServer(pool)
 
 
 @server.route("/")
-def base(request):  # pylint: disable=unused-argument
-    """Default reponse is /index.html"""
-    return HTTPResponse(filename="/index.html")
+def base(request):
+    """
+    Serve the default index.html file.
+    """
+    with HTTPResponse(request, content_type=MIMEType.TYPE_HTML) as response:
+        response.send_file("index.html")
 
 
-# startup the server
+print(f"Listening on http://{wifi.radio.ipv4_address}:80")
+
+# Start the server.
 server.start(str(wifi.radio.ipv4_address))
 
 while True:
     try:
-        # do something useful in this section,
+        # 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
+        # Process any waiting requests
         server.poll()
-    except OSError:
+    except OSError as error:
+        print(error)
         continue

examples/httpserver_simpletest.py renamed to examples/httpserver_simple_serve.py

@@ -2,29 +2,34 @@
 #
 # SPDX-License-Identifier: Unlicense
 
-from secrets import secrets  # pylint: disable=no-name-in-module
-
 import socketpool
 import wifi
 
-from adafruit_httpserver.server import HTTPServer
+from adafruit_httpserver.mime_type import MIMEType
 from adafruit_httpserver.response import HTTPResponse
+from adafruit_httpserver.server import HTTPServer
+
+import secrets
+
+
+ssid, password = secrets.WIFI_SSID, secrets.WIFI_PASSWORD
 
-ssid = secrets["ssid"]
 print("Connecting to", ssid)
-wifi.radio.connect(ssid, secrets["password"])
+wifi.radio.connect(ssid, password)
 print("Connected to", ssid)
-print(f"Listening on http://{wifi.radio.ipv4_address}:80")
 
 pool = socketpool.SocketPool(wifi.radio)
 server = HTTPServer(pool)
 
 
 @server.route("/")
-def base(request):  # pylint: disable=unused-argument
-    """Default reponse is /index.html"""
-    return HTTPResponse(filename="/index.html")
+def base(request):
+    """
+    Serve the default index.html file.
+    """
+    with HTTPResponse(request, content_type=MIMEType.TYPE_HTML) as response:
+        response.send_file("index.html")
 
 
-# Never returns
+print(f"Listening on http://{wifi.radio.ipv4_address}:80")
 server.serve_forever(str(wifi.radio.ipv4_address))