first commit

README.md

@@ -0,0 +1,72 @@
+# Bambu Web Helper
+
+Multi-user web application for Bambu Cloud monitoring with Docker, Postgres,
+user management, and a separate private MQTT broker configuration for every user.
+
+## Features
+
+- Web interface on port `3923`
+- Postgres database through `docker compose`
+- Login, self-service password changes, and admin password resets
+- Admin-managed per-user printer limits, initially `1`
+- Per-printer Bambu Cloud token storage
+- Live printer status through Bambu Cloud MQTT
+- Per-user MQTT broker with optional authentication, TLS, and certificate-error override
+- Per-user Bambu push and MQTT sync intervals
+
+## Start with Docker
+
+1. Ensure Docker Desktop is running.
+2. Run `docker compose up --build -d`.
+3. Open `http://localhost:3923`.
+
+The initial admin is set in `.env`:
+
+- Username: `bambumin`
+- Password: `ChangeMe123!`
+
+## Defaults
+
+The `.env` file supplies defaults for newly created users:
+
+- `DEFAULT_USER_PRINTER_LIMIT=1`
+- `DEFAULT_USER_PUSH_INTERVAL_MS=600000`
+- `DEFAULT_USER_SYNC_INTERVAL_MS=30000`
+- `BRIDGE_REFRESH_INTERVAL_MS=30000`
+
+## Private MQTT
+
+After login, every user configures their own MQTT broker in the web interface.
+Enter only the hostname or IP address, such as `mqtt.example.net`; enter the port
+separately. Enabling TLS uses `mqtts`. Enabling the certificate-error option sets
+the MQTT client's `rejectUnauthorized` option to `false`.
+
+Each printer publishes retained payloads to the configured user broker:
+
+- `{baseTopic}/{serial}/availability`
+- `{baseTopic}/{serial}/state`
+- `{baseTopic}/{serial}/raw`
+- `{baseTopic}/{serial}/{custom-suffix}` for configured individual scalar values
+
+In the printer tab, users can map selected fields from `raw` or the normalized
+`state` to their own topic suffix. Examples include `print.nozzle_temper` and
+`nozzleTemp`. Scalar values are published directly as text, number, or boolean,
+so subscribers do not need to parse the JSON status payload.
+
+The push interval sends Bambu's `pushall` request. The MQTT sync interval republishes
+the last known state; new live updates are always published immediately.
+
+## Bambu Cloud
+
+The integration follows the connection pattern used by
+[Keralots/BambuHelper](https://github.com/Keralots/BambuHelper):
+
+- `us.mqtt.bambulab.com` for `US` and `EU`, `cn.mqtt.bambulab.com` for `CN`
+- TLS on port `8883`
+- Username `u_{uid}` and the access token as password
+- Status topic `device/{SERIAL}/report`
+- Request topic `device/{SERIAL}/request`
+
+The application requests complete status snapshots with `pushall`. A printer owner
+can additionally switch the chamber light and pause, resume, or stop an active print
+from the printer page. Stopping always requires a confirmation in the web interface.