microweb 0.1.3__py3-none-any.whl → 0.1.4__py3-none-any.whl

microweb/cli.py

@@ -46,7 +46,7 @@ def check_micropython(port):
             print_colored(f"mpremote output:\n{result.stdout.strip()}\n{result.stderr.strip()}", color='yellow')
             return False
     except Exception as e:
-        print_colored(f"Error checking MicroPython via mpremote: {e}", color='red')
+        print_colored(f"Error checking MicroPython via mpremote: {e}. The app may be running boot.py.", color='blue')
         return False
 
 def get_remote_file_info(port):
@@ -475,6 +475,7 @@ def run(file, port, check_only, static, force, no_stop, timeout, add_boot, remov
                 if result.returncode != 0:
                     print_colored(f"❌ Error running {file}: return code {result.returncode}", color='red')
                     print_colored(f"stdout:\n{result.stdout.strip()}\nstderr:\n{result.stderr.strip()}", color='red')
+                    print_colored(f"try microweb flash --port COM10 ",color="cyan")
                     return
                 if upload_count > 0:
                     print_colored(f"📊 Uploaded {upload_count} file(s), skipped {len(files_skipped)} file(s)", color='green')
@@ -489,6 +490,8 @@ def run(file, port, check_only, static, force, no_stop, timeout, add_boot, remov
     except Exception as e:
         print_colored(f"❌ Error: {e}", color='red')
 
+
+
 @cli.command()
 @click.option('--port', default=None, help='Serial port, e.g., COM10')
 @click.option('--remove', 'remove_everything', is_flag=True, help='Actually remove all files in the ESP32 home directory')
@@ -506,51 +509,239 @@ def remove(port, remove_everything):
     try:
         if remove_everything:
             print_colored("Removing all files in ESP32 home directory...", color='yellow')
-            cmd_ls = ['mpremote', 'connect', port, 'ls']
-            result = subprocess.run(cmd_ls, capture_output=True, text=True, timeout=10)
-            if result.returncode == 0:
-                files = []
-                for line in result.stdout.strip().split('\n'):
-                    parts = line.strip().split()
-                    if len(parts) >= 2:
-                        filename = ' '.join(parts[1:])
-                        files.append(filename)
-                for filename in files:
-                    if filename in ('.', '..'):
-                        continue
-                    print_colored(f"Removing {filename}...", color='cyan')
-                    cmd_rm = [
-                        'mpremote', 'connect', port, 'exec',
-                        f"import os; import shutil; "
-                        f"shutil.rmtree('{filename}') if hasattr(__import__('shutil'), 'rmtree') and os.path.isdir('{filename}') "
-                        f"else (os.remove('{filename}') if '{filename}' in os.listdir() else None)"
-                    ]
-                    subprocess.run(cmd_rm, capture_output=True, text=True, timeout=10)
-                print_colored("All files in ESP32 home directory removed.", color='green')
-            else:
-                print_colored(f"Error listing files: {result.stderr}", color='red')
+            remote_files = get_remote_file_info(port)
+            if not remote_files:
+                print_colored("No files found or error accessing filesystem.", color='yellow')
+                return
+            for filename in remote_files.keys():
+                if filename in ('.', '..'):
+                    continue
+                print_colored(f"Removing {filename}...", color='cyan')
+                cmd_rm = ['mpremote', 'connect', port, 'rm', filename]
+                result = subprocess.run(cmd_rm, capture_output=True, text=True, timeout=10)
+                if result.returncode != 0:
+                    print_colored(f"Error removing {filename}: {result.stderr}", color='red')
+            print_colored("All files in ESP32 home directory removed.", color='green')
         else:
             print_colored("Dry run: No files were removed. Use --remove to actually delete all files in the ESP32 home directory.", color='yellow')
     except Exception as e:
         print_colored(f"Error removing files: {e}", color='red')
 
+
+
+@cli.command()
+@click.option('--path', default='example_app', show_default=True, help='Directory to create the example app')
+def create(path):
+    """Create an example MicroWeb app with app.py, static/index.html, and README.md."""
+    try:
+        os.makedirs(path, exist_ok=True)
+        os.makedirs(os.path.join(path, 'static'), exist_ok=True)
+        
+        app_content = """import wifi
+from microweb import MicroWeb
+
+# Define a simple User model to store and retrieve user data
+class User:
+    def __init__(self, user_id, name, email):
+        self.user_id = user_id
+        self.name = name
+        self.email = email
+    
+    def to_dict(self):
+        return {
+            'user_id': self.user_id,
+            'name': self.name,
+            'email': self.email
+        }
+
+# Initialize MicroWeb application with debug mode and Wi-Fi access point configuration
+app = MicroWeb(debug=True, ap={"ssid": "MyESP32", "password": "mypassword"})
+
+# Define route for the root URL, rendering the index.html template with a welcome message
+@app.route('/')
+def home(req):
+    return app.render_template('index.html', message="Welcome to MicroWeb API!")
+
+# Define API route to return server status and IP address as JSON
+@app.route('/api/status', methods=['GET'])
+def status(req):
+    return app.json_response({"status": "running", "ip": wifi.get_ip()})
+
+# Define API route to get user data using the User model
+@app.route('/api/user/<id>')
+def get_user(req, match):
+    # Extract ID from URL parameter, default to "Anonymous" if not provided
+    id = match.group(1) if match else "Anonymous"
+    # Create a sample user instance (in a real app, this could come from a database)
+    user = User(user_id=id, name=f"User {id}", email=f"user{id}@example.com")
+    return app.json_response(user.to_dict())
+
+# Define API route to greet a user by ID
+@app.route('/greet/<name>')
+def greet(req, match):
+    name = match.group(1) if match else "Anonymous"
+    return {"message": f"Hello, {name}!", "status": "success"}
+
+# Define API route to echo back POST data as JSON
+# @app.route('/api/echo', methods=['POST'])
+# def echo(req):
+#     data = req.form  # Get form data from POST body
+#     return app.json_response({"received": data})
+
+# Define a route that handles both GET and POST requests, returning method-specific JSON responses
+# @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()  # Get JSON data from POST body
+#         return app.json_response({"method": "POST", "received": data})
+
+# Define route for form submission, rendering form.html for GET and result.html for POST
+# @app.route('/submit', methods=['GET', 'POST'])
+# def submit_form(req):
+#     if req.method == 'POST':
+#         return app.render_template('result.html', 
+#                                  data=str(req.form),  # Convert form data to string
+#                                  method="POST")
+#     else:
+#         return app.render_template('form.html')
+
+# Register static file style.css to be served at /style.css
+# app.add_static('/style.css', 'style.css')
+
+# Start the MicroWeb server
+app.run()
+"""
+
+        
+        index_content = """<!DOCTYPE html>
+<html>
+<head>
+    <title>MicroWeb Example</title>
+</head>
+<body>
+    <h1>{% message %}</h1>
+    <p>This is an example MicroWeb application.</p>
+</body>
+</html>
+"""
+        
+        readme_content = """# MicroWeb Example Application
+
+This is a simple MicroWeb application for MicroPython devices (e.g., ESP32). It includes a basic web server with a homepage and a status API endpoint.
+
+## Files
+- `app.py`: The main MicroWeb application script.
+- `static/index.html`: The homepage template.
+
+## Setup and Usage
+
+### Prerequisites
+- A MicroPython-compatible device (e.g., ESP32).
+- The `microweb` package installed (`pip install microweb`).
+- A serial port connection (e.g., COM10).
+
+### Flash MicroPython and MicroWeb
+1. Connect your device to your computer.
+2. Flash MicroPython and MicroWeb to your device:
+   ```bash
+   microweb flash --port COM10
+   ```
+   Replace `COM10` with your device's serial port.
+
+### Run the Application
+1. Upload and run the application:
+   ```bash
+   microweb run app.py --port COM10
+   ```
+2. Connect to the Wi-Fi access point:
+   - **SSID**: MyESP32
+   - **Password**: MyPassword
+3. Open a browser and visit `http://192.168.4.1` to see the homepage.
+
+### Additional Commands
+- Set the app to run on boot:
+  ```bash
+  microweb run app.py --port COM10 --add-boot
+  ```
+- Remove all files from the device:
+  ```bash
+  microweb remove --port COM10 --remove
+  ```
+
+For more details, run:
+```bash
+microweb examples
+```
+"""
+        
+        app_path = os.path.join(path, 'app.py')
+        index_path = os.path.join(path, 'static', 'index.html')
+        readme_path = os.path.join(path, 'README.md')
+        
+        with open(app_path, 'w', encoding='utf-8') as f:
+            f.write(app_content)
+        with open(index_path, 'w', encoding='utf-8') as f:
+            f.write(index_content)
+        with open(readme_path, 'w', encoding='utf-8') as f:
+            f.write(readme_content)
+        
+        print_colored(f"Example app created at {path}/", color='green')
+        print_colored(f"  - {app_path}", color='cyan')
+        print_colored(f"  - {index_path}", color='cyan')
+        print_colored(f"  - {readme_path}", color='cyan')
+        print_colored(f"Run with: microweb run {app_path} --port COM10", color='yellow')
+    except Exception as e:
+        print_colored(f"Error creating example app: {e}", color='red')
+
+
+@cli.command()
+@click.option('--port', default=None, help='Serial port, e.g., COM10')
+def ls(port):
+    """List files on the MicroPython device's filesystem."""
+    if not port:
+        ports = [p.device for p in serial.tools.list_ports.comports()]
+        port = ports[0] if ports else None
+    if not port:
+        print_colored("No device found. Specify --port, e.g., --port COM10.", color='red')
+        return
+    try:
+        print_colored(f"Listing files on device at {port}...", color='blue')
+        remote_files = get_remote_file_info(port)
+        if not remote_files:
+            print_colored("No files found or error accessing filesystem.", color='yellow')
+            return
+        print_colored(f"Found {len(remote_files)} files on device:", color='green')
+        for filename, size in sorted(remote_files.items()):
+            print_colored(f"  📄 {filename}: {size} bytes", color='cyan')
+    except Exception as e:
+        print_colored(f"Error listing files: {e}", color='red')
+
+
+
 @cli.command()
 def examples():
-            """Show example commands for using microweb CLI."""
-            print_colored("Example commands for microweb CLI:", color='blue', style='bold')
-            print_colored("\n1. Flash MicroPython and MicroWeb to ESP32:", color='cyan')
-            print_colored("   microweb flash --port COM10", color='green')
-            print_colored("\n2. Upload and run your app.py on ESP32:", color='cyan')
-            print_colored("   microweb run app.py --port COM10", color='green')
-            print_colored("\n3. Check static/template files without uploading:", color='cyan')
-            print_colored("   microweb run app.py --check-only", color='green')
-            print_colored("\n4. Remove all files from ESP32 (DANGEROUS):", color='cyan')
-            print_colored("   microweb remove --port COM10 --remove", color='green')
-            print_colored("\n5. Upload and set app to run on boot:", color='cyan')
-            print_colored("   microweb run app.py --port COM10 --add-boot", color='green')
-            print_colored("\n6. Remove boot.py from ESP32:", color='cyan')
-            print_colored("   microweb run app.py --port COM10 --remove-boot", color='green')
-            print_colored("\nReplace COM10 with your actual ESP32 serial port.", color='yellow')
+    """Show example commands for using microweb CLI."""
+    print_colored("Example commands for microweb CLI:", color='blue', style='bold')
+    print_colored("\n1. Create an example MicroWeb app:", color='cyan')
+    print_colored("   microweb create --path example_app", color='green')
+    print_colored("\n2. Flash MicroPython and MicroWeb to ESP32:", color='cyan')
+    print_colored("   microweb flash --port COM10", color='green')
+    print_colored("\n3. Upload and run your app.py on ESP32:", color='cyan')
+    print_colored("   microweb run app.py --port COM10", color='green')
+    print_colored("\n4. Check static/template files without uploading:", color='cyan')
+    print_colored("   microweb run app.py --check-only", color='green')
+    print_colored("\n5. List files on the ESP32 filesystem:", color='cyan')
+    print_colored("   microweb ls --port COM10", color='green')
+    print_colored("\n6. Remove all files from ESP32 (DANGEROUS):", color='cyan')
+    print_colored("   microweb remove --port COM10 --remove", color='green')
+    print_colored("\n7. Upload and set app to run on boot:", color='cyan')
+    print_colored("   microweb run app.py --port COM10 --add-boot", color='green')
+    print_colored("\n8. Remove boot.py from ESP32:", color='cyan')
+    print_colored("   microweb run app.py --port COM10 --remove-boot", color='green')
+    print_colored("\nReplace COM10 with your actual ESP32 serial port.", color='yellow')
+
 
 
 if __name__ == '__main__':

{microweb-0.1.3.dist-info → microweb-0.1.4.dist-info}/METADATA

@@ -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

{microweb-0.1.3.dist-info → microweb-0.1.4.dist-info}/RECORD

@@ -1,5 +1,5 @@
 microweb/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-microweb/cli.py,sha256=MoFSGG1AXvza4pwFxhoT9R65-9Jo7VtMslXN993kfv4,27919
+microweb/cli.py,sha256=Btvegc_SJ76rLkSvItuiWLySRDrNy2b0gdUrg2a-zKo,34338
 microweb/microweb.py,sha256=WlDV1Fk5M4EsvmmkWKVLWaoZh6Vgl9G0qORFsQEQ3iM,12799
 microweb/uploader.py,sha256=4aTFBMwIIKzONuvXla70ch7yT1pJ8XDmInYBPfVqcok,3164
 microweb/wifi.py,sha256=S2gOOmTKp2G1uUHxOH0DHQ_k7QSERKHDCm89qv-WlKs,904
@@ -7,9 +7,9 @@ microweb/firmware/ESP32_GENERIC-20250415-v1.25.0.bin,sha256=HrGohHPjKqak1F3Btbat
 microweb/firmware/ESP8266_GENERIC-20250415-v1.25.0.bin,sha256=DcEkzHgtDl-BCwap6UbgKhirHjbWepSgd8PonauaVcY,636820
 microweb/firmware/boot.py,sha256=1522jvxAjGk-y7X4mzMilB4pMQ6KrAgosDXRAMtac8k,22
 microweb/firmware/main.py,sha256=g_rg-1qpQEzvQoSnhXairx_v7xHNuGDJVrmbdziKt1A,10
-microweb-0.1.3.dist-info/licenses/LICENSE,sha256=7tSPQeJFv8168MWaFKTWEqYRvM9Lh5xsBh-US0mxUF0,1070
-microweb-0.1.3.dist-info/METADATA,sha256=EsCNvIOp8eJ2c6gM_9lw1dTKaLlP5teu09Eo54bgnQ8,13725
-microweb-0.1.3.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-microweb-0.1.3.dist-info/entry_points.txt,sha256=yBGjIy-e3mx-HHkmkGNLBcSDEALB327du5KuauZHmg4,46
-microweb-0.1.3.dist-info/top_level.txt,sha256=CkRcDTo-nv4JTieAZPKFC-EGKYYQmKNq5C8zU2k5zRM,9
-microweb-0.1.3.dist-info/RECORD,,
+microweb-0.1.4.dist-info/licenses/LICENSE,sha256=7tSPQeJFv8168MWaFKTWEqYRvM9Lh5xsBh-US0mxUF0,1070
+microweb-0.1.4.dist-info/METADATA,sha256=wHRZhYMs8_sAMmNzz3ewkEpcm8gSqcvibAmSvVGPJDc,25314
+microweb-0.1.4.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+microweb-0.1.4.dist-info/entry_points.txt,sha256=yBGjIy-e3mx-HHkmkGNLBcSDEALB327du5KuauZHmg4,46
+microweb-0.1.4.dist-info/top_level.txt,sha256=CkRcDTo-nv4JTieAZPKFC-EGKYYQmKNq5C8zU2k5zRM,9
+microweb-0.1.4.dist-info/RECORD,,