microweb 0.1.3__tar.gz → 0.1.4__tar.gz

{microweb-0.1.3/microweb.egg-info → microweb-0.1.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: microweb
-Version: 0.1.3
+Version: 0.1.4
 Summary: A web server framework for MicroPython . Easily build and deploy web applications using MicroPython.
 Home-page: https://github.com/ishanoshada/microweb
 Author: Ishan Oshada
@@ -15,6 +15,8 @@ License-File: LICENSE
 Requires-Dist: pyserial
 Requires-Dist: esptool
 Requires-Dist: click
+Requires-Dist: adafruit-ampy
+Requires-Dist: mpremote
 Dynamic: author
 Dynamic: classifier
 Dynamic: description
@@ -84,6 +86,7 @@ With MicroWeb, you get routing, templates, JSON, static files, and more—making
 - [Features](#features)
 - [Installation](#installation)
 - [Usage](#usage)
+    - [Creating an Example Application](#creating-an-example-application)
     - [Flashing the ESP32](#flashing-the-esp32)
     - [Running a Custom Application](#running-a-custom-application)
 - [Example Usage](#example-usage)
@@ -93,6 +96,7 @@ With MicroWeb, you get routing, templates, JSON, static files, and more—making
 - [Wi-Fi Configuration](#wi-fi-configuration)
 - [Accessing the Web Server](#accessing-the-web-server)
 - [CLI Tool Usage Examples](#cli-tool-usage-examples)
+- [How to Code with MicroWeb](#how-to-code-with-microweb)
 - [ Feature Updates ](#feature-updates)
 - [Project Structure](#project-structure)
 - [Troubleshooting](#troubleshooting)
@@ -137,32 +141,32 @@ pip install .
 
 ---
 
+
 ## Usage
 
-Flash MicroPython and MicroWeb:
+### Creating an Example Application
+Generate a sample MicroWeb application with a basic web server, template, and documentation:
 
 ```bash
-microweb flash --port COM10
+microweb create --path example_app
 ```
 
-#### Options:
-
-* `--erase`
-  Erase the entire flash memory before flashing firmware.
-
-* `--esp8266`
-  Flash ESP8266 firmware instead of the default ESP32.
-
-* `--firmware firmware.bin`
-  Use a custom `.bin` firmware file. This overrides the default firmware for ESP32 or ESP8266 ( any ).
-
+- Creates a directory (default: `example_app`) containing `app.py`, `static/index.html`, and a `README.md` with usage instructions.
+- Option: `--path <directory>` to specify a custom directory name.
 
+### Flashing MicroPython and MicroWeb
+Flash MicroPython firmware and MicroWeb to your device:
 
+```bash
+microweb flash --port COM10
+```
 
----
+#### Options:
+- `--erase`: Erase the entire flash memory before flashing firmware.
+- `--esp8266`: Flash ESP8266 firmware instead of the default ESP32.
+- `--firmware firmware.bin`: Use a custom `.bin` firmware file, overriding the default firmware for ESP32 or ESP8266.
 
 ### Running a Custom Application
-
 Upload and run a MicroPython script:
 
 ```bash
@@ -173,7 +177,17 @@ microweb run app.py --port COM10
 - Uploads and executes the script.
 - Checks and uploads only changed files by default.
 - Prompts to run `microweb flash` if MicroPython is not detected.
-- After running `app.run()`, the ESP32 will host a Wi-Fi access point (AP) if it cannot connect to a configured network. You can then connect your device to this AP and access the web server using the ESP32's IP address (typically `http://192.168.4.1` in AP mode).
+- After running `app.run()`, the ESP32 will host a Wi-Fi access point (AP) if it cannot connect to a configured network. Connect to this AP and access the web server at `http://192.168.4.1` (typical IP in AP mode).
+
+### Listing Files on the Device
+List files on the MicroPython device's filesystem:
+
+```bash
+microweb ls --port COM10
+```
+
+- Displays all files and their sizes in the device's home directory.
+- Requires MicroPython to be installed on the device.
 
 ---
 
@@ -319,23 +333,26 @@ If no credentials are provided, loads `config.json`. If connection fails, starts
 - Use the control panel to update Wi-Fi, test routes, or submit forms.
 
 ---
+
 ## CLI Tool Usage Examples
 
 The following table summarizes common `microweb` CLI commands. See also: #changes.
 
 | Command Example                              | Description                                               |
 |----------------------------------------------|-----------------------------------------------------------|
-| `microweb exmples `                               | Show example commands for using microweb CLI.**          |
+| `microweb create --path example_app`         | Create an example MicroWeb app with `app.py`, `static/index.html`, and `README.md`. |
+| `microweb examples`                          | Show example commands for using the MicroWeb CLI.          |
 | `microweb flash --port COM10`                | Flash MicroPython firmware and upload MicroWeb files.      |
 | `microweb flash --port COM10 --erase`        | Erase ESP32 flash before installing MicroPython.           |
 | `microweb run app.py --port COM10`           | Upload and run a custom MicroPython script.                |
 | `microweb run app.py --check-only`           | Check static/template dependencies without uploading.      |
 | `microweb run app.py --force`                | Force upload all files, even if unchanged.                 |
-| `microweb run app.py --add-boot`             | Uploads a `boot.py` to auto-run your app on boot.          |
-| `microweb run app.py --remove-boot`          | Removes `boot.py` from the ESP32.                          |
+| `microweb run app.py --add-boot`             | Upload a `boot.py` to auto-run your app on boot.           |
+| `microweb run app.py --remove-boot`          | Remove `boot.py` from the ESP32.                           |
 | `microweb run app.py --static static/`       | Specify a custom static files folder.                      |
 | `microweb run app.py --no-stop`              | Do not reset ESP32 before running the app.                 |
 | `microweb run app.py --timeout 600`          | Set a custom timeout (in seconds) for app execution.       |
+| `microweb ls --port COM10`                   | List files and their sizes on the ESP32 filesystem.        |
 | `microweb remove --port COM10`               | List files on ESP32 (requires `--remove` to actually delete). |
 | `microweb remove --port COM10 --remove`      | Remove all files in ESP32 home directory.                  |
 
@@ -347,6 +364,284 @@ The following table summarizes common `microweb` CLI commands. See also: #change
 For more details, run `microweb --help`.
 
 
+
+---
+
+## How to Code with MicroWeb
+
+This section guides you through writing MicroWeb applications for MicroPython on ESP32. MicroWeb simplifies web development with features like dynamic routing, template rendering, static file serving, JSON responses, and Wi-Fi configuration. Below, we explain the key components of coding with MicroWeb, with examples to help you get started.
+
+### **1. Setting Up the MicroWeb Application**
+To start, import the `MicroWeb` class and initialize the app. You can configure debugging and Wi-Fi settings (access point or station mode) in the constructor.
+
+```python
+from microweb import MicroWeb
+
+# Initialize MicroWeb with debug mode and access point (AP) settings
+app = MicroWeb(debug=True, ap={'ssid': 'MyESP32', 'password': 'mypassword'})
+```
+
+**Explanation**:
+- `debug=True`: Enables detailed logging for troubleshooting, useful during development.
+- `ap={'ssid': ..., 'password': ...}`: Configures the ESP32 to create a Wi-Fi access point if it cannot connect to a network. Alternatively, use `internet={'ssid': ..., 'password': ...}` for station mode to connect to an existing Wi-Fi network.
+- If no Wi-Fi credentials are provided, MicroWeb loads settings from `config.json` or starts a default AP (SSID: `ESP32-MicroWeb`, password: `12345678`).
+
+### **2. Defining Routes**
+Routes map URLs to handler functions. Use the `@app.route()` decorator to define endpoints and specify HTTP methods (e.g., GET, POST).
+
+```python
+@app.route('/')
+def home(req):
+    return app.render_template('index.html', message='Welcome to MicroWeb!')
+```
+
+**Explanation**:
+- The `@app.route('/')` decorator maps the root URL (`/`) to the `home` function.
+- The `req` parameter provides access to request data (e.g., `req.method`, `req.form`, `req.json()`).
+- `app.render_template` renders an HTML template (`index.html`) with dynamic variables (e.g., `message`).
+
+For dynamic routing with URL parameters:
+```python
+@app.route('/greet/<name>')
+def greet(req, match):
+    name = match.group(1) if match else 'Anonymous'
+    return {'message': f'Hello, {name}!', 'status': 'success'}
+```
+
+**Explanation**:
+- `/greet/<name>` captures a URL parameter (e.g., `/greet/Alice` sets `name` to `Alice`).
+- The `match` parameter contains the parsed URL parameters, accessed via `match.group(1)`.
+
+### **3. Handling HTTP Methods**
+MicroWeb supports multiple HTTP methods (GET, POST, etc.) for a single route using the `methods` parameter.
+
+```python
+@app.route('/api/methods', methods=['GET', 'POST'])
+def methods(req):
+    if req.method == 'GET':
+        return app.json_response({'method': 'GET', 'message': 'This is a GET request'})
+    elif req.method == 'POST':
+        data = req.json()
+        return app.json_response({'method': 'POST', 'received': data})
+```
+
+**Explanation**:
+- The `methods=['GET', 'POST']` parameter allows the route to handle both GET and POST requests.
+- `req.method` checks the HTTP method to determine the response.
+- `req.json()` parses JSON data from the POST request body.
+- `app.json_response` returns a JSON response with the specified data.
+
+### **4. Rendering Templates**
+MicroWeb supports rendering HTML templates with dynamic data, ideal for web interfaces. Templates use a simple syntax (e.g., `{% variable %}`) for dynamic content.
+
+```python
+@app.route('/submit', methods=['GET', 'POST'])
+def submit_form(req):
+    if req.method == 'POST':
+        return app.render_template('result.html', data=str(req.form), method='POST')
+    else:
+        return app.render_template('form.html')
+```
+
+**Explanation**:
+- Templates (e.g., `form.html`, `result.html`) must be in the `static/` directory or a specified folder.
+- `req.form` accesses form data from POST requests.
+- `app.render_template` passes variables (e.g., `data`, `method`) to the template for dynamic rendering.
+
+**Example Template (`static/result.html`)**:
+```html
+<!DOCTYPE html>
+<html>
+<head>
+    <title>Form Result</title>
+    <link rel="stylesheet" href="/style.css">
+</head>
+<body>
+    <p><strong>Method:</strong> {% method %}</p>
+    <p><strong>Data:</strong> {% data %}</p>
+</body>
+</html>
+```
+
+**Explanation**:
+- The `{% method %}` and `{% data %}` placeholders are replaced with the `method` and `data` variables passed to `app.render_template`.
+- The `<link rel="stylesheet" href="/style.css">` tag references a static CSS file, served via `app.add_static('/style.css', 'style.css')`.
+- Ensure `result.html` and `style.css` are in the `static/` directory and uploaded to the ESP32.
+
+**Example Form Template (`static/form.html`)**:
+```html
+<!DOCTYPE html>
+<html>
+<head>
+    <title>Form</title>
+    <link rel="stylesheet" href="/style.css">
+</head>
+<body>
+    <form method="POST" action="/submit">
+        <input type="text" name="username" placeholder="Enter your name">
+        <button type="submit">Submit</button>
+    </form>
+</body>
+</html>
+```
+
+**Explanation**:
+- The form submits data to `/submit` via POST, which is processed by the `submit_form` route.
+- The `style.css` file is served as a static file, ensuring consistent styling across templates.
+
+### **5. Serving Static Files**
+MicroWeb allows serving static files like CSS, JavaScript, or images to enhance web interfaces.
+
+```python
+app.add_static('/style.css', 'style.css')
+```
+
+**Explanation**:
+- `app.add_static` maps a URL path (`/style.css`) to a file in the `static/` directory (`style.css`).
+- Static files must be uploaded to the ESP32’s filesystem using:
+  ```bash
+  microweb run app.py --static static/ --port COM10
+  ```
+- In the `result.html` example, `<link rel="stylesheet" href="/style.css">` loads the CSS file for styling.
+
+### **6. JSON Responses**
+MicroWeb simplifies JSON responses for API endpoints.
+
+```python
+@app.route('/api/status', methods=['GET'])
+def status(req):
+    return app.json_response({'status': 'running', 'ip': wifi.get_ip()})
+```
+
+**Explanation**:
+- `app.json_response` formats the dictionary as JSON and sets the `Content-Type` to `application/json`.
+- The `wifi` module (if available) retrieves the ESP32’s IP address.
+
+### **7. Custom HTTP Headers**
+You can set custom headers using the `Response` class.
+
+```python
+from microweb import Response
+
+@app.route('/headers')
+def headers_example(req):
+    resp = Response('Custom header set!', content_type='text/plain')
+    resp.headers['X-Custom-Header'] = 'Value'
+    return resp
+```
+
+**Explanation**:
+- The `Response` class allows custom content types and headers.
+- `resp.headers` sets additional HTTP headers for the response.
+
+### **8. Wi-Fi Integration**
+MicroWeb handles Wi-Fi configuration, allowing the ESP32 to act as an access point or connect to a network.
+
+```python
+import wifi
+from microweb import MicroWeb
+
+app = MicroWeb(debug=True, ap={'ssid': 'MyESP32', 'password': 'mypassword'})
+
+@app.route('/api/status', methods=['GET'])
+def status(req):
+    return app.json_response({'status': 'running', 'ip': wifi.get_ip()})
+```
+
+**Explanation**:
+- The `wifi` module (part of MicroWeb or MicroPython) provides functions like `wifi.get_ip()` to retrieve the device’s IP address.
+- If Wi-Fi connection fails, the ESP32 starts an access point with the specified `ssid` and `password`.
+
+### **9. Running the Application**
+Start the web server with `app.run()`.
+
+```python
+if __name__ == '__main__':
+    app.run()
+```
+
+**Explanation**:
+- `app.run()` starts the MicroWeb server, listening for HTTP requests.
+- Use the CLI to upload and run the script:
+  ```bash
+  microweb run app.py --port COM10
+  ```
+
+### **10. Best Practices**
+- **Error Handling**: Add try-except blocks for `wifi.get_ip()` or `req.form` to handle network or input errors.
+  ```python
+  try:
+      ip = wifi.get_ip()
+  except Exception as e:
+      ip = 'N/A'
+  return app.json_response({'status': 'running', 'ip': ip})
+  ```
+- **File Management**: Ensure templates (`index.html`, `form.html`, `result.html`) and static files (`style.css`) exist in the `static/` directory before running.
+- **Security**: Avoid hardcoding Wi-Fi credentials; use `config.json` or the web interface for configuration.
+- **Debugging**: Enable `debug=True` during development to log errors and requests.
+- **Testing**: Test routes with tools like `curl` or a browser (e.g., `http://192.168.4.1/` in AP mode).
+
+### **11. Example: Putting It All Together**
+Below is a complete MicroWeb application combining routes, templates, static files, and JSON responses, including the `result.html` template.
+
+```python
+import wifi
+from microweb import MicroWeb
+
+app = MicroWeb(debug=True, ap={'ssid': 'MyESP32', 'password': 'mypassword'})
+
+@app.route('/')
+def home(req):
+    return app.render_template('index.html', message='Welcome to MicroWeb!')
+
+@app.route('/api/status', methods=['GET'])
+def status(req):
+    return app.json_response({'status': 'running', 'ip': wifi.get_ip()})
+
+@app.route('/api/echo', methods=['POST'])
+def echo(req):
+    data = req.form
+    return app.json_response({'received': data})
+
+@app.route('/submit', methods=['GET', 'POST'])
+def submit_form(req):
+    if req.method == 'POST':
+        return app.render_template('result.html', data=str(req.form), method='POST')
+    else:
+        return app.render_template('form.html')
+
+app.add_static('/style.css', 'style.css')
+
+if __name__ == '__main__':
+    app.run()
+```
+
+**Explanation**:
+- Combines template rendering (`/`, `/submit`), JSON responses (`/api/status`, `/api/echo`), and static file serving (`/style.css`).
+- The `/submit` route uses `result.html` (as shown above) to display form data and the HTTP method.
+- Upload and run with:
+  ```bash
+  microweb run app.py --port COM10 --static static/
+  ```
+- Access at `http://192.168.4.1` (or the ESP32’s IP address).
+
+### **12. Testing Your Application**
+- **Browser**: Open `http://<ESP32-IP>/` (e.g., `http://192.168.4.1`) to access the web server.
+- **curl**:
+  ```bash
+  curl http://192.168.4.1/api/status
+  curl -X POST -d 'username=Alice' http://192.168.4.1/api/echo
+  curl -X POST -d 'username=Alice' http://192.168.4.1/submit
+  ```
+- **CLI Logs**: Monitor logs with `debug=True` to debug issues.
+- **Template Testing**: Submit a form via `http://192.168.4.1/submit` to see the `result.html` output, styled with `style.css`.
+
+### **13. Next Steps**
+- Explore the portfolio demo (`tests/portfolio/`) for a full-featured web app example.
+- Use `microweb create --path my_app` to generate a template project.
+- Add boot script support with `microweb run app.py --add-boot --port COM10` for auto-running on power-up.
+- Check the [CLI Tool Usage Examples](#cli-tool-usage-examples) for advanced commands.
+
 ---
 
 ### Feature Updates
@@ -388,6 +683,8 @@ microweb/
 ```
 
 
+
+
 ---
 
 ## Troubleshooting