chore: major project cleanup and documentation improvements. (#8)

chore: remove debugging files. Remove client app and rename firmware directory.
docs: add CONTRIBUTING.md guideline and improve overall documentation.

Author: eleonel

README.md

@@ -1,102 +1,131 @@
-# WebScreen Firmware
+# WebScreen
 
-**WebScreen - Stay Connected, Stay Focused - Subscribe: https://www.crowdsupply.com/hw-media-lab/webscreen**
+WebScreen is an ESP32-based platform that allows users to run dynamic JavaScript applications using the Elk engine, LVGL for UI rendering, and an SD card for storing multiple JS apps. It supports secure HTTPS communication (with full chain certificates), BLE, MQTT, and more. If no JavaScript app is found on the SD card, a fallback notification app is used.
 
-## Project Description
+## Features
 
-WebScreen is an open-source project that provides firmware for a customizable secondary display that sits atop your monitor like a webcam. Powered by an ESP32-S3 microcontroller and featuring a vibrant AMOLED display, WebScreen brings essential notifications, reminders, and visuals directly into your line of sight. This repository contains the source code and instructions to build and customize your own WebScreen device.
+- **Dynamic JavaScript Execution**  
+  Use Elk to run user-provided JS code stored on the SD card.
 
-## Features
+- **Configurable App Selection**  
+  Specify the JavaScript file to run via a JSON configuration file (`webscreen.json`).
 
-- **AMOLED Display**: High-quality display with 240 x 536 resolution and 16.7 million colors.
-- **ESP32-S3 Microcontroller**: Ensures smooth operation and robust performance.
-- **Wi-Fi and Bluetooth Connectivity**: Stay connected with wireless capabilities.
-- **Customizable Firmware**: Open-source code allows for personal modifications and enhancements.
-- **Micro SD Card Support**: Load custom JavaScript applications and store additional data.
-- **LVGL Graphics Library**: Advanced graphics handling for a rich user interface.
+- **Rich UI with LVGL**  
+  Draw labels, images, animations, charts, meters, and more.
 
-## Hardware Requirements
+- **Secure HTTP Requests**  
+  Load a full chain SSL certificate from SD to connect to HTTPS APIs securely.
 
-- **ESP32-S3 Development Board**
-- **RM67162 AMOLED Display**
-- **Micro SD Card (optional)**
-- **Supporting Components**: Resistors, capacitors, connectors as per the BOM.
+- **BLE & MQTT Integration**  
+  Communicate with BLE devices and subscribe/publish to MQTT topics.
 
-## Software Requirements
+- **Fallback Mode**  
+  If no JS app is found or configuration fails, a built-in fallback application is launched.
 
-- **Arduino IDE**: For compiling and uploading the firmware.
-- **LVGL Library**: Graphics library for the display ([LVGL GitHub](https://github.com/lvgl/lvgl)).
-- **Elk JS Engine**: Lightweight JavaScript engine for embedded systems.
-- **Wi-Fi and Networking Libraries**: For network connectivity.
+## Quick Start
 
-## Installation Instructions
+### Hardware Upload via USB (JTAG Upload Port)
 
-1. **Set Up Arduino IDE**:
-   - Install the latest version of the [Arduino IDE](https://www.arduino.cc/en/software).
-   - Add the ESP32 board support to your Arduino IDE. Instructions can be found [here](https://github.com/espressif/arduino-esp32/blob/master/docs/arduino-ide/boards_manager.md).
+The board uses USB as the JTAG upload port. When using USB for uploading:
+- **CDC_ON_BOOT** must be enabled so that serial port information is printed on USB.
+- If the port isn’t detected (because USB is used for other functions), you may need to enter upload mode manually:
+  - **Step 1:** With power off, press and hold the BOOT button (located behind the RST button).
+  - **Step 2:** Connect USB.
+  - **Step 3:** Press and hold the BOOT button, then press the RESET button and release the BOOT button.
 
-2. **Clone This Repository**:
-   ```bash
-   https://github.com/HW-Lab-Hardware-Design-Agency/WebScreen-Software.git
-   ```
+### Arduino IDE
 
-3. **Install Required Libraries**:
-   - Open the Arduino IDE and navigate to **Sketch** > **Include Library** > **Manage Libraries**.
-   - Install the following libraries:
-     - **LVGL**
-     - **WiFi**
-     - **ESPping**
-     - **ArduinoJson**
-     - **YAMLDuino**
-     - **SD_MMC**
+1. **Install ESP32 Boards**  
+   In Arduino Preferences, under the Settings tab, add:  
+   `https://raw.githubusercontent.com/espressif/arduino-esp32/gh-pages/package_esp32_index.json`  
+   to the **Additional Boards Manager URLs**.
+2. Click **OK**.  
+3. Open the **Board Manager** via Tools → Board Manager, search for **ESP32**, and install the ESP32-Arduino SDK (version 2.0.3 or above).  
 
-4. **Configure Pin Definitions**:
-   - Review and modify `pins_config.h` according to your hardware setup.
+   ![](docs/arduino_boards_manager.png)
+4. Copy all files from the repository’s **lib** folder into your Arduino libraries folder (see [manual installation instructions](https://docs.arduino.cc/software/ide-v1/tutorials/installing-libraries#manual-installation)).
+5. In the Tools menu, select the correct board settings as shown below.  
 
-5. **Compile and Upload**:
-   - Open the desired `.ino` file in the Arduino IDE.
-   - Connect your ESP32-S3 board to your computer via USB.
-   - Select the correct board and port under **Tools**.
-   - Click **Upload** to compile and upload the firmware to your device.
+   ![](docs/arduino_tools_settings.png)
 
-## Usage Instructions
+## Configuration
 
-- **Connecting to Wi-Fi**:
-  - The firmware reads Wi-Fi credentials from the `/webscreen.yml` file on the SD card.
-  - Ensure your SD card contains the `webscreen.yml` file with your network SSID and password.
+The project uses an SD card file named `webscreen.json` to configure settings. An example file looks like this:
 
-- **Interacting with the Display**:
-  - The device displays notifications and visuals based on the firmware logic.
-  - You can customize the displayed content by modifying the firmware or loading custom JavaScript applications via the SD card.
+```json
+{
+  "settings": {
+    "wifi": {
+      "ssid": "ssid",
+      "pass": "pass"
+    }
+  },
+  "script": "timeapi_app.js",
+  "last_read": 2
+}
+```
 
-- **Running JavaScript Applications**:
-  - Place your JavaScript files on the SD card.
-  - The Elk JS engine will execute the scripts, allowing for dynamic functionality.
+- The `"settings"` object holds Wi‑Fi credentials.
+- The `"script"` key specifies which JavaScript file (e.g., `/timeapi_app.js`) will be loaded from the SD card.
+- If the key is omitted, the default file `/app.js` is used.
+- The `"last_read"` value is updated automatically on configuration reads.
 
-## File Structure
+## Building & Running
 
-- `main.cpp`: The main firmware file containing the setup and loop functions.
-- `pins_config.h`: Pin definitions and configurations.
-- `rm67162.h` / `rm67162.cpp`: Driver code for the RM67162 AMOLED display.
-- `elk.h`: Header file for the Elk JS engine.
-- `notification.h`: Header file for the notification image resource.
-- `other .ino and .cpp files`: Additional examples and functionalities.
+- **Compilation:**  
+  The project is built with the Arduino ESP32 core. Ensure you have installed all required libraries (LVGL, SD_MMC, NimBLE, PubSubClient, etc.).
 
-## Contributing
+- **Runtime Modes:**  
+  At startup, the firmware checks for the existence of the JavaScript file specified in `webscreen.json`. If found, it launches the dynamic JS environment; otherwise, it falls back to a default notification app.
 
-We welcome contributions from the community! If you'd like to contribute:
+- **Debug Output:**  
+  All operations are logged to the serial console for troubleshooting (including Wi‑Fi, HTTPS connections, and JavaScript execution status).
 
-1. Fork the repository.
-2. Create a new branch for your feature or bugfix.
-3. Commit your changes and push to your fork.
-4. Create a pull request detailing your changes.
+## JavaScript API
 
-## License
+The firmware exposes numerous functions to your JavaScript applications. Some highlights include:
+- **Basic:** `print()`, `delay()`
+- **Wi‑Fi:** `wifi_connect()`, `wifi_status()`, `wifi_get_ip()`
+- **HTTP:** `http_get()`, `http_post()`, `http_delete()`, `http_set_ca_cert_from_sd()`, `parse_json_value()`
+- **SD Card:** `sd_read_file()`, `sd_write_file()`, `sd_list_dir()`, `sd_delete_file()`
+- **BLE:** `ble_init()`, `ble_is_connected()`, `ble_write()`
+- **UI Drawing:** `draw_label()`, `draw_rect()`, `show_image()`, `create_label()`, `label_set_text()`
+- **Image Handling:** `create_image()`, `create_image_from_ram()`, `rotate_obj()`, `move_obj()`, `animate_obj()`
+- **Styles & Layout:** `create_style()`, `obj_add_style()`, `style_set_*()`, `obj_align()`
+- **Advanced Widgets:** Meter, Message Box, Span, Window, TileView, Line
+- **MQTT:** `mqtt_init()`, `mqtt_connect()`, `mqtt_publish()`, `mqtt_subscribe()`, `mqtt_loop()`, `mqtt_on_message()`
+
+For a full list and examples of usage, see the [JavaScript API Reference](docs/API.md).
 
-This project is licensed under the **MIT License** - see the [LICENSE](LICENSE) file for details.
+## Secure HTTPS Connections
 
-## Acknowledgments
+To call secure APIs (e.g., using `http_get()`), load a full chain certificate stored on the SD card using:
+```js
+http_set_ca_cert_from_sd("/timeapi.pem");
+```
+### Creating a Full Chain Certificate
+1. **Obtain Certificates:**  
+   Collect your server certificate and the intermediate certificate(s). Optionally, include the root certificate.
+2. **Concatenate Certificates:**  
+   Use a text editor or command-line tool:
+   ```bash
+   cat server.crt intermediate.crt root.crt > fullchain.pem
+   ```
+   Ensure each certificate block starts with `-----BEGIN CERTIFICATE-----` and ends with `-----END CERTIFICATE-----`.
+3. **Deploy:**  
+   Copy the resulting `fullchain.pem` file to the SD card.
+4. **Usage:**  
+   Your JavaScript app should load it with `http_set_ca_cert_from_sd()` to enable secure HTTPS requests.
+
+## Support & Contributions
+
+- **Bugs & Issues:**  
+  Please report issues or feature requests via the repository’s [issue tracker](https://github.com/HW-Lab-Hardware-Design-Agency/WebScreen-Software/issues).
+- **Contributing:**  
+  Contributions are welcome! See [CONTRIBUTING.md](docs/CONTRIBUTING.md) for guidelines.
+- **Donations:**  
+  If you find this project useful, consider donating or sponsoring the work.
+
+## License
 
-- **LVGL**: Open-source graphics library.
-- **Elk JS Engine**: Embedded JavaScript engine.
-- **Arduino Community**: For the development environment and extensive libraries.
+This project is open source. See the [LICENSE](LICENSE) file for details.