diff --git a/webapp.py.md b/webapp.py.md new file mode 100644 index 0000000..0241da8 --- /dev/null +++ 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.