Merge pull request #94 from michalpokusa/connection-manager-and-ap-ex…

…amples

AP example and docs about ConnectionManager example

docs/examples.rst

@@ -1,50 +1,21 @@
-Simple Test
------------
+.. note::
+    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.
 
-**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.**
+Different ways of starting the server
+-------------------------------------
 
-This is the minimal example of using the library with CircuitPython.
-This example is serving a simple static text message.
+There are several ways to start the server on CircuitPython, mostly depending on the device you are using and
+whether you have access to external network.
 
-It also manually connects to the WiFi network.
+Functionally, all of them are the same, not features of the server are limited or disabled in any way.
 
-.. literalinclude:: ../examples/httpserver_simpletest_manual.py
-    :caption: examples/httpserver_simpletest_manual.py
-    :emphasize-lines: 12-17
-    :linenos:
-
-It is also possible to use Ethernet instead of WiFi.
-The only difference in usage is related to configuring the ``socket_source`` differently.
-
-.. literalinclude:: ../examples/httpserver_ethernet_simpletest.py
-    :caption: examples/httpserver_ethernet_simpletest.py
-    :emphasize-lines: 13-23
-    :linenos:
-
-Although there is nothing wrong with this approach, from the version 8.0.0 of CircuitPython,
-`it is possible to use the environment variables <https://docs.circuitpython.org/en/latest/docs/environment.html#circuitpython-behavior>`_
-defined in ``settings.toml`` file to store secrets and configure the WiFi network.
-
-By default the library uses ``0.0.0.0`` and port ``5000`` for the server, as port ``80`` is reserved for the CircuitPython Web Workflow.
-If you want to use port ``80`` , you need to set ``CIRCUITPY_WEB_API_PORT`` to any other port, and then set ``port`` parameter in ``Server`` constructor to ``80`` .
+Below you can find examples of different ways to start the server:
 
-This is the same example as above, but it uses the ``settings.toml`` file to configure the WiFi network.
+.. toctree::
 
-**From now on, all the examples will use the** ``settings.toml`` **file to configure the WiFi network.**
-
-.. literalinclude:: ../examples/settings.toml
-    :caption: settings.toml
-    :lines: 5-
-    :linenos:
-
-Note that we still need to import ``socketpool`` and ``wifi`` modules.
-
-.. literalinclude:: ../examples/httpserver_simpletest_auto.py
-    :caption: examples/httpserver_simpletest_auto.py
-    :emphasize-lines: 11
-    :linenos:
+    starting_methods
 
 CPython usage
 --------------------
@@ -210,7 +181,7 @@ You can find more information about the template syntax in the
 
 .. literalinclude:: ../examples/httpserver_templates.py
     :caption: examples/httpserver_templates.py
-    :emphasize-lines: 12-15,49-55
+    :emphasize-lines: 12-15,51-59
     :linenos:
 
 Form data parsing

docs/starting_methods.rst

@@ -0,0 +1,82 @@
+
+Manual WiFi
+-----------
+
+This is the minimal example of using the library with CircuitPython.
+This example is serving a simple static text message.
+
+It also manually connects to the WiFi network. SSID and password are stored in the code, but they
+can as well be stored in the ``settings.toml`` file, and then read from there using ``os.getenv()``.
+
+.. literalinclude:: ../examples/httpserver_simpletest_manual_wifi.py
+    :caption: examples/httpserver_simpletest_manual_wifi.py
+    :emphasize-lines: 10-17
+    :linenos:
+
+Manual AP (access point)
+------------------------
+
+If there is no external network available, it is possible to create an access point (AP) and run a server on it.
+It is important to note that only devices connected to the AP will be able to access the server and depending on the device,
+it may not be able to access the internet.
+
+.. literalinclude:: ../examples/httpserver_simpletest_manual_ap.py
+    :caption: examples/httpserver_simpletest_manual_ap.py
+    :emphasize-lines: 11-16,30
+    :linenos:
+
+Manual Ethernet
+---------------
+
+Most of the time, the WiFi will be a preferred way of connecting to the network.
+Nevertheless it is also possible to use Ethernet instead of WiFi.
+The only difference in usage is related to configuring the ``socket_source`` differently.
+
+.. literalinclude:: ../examples/httpserver_simpletest_manual_ethernet.py
+    :caption: examples/httpserver_simpletest_manual_ethernet.py
+    :emphasize-lines: 9-10,13-25,38
+    :linenos:
+
+Automatic WiFi using ``settings.toml``
+--------------------------------------
+
+From the version 8.0.0 of CircuitPython,
+`it is possible to use the environment variables <https://docs.circuitpython.org/en/latest/docs/environment.html#circuitpython-behavior>`_
+defined in ``settings.toml`` file to store secrets and configure the WiFi network
+using the ``CIRCUITPY_WIFI_SSID`` and ``CIRCUITPY_WIFI_PASSWORD`` variables.
+
+By default the library uses ``0.0.0.0`` and port ``5000`` for the server, as port ``80`` is reserved for the CircuitPython Web Workflow.
+If you want to use port ``80`` , you need to set ``CIRCUITPY_WEB_API_PORT`` to any other port, and then set ``port`` parameter in ``Server`` constructor to ``80`` .
+
+This is the same example as above, but it uses the ``settings.toml`` file to configure the WiFi network.
+
+.. note::
+    From now on, all the examples will use the ``settings.toml`` file to configure the WiFi network.
+
+.. literalinclude:: ../examples/settings.toml
+    :caption: settings.toml
+    :lines: 5-
+    :linenos:
+
+Note that we still need to import ``socketpool`` and ``wifi`` modules.
+
+.. literalinclude:: ../examples/httpserver_simpletest_auto_settings_toml.py
+    :caption: examples/httpserver_simpletest_auto_settings_toml.py
+    :emphasize-lines: 11
+    :linenos:
+
+
+Helper for socket pool using ``adafruit_connection_manager``
+------------------------------------------------------------
+
+If you do not want to configure the socket pool manually, you can use the ``adafruit_connection_manager`` library,
+which provides helpers for getting socker pool and SSL context for common boards.
+
+Note that it is not installed by default.
+You can read `more about the it here <https://docs.circuitpython.org/projects/connectionmanager/en/latest/index.html>`_.
+
+
+.. literalinclude:: ../examples/httpserver_simpletest_auto_connection_manager.py
+    :caption: examples/httpserver_simpletest_auto_connection_manager.py
+    :emphasize-lines: 7,11
+    :linenos:

