Skip to content

Add documentation and guide about supported features; unify terminology #23

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
szeka9 merged 2 commits into from
Jun 21, 2026
Merged

Add documentation and guide about supported features; unify terminology #23

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
9648dc9
Add documentation and guide about supported features
szeka9 Jun 21, 2026
5eaab5a
Unify terminology; use "route" instead of "endpoint"
szeka9 Jun 21, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
173 changes: 173 additions & 0 deletions assets/www/configuration.html
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,173 @@
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>PyRobusta Home</title>
<link rel="stylesheet" href="styles.css">
</head>
<body>

<h1 id="introduction">Configuration</h1>

<a href="index.html">← Back</a>

<p class="description">
This page documents PyRobusta configuration options,
configuration deployment using <code>mpremote</code>,
and runtime access to configuration values through the
configuration API.
</p>

<hr>

<h2>Table of Contents</h2>

<a href="#introduction">Configuration</a><br>
├── <a href="#deployment">Configuration Format &amp; Deployment</a><br>
├── <a href="#parameters">Parameter Description</a><br>
└── <a href="#api">Configuration API</a><br>

<hr>


<h2 id="deployment">Configuration Format &amp; Deployment</h2>

<p class="description">
Configuration overrides can be provided through <code>pyrobusta.env</code>, using standard <code>.env</code> syntax.
<code>pyrobusta.env</code> must be stored in the server root. Inline comments are supported using <code>#</code>.
</p>

<textarea readonly="true">
# /pyrobusta.env - Example configuration

socket_max_con=2 # allow two simultaneous socket connections
http_multipart=False # turn off multipart parser to lower heap usage
http_mem_cap=0.05 # limit heap usage of stream buffers to 5% of the total heap
tls=False # turn off TLS
</textarea>

<p class="description">Perform a soft reset and upload <code>pyrobusta.env</code> using mpremote.</p>
<textarea readonly="true">
$ mpremote a0 soft-reset
$ mpremote a0 cp pyrobusta.env :/pyrobusta.env
</textarea>


<h2 id="parameters">Parameter Description</h2>

<table border="1" cellpadding="6" cellspacing="0">
<thead>
<tr>
<th>Name</th>
<th>Description</th>
<th>Default</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>wifi_ssid</code></td>
<td>Name of the Wi-Fi network. When empty, Wi-Fi is not initialized by the built-in <code>wifi.py</code> module.</td>
<td>None</td>
</tr>
<tr>
<td><code>wifi_password</code></td>
<td>Password of the Wi-Fi network. When empty, Wi-Fi is not initialized by the built-in <code>wifi.py</code> module.</td>
<td>None</td>
</tr>
<tr>
<td><code>http_port</code></td>
<td>Port number for HTTP.</td>
<td>80</td>
</tr>
<tr>
<td><code>https_port</code></td>
<td>Port number for HTTPS.</td>
<td>443</td>
</tr>
<tr>
<td><code>http_multipart</code></td>
<td>Enables or disables multipart request and response processing. Enabling multipart support increases memory usage.</td>
<td>False</td>
</tr>
<tr>
<td><code>http_mem_cap</code></td>
<td>
Fraction of available heap memory reserved for stream buffers. Valid range: (0, 1].
</td>
<td>0.1</td>
</tr>
<tr>
<td><code>http_served_paths</code></td>
<td>
Space-separated list of filesystem paths that may be served over HTTP.
</td>
<td><code>/www /lib/pyrobusta</code></td>
</tr>
<tr>
<td><code>http_files_api</code></td>
<td>
Enables or disables the file management API endpoint (<code>/files</code>), allowing upload, download, and listing of files.
</td>
<td>False</td>
</tr>
<tr>
<td><code>socket_max_con</code></td>
<td>Maximum number of simultaneous socket connections.</td>
<td>2</td>
</tr>
<tr>
<td><code>tls</code></td>
<td>
Enables or disables TLS. When enabled, <code>cert.der</code> and <code>key.der</code> must be installed at the server root.
</td>
<td>False</td>
</tr>
<tr>
<td><code>log_level</code></td>
<td>Logging level. Can be one of: <code>warning</code>, <code>info</code>, <code>debug</code>.</td>
<td>info</td>
</tr>
</tbody>
</table>

<h2 id="api">Configuration API</h2>

<p class="description">
Configuration values can be accessed through the
<code>pyrobusta.utils.config</code> module.
Values are loaded from <code>pyrobusta.env</code> during server initialization.
Configuration values can be retrieved using
<code>get_config()</code> together with one of the
predefined <code>CONF_*</code> constants.
</p>

<p class="description">
After initialization, configuration values are retrieved from an internal cache.
The cached values are normalized to their expected runtime types to avoid repeated
parsing of environment strings.
</p>

<p class="description">
Configuration values are treated as immutable during runtime.
Changes are applied only when the configuration cache is reloaded.
The configuration cache can be reloaded by calling
<code>read_config()</code>, which re-reads <code>pyrobusta.env</code>
and rebuilds the internal normalized cache.
</p>

<textarea readonly="true">
from pyrobusta.utils.config import get_config, CONF_TLS

@HttpEngine.route("/tls", "GET")
def tls_status(http_ctx, _):
enabled = get_config(CONF_TLS)
return "text/plain", f"TLS enabled: {enabled}"
</textarea>

<div class="footer">
<hr>
<address>PyRobusta v0.7.0 Web Server</address>
</div>
</body>
</html>
207 changes: 207 additions & 0 deletions assets/www/file_server.html
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,207 @@
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>PyRobusta Home</title>
<link rel="stylesheet" href="styles.css">
</head>
<body>

