Skip to content

Commit 838277a

Browse files
michalpokusamichalpokusa
committed
Added AP example and connection manager example to docs, updated docs and unified connection related examples
1 parent 4cc9503 commit 838277a

8 files changed

+157
-85
lines changed

‎docs/connection_methods.rst

Lines changed: 82 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,82 @@
1+
2+
Manual WiFi
3+
-----------
4+
5+
This is the minimal example of using the library with CircuitPython.
6+
This example is serving a simple static text message.
7+
8+
It also manually connects to the WiFi network. SSID and password are stored in the code, but they
9+
can as well be stored in the ``settings.toml`` file, and then read from there using ``os.getenv()``.
10+
11+
.. literalinclude:: ../examples/httpserver_simpletest_manual_wifi.py
12+
:caption: examples/httpserver_simpletest_manual_wifi.py
13+
:emphasize-lines: 10-17
14+
:linenos:
15+
16+
Manual Ethernet
17+
---------------
18+
19+
Most of the time, the WiFi will be a preferred way of connecting to the network.
20+
Nevertheless it is also possible to use Ethernet instead of WiFi.
21+
The only difference in usage is related to configuring the ``socket_source`` differently.
22+
23+
.. literalinclude:: ../examples/httpserver_simpletest_manual_ethernet.py
24+
:caption: examples/httpserver_simpletest_manual_ethernet.py
25+
:emphasize-lines: 9-10,13-25,38
26+
:linenos:
27+
28+
Automatic WiFi using ``settings.toml``
29+
--------------------------------------
30+
31+
From the version 8.0.0 of CircuitPython,
32+
`it is possible to use the environment variables <https://docs.circuitpython.org/en/latest/docs/environment.html#circuitpython-behavior>`_
33+
defined in ``settings.toml`` file to store secrets and configure the WiFi network
34+
using the ``CIRCUITPY_WIFI_SSID`` and ``CIRCUITPY_WIFI_PASSWORD`` variables.
35+
36+
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.
37+
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`` .
38+
39+
This is the same example as above, but it uses the ``settings.toml`` file to configure the WiFi network.
40+
41+
.. note::
42+
From now on, all the examples will use the ``settings.toml`` file to configure the WiFi network.
43+
44+
.. literalinclude:: ../examples/settings.toml
45+
:caption: settings.toml
46+
:lines: 5-
47+
:linenos:
48+
49+
Note that we still need to import ``socketpool`` and ``wifi`` modules.
50+
51+
.. literalinclude:: ../examples/httpserver_simpletest_auto_settings_toml.py
52+
:caption: examples/httpserver_simpletest_auto_settings_toml.py
53+
:emphasize-lines: 11
54+
:linenos:
55+
56+
57+
Helper for socket pool using ``adafruit_connection_manager``
58+
------------------------------------------------------------
59+
60+
If you do not want to configure the socket pool manually, you can use the ``adafruit_connection_manager`` library,
61+
which provides helpers for getting socker pool and SSL context for common boards.
62+
63+
Note that it is not installed by default.
64+
You can read `more about the it here <https://docs.circuitpython.org/projects/connectionmanager/en/latest/index.html>`_.
65+
66+
67+
.. literalinclude:: ../examples/httpserver_simpletest_auto_connection_manager.py
68+
:caption: examples/httpserver_simpletest_auto_connection_manager.py
69+
:emphasize-lines: 7,11
70+
:linenos:
71+
72+
Manual AP (access point)
73+
------------------------
74+
75+
If there is no external network available, it is possible to create an access point (AP) and run a server on it.
76+
It is important to note that only devices connected to the AP will be able to access the server and depending on the device,
77+
it may not be able to access the internet.
78+
79+
.. literalinclude:: ../examples/httpserver_simpletest_manual_ap.py
80+
:caption: examples/httpserver_simpletest_manual_ap.py
81+
:emphasize-lines: 11-16,30
82+
:linenos:

‎docs/examples.rst

Lines changed: 11 additions & 41 deletions
Original file line numberDiff line numberDiff line change
@@ -1,50 +1,20 @@
1-
Simple Test
2-
-----------
1+
.. note::
2+
All examples in this document are using ``Server`` in ``debug`` mode.
3+
This mode is useful for development, but it is not recommended to use it in production.
4+
More about Debug mode at the end of Examples section.
35

4-
**All examples in this document are using** ``Server`` **in** ``debug`` **mode.**
5-
**This mode is useful for development, but it is not recommended to use it in production.**
6-
**More about Debug mode at the end of Examples section.**
7-
8-
This is the minimal example of using the library with CircuitPython.
9-
This example is serving a simple static text message.
10-
11-
It also manually connects to the WiFi network.
12-
13-
.. literalinclude:: ../examples/httpserver_simpletest_manual.py
14-
:caption: examples/httpserver_simpletest_manual.py
15-
:emphasize-lines: 12-17
16-
:linenos:
17-
18-
It is also possible to use Ethernet instead of WiFi.
19-
The only difference in usage is related to configuring the ``socket_source`` differently.
20-
21-
.. literalinclude:: ../examples/httpserver_ethernet_simpletest.py
22-
:caption: examples/httpserver_ethernet_simpletest.py
23-
:emphasize-lines: 13-23
24-
:linenos:
25-
26-
Although there is nothing wrong with this approach, from the version 8.0.0 of CircuitPython,
27-
`it is possible to use the environment variables <https://docs.circuitpython.org/en/latest/docs/environment.html#circuitpython-behavior>`_
28-
defined in ``settings.toml`` file to store secrets and configure the WiFi network.
29-
30-
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.
31-
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`` .
6+
Different ways of connecting
7+
----------------------------
328

