Created webapp.py (markdown)

2025-12-06 06:11:46 +00:00 · 2024-07-06 01:17:23 +02:00
parent 010bf6d637
commit a5e0bc302e
1 changed files with 170 additions and 0 deletions
--- a/webapp.py.md
+++ b/webapp.py.md
@@ -0,0 +1,170 @@
 # webapp.py WebApp 
 This document describes the detailed step-by-step process of how the `webapp.py` script works, including the specific methods, classes, and functions used at each step.
 ## Initialization and Start of WebApp
 ### Importing Modules
 - The `webapp.py` script imports several modules, including standard libraries (`threading`, `http.server`, `socketserver`, `logging`, `sys`, `signal`, `os`, `json`, `subprocess`) and custom modules (`Logger`, `shared_data`).
 ### Global Variables
 - `should_exit`: A flag used to signal when the server should shut down.
 ### Logger Initialization
 - The logger is initialized to capture events and errors.
 ## `CustomHandler` Class
 ### `__init__` Method
 - **Purpose**: Initializes the request handler with shared data.
 - **Key Steps**:
    1. **Initialize Shared Data**:
        - Sets up `self.shared_data` with shared data.
    2. **Call Parent Constructor**:
        - Calls the parent constructor to complete initialization.
 ### `log_message` Method
 - **Purpose**: Overrides the default logging behavior to suppress logging of GET requests.
 - **Key Steps**:
    1. **Log Non-GET Requests**:
        - Logs messages that are not GET requests.
 ### `do_GET` Method
 - **Purpose**: Handles GET requests to serve HTML files, configuration data, and the display image.
 - **Key Steps**:
    1. **Serve HTML Files**:
        - Calls `serve_file` for `index.html` and `config.html`.
    2. **Serve Configuration Data**:
        - Calls `serve_current_config` to serve the current configuration as JSON.
    3. **Restore Default Configuration**:
        - Calls `restore_default_config` to reset configurations to default.
    4. **Scan Wi-Fi Networks**:
        - Calls `scan_wifi` to scan for available Wi-Fi networks.
    5. **Serve Display Image**:
        - Calls `serve_image` to serve the current display image.
 ### `do_POST` Method
 - **Purpose**: Handles POST requests to save configuration data and connect to Wi-Fi.
 - **Key Steps**:
    1. **Save Configuration**:
        - Calls `save_configuration` to save posted configuration data.
    2. **Connect to Wi-Fi**:
        - Calls `connect_wifi` to connect to a specified Wi-Fi network.
 ### `serve_file` Method
 - **Purpose**: Serves an HTML file with dynamic content injection.
 - **Key Steps**:
    1. **Read and Serve File**:
        - Reads the file, injects dynamic content, and serves it.
 ### `serve_current_config` Method
 - **Purpose**: Serves the current configuration as JSON.
 - **Key Steps**:
    1. **Read and Serve Configuration**:
        - Reads the configuration file and sends it as JSON.
 ### `restore_default_config` Method
 - **Purpose**: Restores the default configuration and saves it to JSON.
 - **Key Steps**:
    1. **Restore and Save Configuration**:
        - Resets configurations to default, saves them, and serves the updated configuration.
 ### `serve_image` Method
 - **Purpose**: Handles requests to serve the display image.
 - **Key Steps**:
    1. **Read and Serve Image**:
        - Reads and serves the current display image file.
 ### `scan_wifi` Method
 - **Purpose**: Scans for available Wi-Fi networks and returns the results as JSON.
 - **Key Steps**:
    1. **Scan Networks**:
        - Runs the `iwlist` command to scan for Wi-Fi networks.
    2. **Parse and Serve Results**:
        - Parses the scan results and serves them as JSON.
 ### `parse_scan_result` Method
 - **Purpose**: Parses the scan output from `iwlist` to extract SSIDs.
 - **Key Steps**:
    1. **Extract SSIDs**:
        - Parses the scan output to extract and return a list of SSIDs.
 ### `connect_wifi` Method
 - **Purpose**: Connects to a specified Wi-Fi network using the provided SSID and password.
 - **Key Steps**:
    1. **Read Credentials**:
        - Reads the SSID and password from the POST request.
    2. **Update Network Configuration**:
        - Updates the NetworkManager configuration with the new credentials.
    3. **Connect to Network**:
        - Runs the `nmcli` command to connect to the network.
 ### `update_nmconnection` Method
 - **Purpose**: Updates the `preconfigured.nmconnection` file with the new SSID and password.
 - **Key Steps**:
    1. **Write Configuration**:
        - Writes the new network configuration to the file.
    2. **Set Permissions**:
        - Sets the correct permissions on the configuration file.
    3. **Reload Connection**:
        - Reloads the NetworkManager connections.
 ### `save_configuration` Method
 - **Purpose**: Saves the configuration posted from the client.
 - **Key Steps**:
    1. **Read and Update Configuration**:
        - Reads the posted configuration data, updates the current configuration, and saves it.
    2. **Reload Configuration**:
        - Reloads the configuration to apply the changes.
 ## `WebThread` Class
 ### `__init__` Method
 - **Purpose**: Initializes the web server thread with the specified handler class and port.
 - **Key Steps**:
    1. **Initialize Attributes**:
        - Sets up `self.shared_data`, `self.port`, and `self.handler_class`.
 ### `run` Method
 - **Purpose**: Runs the web server in a separate thread.
 - **Key Steps**:
    1. **Start Server**:
        - Starts the web server and handles requests until `should_exit` is set to `True`.
    2. **Handle Port Conflicts**:
        - If the port is already in use, increments the port number and retries.
    3. **Graceful Shutdown**:
        - Ensures the server is closed properly when shutting down.
 ### `shutdown` Method
 - **Purpose**: Shuts down the web server gracefully.
 - **Key Steps**:
    1. **Shutdown Server**:
        - Shuts down and closes the server.
 ## `handle_exit_web` Function
 ### Purpose
 - Handles exit signals to shut down the web server cleanly.
 - **Key Steps**:
    1. **Set Exit Flag**:
        - Sets `should_exit` to `True` to signal the server to stop.
    2. **Shutdown Server**:
        - Calls `shutdown` on the web server thread and waits for it to finish.
 ## Execution Flow when `webapp.py` is Run
 ### Step 1: Initialize Web Thread
 - An instance of the `WebThread` class is created with the `CustomHandler` and the specified port.
 ### Step 2: Start Main Loop
 - The main loop is started in a separate thread to handle web server requests.
 ### Step 3: Handle Requests
 - The web server handles GET and POST requests, serving HTML files, configuration data, and images, and processing configuration updates and Wi-Fi connections.
 ### Step 4: Handle Exit Signal
 - When an exit signal is received, the `handle_exit_web` function sets the exit flag and shuts down the server cleanly.
 ## Summary
 The `webapp.py` script manages the web interface of the e-ink display, serving HTML interface pages and the EPD image, handling GET and POST requests, and running a multithreaded web server for concurrent request handling. It ensures a clean exit on receiving system signals and captures events and errors for maintainability and ease of debugging.