<h1 id="static_content">File Server API</h1>

<a href="index.html">← Back</a>

<p class="description">This API provides file management capabilities, allowing clients to upload,
retrieve, and manage files through various HTTP methods.
<code>http_files_api</code> must be set to <code>True</code> in
<code>pyrobusta.env</code> to enable this API.
</p>

<hr>

<h2>Table of Contents</h2>

<a href="#static_content">Static Content</a><br>
├── <a href="#summary">Summary</a><br>
├── <a href="#file_retrieval">File Retrieval</a><br>
├── <a href="#file_upload">File Upload / Overwrite</a><br>
├── <a href="#bulk_upload">Bulk File Upload</a><br>
└── <a href="#file_delete">File Delete</a><br>

<hr>

<h2 id="summary">Summary</h2>

<table class="description">
<thead>
<tr>
<th>Method</th>
<th>Path</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>GET</code></td>
<td><code>/files/{path}</code></td>
<td>Lists or retrieves metadata about files.</td>
</tr>
<tr>
<td><code>PUT</code></td>
<td><code>/files/{file path}</code></td>
<td>Uploads or overwrites a file at the specified path.</td>
</tr>
<tr>
<td><code>POST</code></td>
<td><code>/files</code></td>
<td>Uploads multiple files in multipart/form-data.</td>
</tr>
<tr>
<td><code>DELETE</code></td>
<td><code>/files/{file path}</code></td>
<td>Deletes a file at the specified path.</td>
</tr>
</tbody>
</table>

<section>
<h2 id="file_retrieval">File Retrieval / Listing</h2>
<p class="description"><strong>Endpoint:</strong> <code>GET /files/{path}</code></p>

<p class="description">
This method allows general file system interaction, enabling operations
such as listing directory contents, retrieving metadata, and downloading
files.
</p>

<ul>
<li><strong>Method:</strong> <code>GET</code></li>
<li><strong>Path:</strong> <code>/files/{path}</code></li>
<li><strong>Success Response:</strong> <code>200 OK</code></li>
</ul>

<h3>Example Request</h3>

<textarea readonly="true">
$ curl 192.168.1.100/files/www
[
{"path": "/www/examples.html", "created": "90", "size": "4507"},
{"path": "/www/index.html", "created": "91", "size": "1198"}
]
</textarea>
</section>

<section>
<h2 id="file_upload">File Upload / Overwrite</h2>
<p class="description"><strong>Endpoint:</strong> <code>PUT /files/{file path}</code></p>

<p class="description">
This method uploads a file or overwrites an existing file at a specific
path. The upload path is restricted to
<code>/www/user_data</code>.
</p>

<ul>
<li><strong>Method:</strong> <code>PUT</code></li>
<li><strong>Path:</strong> <code>/files/{file path}</code></li>
<li><strong>Body:</strong> Raw file content (binary or text).</li>
<li><strong>Success Response:</strong> <code>201 Created</code></li>
<li>
<strong>Notes:</strong>
<code>transfer-encoding: chunked</code> is supported.
</li>
</ul>

<h3>Example Request</h3>

<textarea readonly="true">
$ curl -X PUT --data 'This is a test.' \
http://192.168.1.100/files/www/user_data/test.txt
OK

$ curl 192.168.1.100/files/www/user_data/test.txt
This is a test.
</textarea>
</section>

<section>
<h2 id="bulk_upload">Bulk File Upload</h2>
<p class="description"><strong>Endpoint:</strong> <code>POST /files</code></p>

<p class="description">
This method handles general file uploads, designed for uploading multiple
files with per-file chunking supported. Only
<code>multipart/form-data</code> is accepted.
</p>

<p class="description">
Uploads are restricted to <code>/www/user_data</code>. The
<code>Content-Disposition</code> header only needs to specify the file
name; the upload directory is prepended automatically.
</p>

<p class="description">
<code>http_multipart</code> must be set to <code>True</code> in the
configuration to use this method.
</p>

<ul>
<li><strong>Method:</strong> <code>POST</code></li>
<li><strong>Path:</strong> <code>/files</code></li>
<li>
<strong>Body:</strong>
File content encapsulated in multipart/form-data.
</li>
<li><strong>Success Response:</strong> <code>201 Created</code></li>
</ul>

<h3>Example Request</h3>

<textarea readonly="true">
$ echo "File 1 content" > /tmp/upload-1.txt
$ echo "File 2 content" > /tmp/upload-2.txt

$ curl -X POST \
--form file1='@/tmp/upload-1.txt' \
--form file2='@/tmp/upload-2.txt' \
http://192.168.1.100/files

$ curl 192.168.1.100/files/www/user_data
[
{"path": "/www/user_data/upload-1.txt", "created": "418", "size": "15"},
{"path": "/www/user_data/upload-2.txt", "created": "418", "size": "15"}
]
</textarea>
</section>

<section>
<h2 id="file_delete">File Delete</h2>
<p class="description"><strong>Endpoint:</strong> <code>DELETE /files/{file path}</code></p>

<p class="description">
This method deletes a file at a specific path. The path is restricted to
<code>/www/user_data</code>.
</p>

<ul>
<li><strong>Method:</strong> <code>DELETE</code></li>
<li><strong>Path:</strong> <code>/files/{file path}</code></li>
<li><strong>Success Response:</strong> <code>204 No Content</code></li>
</ul>

<h3>Example Request</h3>

<textarea readonly="true">
$ curl -X DELETE \
192.168.1.100/files/www/user_data/test.txt
</textarea>
</section>


<div class="footer">
<hr>
<address>PyRobusta v0.7.0 Web Server</address>
</div>
</body>
</html>
Loading
Loading