Bjorn.py Main File

Bjorn.py.md

@@ -0,0 +1,155 @@
+# Bjorn.py 
+
+This document describes the detailed step-by-step process of how the `Bjorn.py` python file works, including the specific methods, classes, and functions used at each step.
+This is the main Python File of Bjorn.
+
+## Initialization and Start of Bjorn
+
+### Importing Modules
+- **Modules**:
+    - `threading`, `signal`, `logging`, `time`, `sys`, `subprocess`
+    - Custom modules: `shared_data`, `Display`, `handle_exit_display`, `Commentaireia`, `web_thread`, `handle_exit_web`, `Orchestrator`, `NetworkScanner`, `Logger`
+
+### Creating `Bjorn` Instance
+- **Code**:
+    ```python
+    bjorn = Bjorn(shared_data)
+    ```
+- **Purpose**: Initializes the `Bjorn` class with shared data.
+
+### Starting Threads
+- **Code**:
+    ```python
+    display_thread = threading.Thread(target=display.run)
+    bjorn_thread = threading.Thread(target=bjorn.run)
+    ```
+- **Purpose**: Creates and starts threads for the display and Bjorn's main operations.
+
+### Handling Signals
+- **Code**:
+    ```python
+    signal.signal(signal.SIGINT, lambda sig, frame: handle_exit(sig, frame, display_thread, bjorn_thread))
+    signal.signal(signal.SIGTERM, lambda sig, frame: handle_exit_webserver(sig, frame))
+    ```
+- **Purpose**: Sets up signal handlers to ensure a clean exit when the application is terminated.
+
+## `Bjorn` Class
+
+### `__init__` Method
+- **Purpose**: Initializes the main components of the application, including the `Commentaireia` instance and a semaphore to limit concurrent threads.
+
+### `run` Method
+- **Purpose**: Main loop for the `Bjorn` application.
+- **Key Steps**:
+    1. **Wait for Startup Delay**:
+        - **Condition**:
+            ```python
+            if hasattr(self.shared_data, 'startup_delay') and self.shared_data.startup_delay > 0:
+            ```
+        - **Action**:
+            ```python
+            time.sleep(self.shared_data.startup_delay)
+            ```
+    2. **Check Wi-Fi Connection**:
+        - **Loop**:
+            ```python
+            while not self.shared_data.should_exit and not is_wifi_connected():
+            ```
+        - **Action**:
+            ```python
+            time.sleep(5)
+            ```
+    3. **Start Network Scanner and Orchestrator**:
+        - **Code**:
+            ```python
+            self.scanner = NetworkScanner(self.shared_data)
+            with self.semaphore:
+                self.scanner.scan()
+            self.orchestrator = Orchestrator()
+            with self.semaphore:
+                self.orchestrator.run()
+            ```
+
+## Helper Functions
+
+### `handle_exit`
+- **Purpose**: Handles the termination of the main and display threads.
+- **Parameters**: `sig`, `frame`, `display_thread`, `bjorn_thread`
+- **Key Steps**:
+    1. **Set Exit Flag**:
+        ```python
+        shared_data.should_exit = True
+        ```
+    2. **Handle Display Exit**:
+        ```python
+        handle_exit_display(sig, frame, display_thread)
+        ```
+    3. **Join Threads**:
+        ```python
+        if display_thread.is_alive():
+            display_thread.join()
+        if bjorn_thread.is_alive():
+            bjorn_thread.join()
+        ```
+
+### `handle_exit_webserver`
+- **Purpose**: Handles the termination of the web server thread.
+- **Parameters**: `sig`, `frame`
+- **Key Steps**:
+    1. **Set Exit Flag**:
+        ```python
+        shared_data.should_exit = True
+        ```
+    2. **Handle Web Exit**:
+        ```python
+        handle_exit_web(sig, frame)
+        ```
+    3. **Join Web Thread**:
+        ```python
+        if web_thread.is_alive():
+            web_thread.join()
+        ```
+
+### `is_wifi_connected`
+- **Purpose**: Checks for Wi-Fi connectivity using the `nmcli` command.
+- **Code**:
+    ```python
+    result = subprocess.run(['nmcli', '-t', '-f', 'active', 'dev', 'wifi'], stdout=subprocess.PIPE, text=True)
+    return 'yes' in result.stdout
+    ```
+
+## Execution Flow
+
+1. **Start Threads**:
+    - **Loading Configuration**:
+        ```python
+        shared_data.load_config()
+        ```
+    - **Starting Display Thread**:
+        ```python
+        display = Display(shared_data)
+        display_thread.start()
+        ```
+    - **Starting Bjorn Thread**:
+        ```python
+        bjorn_thread.start()
+        ```
+    - **Starting Web Server Thread (if enabled)**:
+        ```python
+        if shared_data.config["websrv"]:
+            web_thread.start()
+        ```
+
+2. **Handle Signals**:
+    - **SIGINT**:
+        ```python
+        signal.signal(signal.SIGINT, lambda sig, frame: handle_exit(sig, frame, display_thread, bjorn_thread))
+        ```
+    - **SIGTERM**:
+        ```python
+        signal.signal(signal.SIGTERM, lambda sig, frame: handle_exit_webserver(sig, frame))
+        ```
+
+## Summary
+
+The `Bjorn` application orchestrates various components including network scanning, display, and web server functionalities. The main operations are managed by the `Bjorn` class, which ensures proper startup, operation, and clean termination of the application. Helper functions handle signal-based exits, ensuring that all threads are properly terminated.