docs/starting_methods.rst.license

@@ -0,0 +1,3 @@
+SPDX-FileCopyrightText: 2024 Michał Pokusa
+
+SPDX-License-Identifier: MIT

examples/httpserver_simpletest_auto_connection_manager.py

@@ -0,0 +1,23 @@
+# SPDX-FileCopyrightText: 2024 DJDevon3
+#
+# SPDX-License-Identifier: MIT
+
+import wifi
+
+from adafruit_connection_manager import get_radio_socketpool
+from adafruit_httpserver import Server, Request, Response
+
+
+pool = get_radio_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))

examples/httpserver_simpletest_manual_ap.py

@@ -0,0 +1,30 @@
+# SPDX-FileCopyrightText: 2024 Michał Pokusa
+#
+# SPDX-License-Identifier: Unlicense
+
+import socketpool
+import wifi
+
+from adafruit_httpserver import Server, Request, Response
+
+
+AP_SSID = "..."
+AP_PASSWORD = "..."
+
+print("Creating access point...")
+wifi.radio.start_ap(ssid=AP_SSID, password=AP_PASSWORD)
+print(f"Created access point {AP_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_ap))

examples/httpserver_ethernet_simpletest.py → examples/httpserver_simpletest_manual_ethernet.py

@@ -1,19 +1,21 @@
 # SPDX-FileCopyrightText: 2023 Tim C for Adafruit Industries
+#
 # SPDX-License-Identifier: MIT
 
 import board
 import digitalio
 
 from adafruit_wiznet5k.adafruit_wiznet5k import WIZNET5K
-import adafruit_wiznet5k.adafruit_wiznet5k_socket as socket
+from adafruit_wiznet5k import adafruit_wiznet5k_socket as socket
 from adafruit_httpserver import Server, Request, Response
 
-print("Wiznet5k HTTPServer Test")
 
 # For Adafruit Ethernet FeatherWing
 cs = digitalio.DigitalInOut(board.D10)
+
 # For Particle Ethernet FeatherWing
 # cs = digitalio.DigitalInOut(board.D5)
+
 spi_bus = board.SPI()
 
 # Initialize ethernet interface with DHCP
@@ -22,7 +24,6 @@
 # Set the interface on the socket source
 socket.set_interface(eth)
 
-# Initialize the server
 server = Server(socket, "/static", debug=True)
 
 

examples/httpserver_simpletest_manual.py → examples/httpserver_simpletest_manual_wifi.py

@@ -2,21 +2,20 @@
 #
 # 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")
+WIFI_SSID = "..."
+WIFI_PASSWORD = "..."
 
-print("Connecting to", ssid)
-wifi.radio.connect(ssid, password)
-print("Connected to", ssid)
+print(f"Connecting to {WIFI_SSID}...")
+wifi.radio.connect(WIFI_SSID, WIFI_PASSWORD)
+print(f"Connected to {WIFI_SSID}")
 
 pool = socketpool.SocketPool(wifi.radio)
+
 server = Server(pool, "/static", debug=True)