Update documentation, bump version to v0.5.0

.github/workflows/ci.yml

@@ -1,23 +1,16 @@
 name: Build
 
 on:
-  push:
-    branches: [ main ]
-    paths:
-      - "**.py"
-      - "requirements.txt"
-      - ".github/workflows/ci.yml"
-      - "Makefile"
-      - "external/**"
-
   pull_request:
     branches: [ main ]
     paths:
-      - "**.py"
+      - "src/**"
+      - "tests/**"
+      - "external/**"
       - "requirements.txt"
       - ".github/workflows/ci.yml"
       - "Makefile"
-      - "external/**"
+      - ".pylintrc"
 
 jobs:
   test:

Makefile

@@ -1,4 +1,4 @@
-PYROBUSTA_VERSION := v0.4.0
+PYROBUSTA_VERSION := v0.5.0
 DEVICE ?= u0
 
 SRC_DIR := src

README.md

@@ -13,76 +13,73 @@ A lightweight HTTP server library for MicroPython designed for constrained embed
 - Query parameter parsing with percent encoding support
 - TLS support
 
-# Prerequisites
-
-## Setup virtual environment
-```bash
-python3 -m venv venv
-source venv/bin/activate
-python3 -m pip install -r requirements.txt
-```
-
-## Create pyrobusta.env in the project root (optional)
-
-```bash
-# pyrobusta.env
-wifi_ssid="<your-wifi-ssid>"
-wifi_password="<your-wifi-password>"
-tls="true"
-socket_max_con=2
-http_mem_cap=0.05
-...
+# Installation
+
+Use the mip package manager to install PyRobusta on your MicroPython-installed device.\
+The bare minimum requirement is 40KB of free heap, however, it is recommended to select\
+boards with more SRAM for usability and stability. The ESP32-C3 is a recommended entry-level\
+board leaving a user-friendly amount of memory after installing PyRobusta.
+
+If required, use the below script to connect to a Wi-Fi station in advance.
+```python
+from network import WLAN, STA_IF
+from time import sleep
+
+ssid = "<your-wifi-name>"
+password = "<your-password>"
+
+sta_if = WLAN(STA_IF)
+sta_if.active(True)
+sta_if.connect(ssid, password)
+
+timeout = 30
+while timeout > 0:
+    if sta_if.isconnected():
+        ip = sta_if.ifconfig()[0]
+        print(f"connected, IP={ip}")
+		break
+    sleep(1)
+    timeout -= 1
+
+if sta_if.isconnected():
+    print(sta_if.ifconfig()[0])
+else:
+    print("connection failed")
 ```
-pyrobusta.env contains runtime configuration, deployed to the device. This allows the user to override default behavior and configure optional settings.
 
-- rules such as ```make run-unix``` or ```make run-device``` also rely on pyrobusta.env, allowing the user to experiment with different settings
-- pyrobusta.env is ignored when running functional tests (```make test-unix```, ```make test-device```)
+Install and start PyRobusta by following the below steps. For more advanced usage,\
+check the included documentation reachable from the home page served by your device.
 
-Check [configuration.md](https://github.com/szeka9/PyRobusta/blob/main/docs/configuration.md) for all configuration options.
+```python
+# Download latest version of PyRobusta
+import mip
+mip.install("github:szeka9/PyRobusta")
 
+# Install assets
+from pyrobusta.utils.assets import install_www
+install_www()
 
-# Build and run example application
+# Start the server
+import asyncio
+from pyrobusta.server.http_server import HttpServer
 
-## Run on unix port
+async def main():
+    server = HttpServer()
+    asyncio.create_task(server.start_socket_server())
+    while True:
+        await asyncio.sleep(1)
 
-```bash
-make toolchain          # Setup mpy-cross and micropython
-make build              # Cross-compile, create build artifacts
-make stage-example      # Create runtime directory for unix port
-make run-unix           # Run example application on the unix port of micropython
+asyncio.run(main())
 ```
+Open a browser and type your device's IP in the address bar. You should be greeted\
+by the default home page.
 
-## Deploy to a device
-
-```bash
-make toolchain          # Setup mpy-cross and micropython
-make build              # Cross-compile, create build artifacts
-make deploy             # Upload build artifacts to device using mpremote
-make tls-cert           # Optional: generate self-signed certificate for the device
-make deploy-cert        # Optional: upload generated certificate to the device
-make deploy-example     # Deploy the selected example app using mpremote
-make run-device         # Optional: Reset the device and connect through REPL
-```
-```deploy-example``` and ```run-device``` uses the DEVICE argument
-set to ```u0``` (/dev/ttyUSB0) by default, passed to mpremote.
+![image info](./docs/img/home_page.png)
 
