From aaa640e303a19a1ccc8de7cbb5f73ce80022efce Mon Sep 17 00:00:00 2001 From: michalpokusa <72110769+michalpokusa@users.noreply.github.com> Date: Wed, 3 Apr 2024 11:35:34 +0000 Subject: [PATCH] Added AP example and connection manager example to docs, updated docs and unified connection related examples --- docs/examples.rst | 55 +++---------- docs/starting_methods.rst | 82 +++++++++++++++++++ docs/starting_methods.rst.license | 3 + ...rver_simpletest_auto_connection_manager.py | 23 ++++++ ...tpserver_simpletest_auto_settings_toml.py} | 0 ...httpserver_simpletest_connectionmanager.py | 33 -------- examples/httpserver_simpletest_manual_ap.py | 30 +++++++ ... httpserver_simpletest_manual_ethernet.py} | 7 +- ...y => httpserver_simpletest_manual_wifi.py} | 13 ++- 9 files changed, 161 insertions(+), 85 deletions(-) create mode 100644 docs/starting_methods.rst create mode 100644 docs/starting_methods.rst.license create mode 100644 examples/httpserver_simpletest_auto_connection_manager.py rename examples/{httpserver_simpletest_auto.py => httpserver_simpletest_auto_settings_toml.py} (100%) delete mode 100644 examples/httpserver_simpletest_connectionmanager.py create mode 100644 examples/httpserver_simpletest_manual_ap.py rename examples/{httpserver_ethernet_simpletest.py => httpserver_simpletest_manual_ethernet.py} (87%) rename examples/{httpserver_simpletest_manual.py => httpserver_simpletest_manual_wifi.py} (75%) diff --git a/docs/examples.rst b/docs/examples.rst index 93eb107..92b6e25 100644 --- a/docs/examples.rst +++ b/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 `_ -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 diff --git a/docs/starting_methods.rst b/docs/starting_methods.rst new file mode 100644 index 0000000..566976d --- /dev/null +++ b/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 `_ +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 `_. + + +.. literalinclude:: ../examples/httpserver_simpletest_auto_connection_manager.py + :caption: examples/httpserver_simpletest_auto_connection_manager.py + :emphasize-lines: 7,11 + :linenos: diff --git a/docs/starting_methods.rst.license b/docs/starting_methods.rst.license new file mode 100644 index 0000000..11055fd --- /dev/null +++ b/docs/starting_methods.rst.license @@ -0,0 +1,3 @@ +SPDX-FileCopyrightText: 2024 Michał Pokusa + +SPDX-License-Identifier: MIT diff --git a/examples/httpserver_simpletest_auto_connection_manager.py b/examples/httpserver_simpletest_auto_connection_manager.py new file mode 100644 index 0000000..49d0473 --- /dev/null +++ b/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)) diff --git a/examples/httpserver_simpletest_auto.py b/examples/httpserver_simpletest_auto_settings_toml.py similarity index 100% rename from examples/httpserver_simpletest_auto.py rename to examples/httpserver_simpletest_auto_settings_toml.py diff --git a/examples/httpserver_simpletest_connectionmanager.py b/examples/httpserver_simpletest_connectionmanager.py deleted file mode 100644 index ff44d23..0000000 --- a/examples/httpserver_simpletest_connectionmanager.py +++ /dev/null @@ -1,33 +0,0 @@ -# SPDX-FileCopyrightText: 2024 DJDevon3 -# SPDX-License-Identifier: MIT -# Coded for Circuit Python 9. -"""HTTP Server Simpletest with Connection Manager""" -# pylint: disable=import-error - -import os - -import adafruit_connection_manager -import wifi - -from adafruit_httpserver import Server, Request, Response - -# Get WiFi details, ensure these are setup in settings.toml -ssid = os.getenv("WIFI_SSID") -password = os.getenv("WIFI_PASSWORD") - -print("Connecting to WiFi...") -wifi.radio.connect(ssid, password) -print("✅ Wifi!") - -# Initalize Wifi, Socket Pool, Request Session -pool = adafruit_connection_manager.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)) diff --git a/examples/httpserver_simpletest_manual_ap.py b/examples/httpserver_simpletest_manual_ap.py new file mode 100644 index 0000000..767196e --- /dev/null +++ b/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)) diff --git a/examples/httpserver_ethernet_simpletest.py b/examples/httpserver_simpletest_manual_ethernet.py similarity index 87% rename from examples/httpserver_ethernet_simpletest.py rename to examples/httpserver_simpletest_manual_ethernet.py index 97ac726..fafee51 100644 --- a/examples/httpserver_ethernet_simpletest.py +++ b/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) diff --git a/examples/httpserver_simpletest_manual.py b/examples/httpserver_simpletest_manual_wifi.py similarity index 75% rename from examples/httpserver_simpletest_manual.py rename to examples/httpserver_simpletest_manual_wifi.py index df28c6f..a9fee46 100644 --- a/examples/httpserver_simpletest_manual.py +++ b/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)