33-
This is the same example as above, but it uses the ``settings.toml`` file to configure the WiFi network.
9+
There are several ways to connect to the server, depending on the platform you are using.
3410

35-
**From now on, all the examples will use the** ``settings.toml`` **file to configure the WiFi network.**
11+
.. toctree::
12+
:hidden:
3613

37-
.. literalinclude:: ../examples/settings.toml
38-
:caption: settings.toml
39-
:lines: 5-
40-
:linenos:
14+
connection_methods
4115

42-
Note that we still need to import ``socketpool`` and ``wifi`` modules.
16+
.. include:: ./connection_methods.rst
4317

44-
.. literalinclude:: ../examples/httpserver_simpletest_auto.py
45-
:caption: examples/httpserver_simpletest_auto.py
46-
:emphasize-lines: 11
47-
:linenos:
4818

4919
CPython usage
5020
--------------------

‎examples/httpserver_simpletest_auto_connection_manager.py

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
# SPDX-FileCopyrightText: 2024 DJDevon3
2+
#
3+
# SPDX-License-Identifier: MIT
4+
5+
import wifi
6+
7+
from adafruit_connection_manager import get_radio_socketpool
8+
from adafruit_httpserver import Server, Request, Response
9+
10+
11+
pool = get_radio_socketpool(wifi.radio)
12+
server = Server(pool, "/static", debug=True)
13+
14+
15+
@server.route("/")
16+
def base(request: Request):
17+
"""
18+
Serve a default static plain text message.
19+
"""
20+
return Response(request, "Hello from the CircuitPython HTTP Server!")
21+
22+
23+
server.serve_forever(str(wifi.radio.ipv4_address))

‎examples/httpserver_simpletest_auto.py renamed to ‎examples/httpserver_simpletest_auto_settings_toml.py

File renamed without changes.

‎examples/httpserver_simpletest_connectionmanager.py

Lines changed: 0 additions & 33 deletions
This file was deleted.

‎examples/httpserver_simpletest_manual_ap.py

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
# SPDX-FileCopyrightText: 2024 Michał Pokusa
2+
#
3+
# SPDX-License-Identifier: Unlicense
4+
5+
import socketpool
6+
import wifi
7+
8+
from adafruit_httpserver import Server, Request, Response
9+
10+
11+
AP_SSID = "..."
12+
AP_PASSWORD = "..."
13+
14+
print("Creating access point...")
15+
wifi.radio.start_ap(ssid=AP_SSID, password=AP_PASSWORD)
16+
print(f"Created access point {AP_SSID}")
17+
18+
pool = socketpool.SocketPool(wifi.radio)
19+
server = Server(pool, "/static", debug=True)
20+
21+
22+
@server.route("/")
23+
def base(request: Request):
24+
"""
25+
Serve a default static plain text message.
26+
"""
27+
return Response(request, "Hello from the CircuitPython HTTP Server!")
28+
29+
30+
server.serve_forever(str(wifi.radio.ipv4_address_ap))

‎examples/httpserver_ethernet_simpletest.py renamed to ‎examples/httpserver_simpletest_manual_ethernet.py

Lines changed: 5 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,19 +1,21 @@
11
# SPDX-FileCopyrightText: 2023 Tim C for Adafruit Industries
2+
#
23
# SPDX-License-Identifier: MIT
34

45
import board
56
import digitalio
67

7-
from adafruit_wiznet5k.adafruit_wiznet5k import WIZNET5K
8-
import adafruit_wiznet5k.adafruit_wiznet5k_socket as socket
98
from adafruit_httpserver import Server, Request, Response
9+
from adafruit_wiznet5k.adafruit_wiznet5k import WIZNET5K
10+
from adafruit_wiznet5k import adafruit_wiznet5k_socket as socket
1011

11-
print("Wiznet5k HTTPServer Test")
1212

1313
# For Adafruit Ethernet FeatherWing
1414
cs = digitalio.DigitalInOut(board.D10)
15+
1516
# For Particle Ethernet FeatherWing
1617
# cs = digitalio.DigitalInOut(board.D5)
18+
1719
spi_bus = board.SPI()
1820

1921
# Initialize ethernet interface with DHCP
@@ -22,7 +24,6 @@
2224
# Set the interface on the socket source
2325
socket.set_interface(eth)
2426

25-
# Initialize the server
2627
server = Server(socket, "/static", debug=True)
2728

2829

‎examples/httpserver_simpletest_manual.py renamed to ‎examples/httpserver_simpletest_manual_wifi.py

Lines changed: 6 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -2,21 +2,20 @@
22
#
33
# SPDX-License-Identifier: Unlicense
44

5-
import os
6-
75
import socketpool
86
import wifi
97

108
from adafruit_httpserver import Server, Request, Response
119

12-
ssid = os.getenv("WIFI_SSID")
13-
password = os.getenv("WIFI_PASSWORD")
10+
WIFI_SSID = "..."
11+
WIFI_PASSWORD = "..."
1412

15-
print("Connecting to", ssid)
16-
wifi.radio.connect(ssid, password)
17-
print("Connected to", ssid)
13+
print(f"Connecting to {WIFI_SSID}...")
14+
wifi.radio.connect(WIFI_SSID, WIFI_PASSWORD)
15+
print(f"Connected to {WIFI_SSID}")
1816

1917
pool = socketpool.SocketPool(wifi.radio)
18+
2019
server = Server(pool, "/static", debug=True)
2120

2221

0 commit comments

Comments
 (0)