-Override the DEVICE argument to select a different device, e.g.
-```make DEVICE=a0 run-device``` for /dev/ttyACM0. Check mpremote --help
-for additional shortcuts.
+For fine-tuning heap usage, check the [dimensioning guide](./docs/dimensioning/http_dimensioning.md)\
+and [configuration settings](./docs/configuration.md).
 
-## Redeploy
+# Development
 
-When changing the source code, run the below rule for redeploying to the device.
-
-```bash
-make redeploy           # Will run the following rules: clean build clean-device deploy
-```
-
-## Unit tests, pylint, functional tests
-
-```bash
-make static-checkers    # Run static checkers (Pylint, black formatter)
-make unit-test          # Run unit tests
-make test-unix          # Run functional tests on the unix port
-make test-device        # Run functional tests on a device
-```
+Check the provided development guide to create and deploy custom builds\
+to your device: [development guide](./docs/development.md)

assets/www/examples.html

@@ -55,10 +55,10 @@ <h2>Server configuration</h2>
 # /pyrobusta.env
 
 socket_max_con=2                        # max number of socket connections, reduce it to lower memory usage
-http_multipart="false"                  # turn on/off multipart parser, increases memory usage when turned on
-http_mem_cap="0.05"                     # memory cap (% × 0.01) of usable heap for stream buffers
+http_multipart=False                    # turn on/off multipart parser, increases memory usage when turned on
+http_mem_cap=0.05                       # memory cap (% × 0.01) of usable heap for stream buffers
 http_served_paths="/www /lib/pyrobusta" # space delimited list of filesystem paths allowed to be served
-tls="false"                             # key.der and cert.der needs to be installed at / when set to true
+tls=False                               # key.der and cert.der needs to be installed at / when set to true
     </textarea>
     <p></p>
 
@@ -72,7 +72,7 @@ <h2>Simple Server Application</h2>
 import asyncio
 from gc import mem_free, mem_alloc
 
-from pyrobusta.server import http_server
+from pyrobusta.server.http_server import HttpServer
 from pyrobusta.protocol.http import HttpEngine
 from pyrobusta.utils import logging
 
@@ -94,14 +94,14 @@ <h2>Simple Server Application</h2>
 
     return "text/plain", (f"Free memory [{value_format}]: {free}\n")
 
+async def run_server():
+    server = HttpServer()
+    asyncio.create_task(server.start_socket_server())
+    while True:
+        await asyncio.sleep(1)
 
 def main():
-    http_server.main()
-    try:
-        asyncio.get_event_loop().run_forever()
-    except Exception as e:
-        logging.warning(f"loop stopped: {e}")
-        asyncio.get_event_loop().close()
+    asyncio.run(run_server())
     </textarea>
     <textarea readonly="true" rows="15">
 # /boot.py
@@ -153,7 +153,7 @@ <h2>Simple Server Application</h2>
 
     <div class="footer">
         <hr>
-        <address>PyRobusta v0.4.0 Web Server</address>
+        <address>PyRobusta v0.5.0 Web Server</address>
     </div>
 </body>
 </html>

assets/www/index.html

@@ -48,7 +48,7 @@ <h2>Available Resources</h2>
 
     <div class="footer">
         <hr>
-        <address>PyRobusta v0.4.0 Web Server</address>
+        <address>PyRobusta v0.5.0 Web Server</address>
     </div>
 
 </body>

dist/pyrobusta/assets/www/examples.html

@@ -55,10 +55,10 @@ <h2>Server configuration</h2>
 # /pyrobusta.env
 
 socket_max_con=2                        # max number of socket connections, reduce it to lower memory usage
-http_multipart="false"                  # turn on/off multipart parser, increases memory usage when turned on
-http_mem_cap="0.05"                     # memory cap (% × 0.01) of usable heap for stream buffers
+http_multipart=False                    # turn on/off multipart parser, increases memory usage when turned on
+http_mem_cap=0.05                       # memory cap (% × 0.01) of usable heap for stream buffers
 http_served_paths="/www /lib/pyrobusta" # space delimited list of filesystem paths allowed to be served
-tls="false"                             # key.der and cert.der needs to be installed at / when set to true
+tls=False                               # key.der and cert.der needs to be installed at / when set to true
     </textarea>
     <p></p>
 
@@ -72,7 +72,7 @@ <h2>Simple Server Application</h2>
 import asyncio
 from gc import mem_free, mem_alloc
 
-from pyrobusta.server import http_server
+from pyrobusta.server.http_server import HttpServer
 from pyrobusta.protocol.http import HttpEngine
 from pyrobusta.utils import logging
 
@@ -94,16 +94,18 @@ <h2>Simple Server Application</h2>
 
     return "text/plain", (f"Free memory [{value_format}]: {free}\n")
 
+async def run_server():
+    server = HttpServer()
+    asyncio.create_task(server.start_socket_server())
+    while True:
+        await asyncio.sleep(1)
 
 def main():
-    http_server.main()
-    try:
-        asyncio.get_event_loop().run_forever()
-    except Exception as e:
-        logging.warning(f"loop stopped: {e}")
-        asyncio.get_event_loop().close()
+    asyncio.run(run_server())
     </textarea>
-    <textarea readonly="true" rows="13">
+    <textarea readonly="true" rows="15">
+# /boot.py
+
 # This file is executed on every boot (including wake-boot from deepsleep)
 import machine
 from os import listdir
@@ -136,22 +138,22 @@ <h2>Simple Server Application</h2>
 [INFO] pyrobusta.server.http_server.init_pools: 2 connection(s) allowed
 [INFO] pyrobusta.server.http_server: started
 
-# You can now reach the device at 192.168.1.101:8080 (replace with your IP)
+# You can now reach the device at 192.168.1.101 (replace with your IP)
 # Press Ctrl-x to exit
     </textarea>
 
     <p>Use curl to test your application.</p>
     <textarea readonly="true" rows="6">
-$ curl "http://192.168.1.101:8080/app"
+$ curl "http://192.168.1.101/app"
 Free memory [bytes]: 115456
 
-$ curl "http://192.168.1.101:8080/app?format=%"
+$ curl "http://192.168.1.101/app?format=%"
 Free memory [%]: 71.76
     </textarea>
 
     <div class="footer">
         <hr>
-        <address>PyRobusta v0.4.0 Web Server</address>
+        <address>PyRobusta v0.5.0 Web Server</address>
     </div>
 </body>
 </html>

dist/pyrobusta/assets/www/index.html

@@ -48,7 +48,7 @@ <h2>Available Resources</h2>
 
     <div class="footer">
         <hr>
-        <address>PyRobusta v0.4.0 Web Server</address>
+        <address>PyRobusta v0.5.0 Web Server</address>
     </div>
 
 </body>

docs/development.md

@@ -0,0 +1,74 @@
+
+# Prerequisites
+
+## Setup virtual environment
+```bash
+python3 -m venv venv
+source venv/bin/activate
+python3 -m pip install -r requirements.txt
+```
+
+## Create pyrobusta.env in the project root (optional)
+
+```bash
+# pyrobusta.env
+wifi_ssid="<your-wifi-ssid>"
+wifi_password="<your-wifi-password>"
+tls="true"
+socket_max_con=2
+http_mem_cap=0.05
+...
+```
+pyrobusta.env contains runtime configuration, deployed to the device. This allows the user to override default behavior and configure optional settings.
+
+- rules such as ```make run-unix``` or ```make run-device``` also rely on pyrobusta.env, allowing the user to experiment with different settings
+- pyrobusta.env is ignored when running functional tests (```make test-unix```, ```make test-device```)
+
+Check [configuration.md](./configuration.md) for all configuration options.
+
+
+# Build and run example application
+
+## Run on unix port
+
+```bash
+make toolchain          # Setup mpy-cross and micropython
+make build              # Cross-compile, create build artifacts
+make stage-example      # Create runtime directory for unix port
+make run-unix           # Run example application on the unix port of micropython
+```
+
+## Deploy to a device
+
+```bash
+make toolchain          # Setup mpy-cross and micropython
+make build              # Cross-compile, create build artifacts
+make deploy             # Upload build artifacts to device using mpremote
+make tls-cert           # Optional: generate self-signed certificate for the device
+make deploy-cert        # Optional: upload generated certificate to the device
+make deploy-example     # Deploy the selected example app using mpremote
+make run-device         # Optional: Reset the device and connect through REPL
+```
+```deploy-example``` and ```run-device``` uses the DEVICE argument
+set to ```u0``` (/dev/ttyUSB0) by default, passed to mpremote.
+
+Override the DEVICE argument to select a different device, e.g.
+```make DEVICE=a0 run-device``` for /dev/ttyACM0. Check mpremote --help
+for additional shortcuts.
+
+## Redeploy
+
+When changing the source code, run the below rule for redeploying to the device.
+
+```bash
+make redeploy           # Will run the following rules: clean build clean-device deploy
+```
+
+## Unit tests, pylint, functional tests
+
+```bash
+make static-checkers    # Run static checkers (Pylint, black formatter)
+make unit-test          # Run unit tests
+make test-unix          # Run functional tests on the unix port
+make test-device        # Run functional tests on a device
+```