Functional Specifications — MQTT Antena
Functional Specifications — MQTT Antena
This document describes the current, observable behavior of the application in this repository. It is a baseline, not a commitment that every current behavior is desirable or complete. Items marked ToDo are unresolved policy or improvement questions, not implemented requirements.
Purpose and Scope
MQTT Antena is a self-hosted, browser-based MQTT client intended as a development and analysis tool for MQTT-based applications and IoT systems. It lets users save MQTT broker connection details, connect to brokers, observe live messages for a topic, and publish messages.
The application in this repository is a Flask web application that can run as a standalone Docker container and is also used in a Home Assistant add-on context. The README links two separate companion projects:
These links identify related projects only. Their behavior and integration details are outside the scope of this specification.
The current application includes user registration and session-based login, per-user broker configuration, broker connection management, MQTT topic subscription and live message viewing, and MQTT message publishing. It does not provide persisted message history, persistent connection status, or in-app password recovery.
Functional Capabilities
Accounts and access
- A visitor can register with a username, password, and password confirmation. A successful registration creates the account, starts a logged-in session, and redirects to broker management.
- A username already present in the database is rejected with a user-visible error. A password/confirmation mismatch is also rejected with a user-visible error.
- A registered user can log in with the matching username and password and log out.
- A user can reset an account password through the
flask reset-password <USERNAME> <PASSWORD>command. There is no in-app password-reset flow. - Pages and operations marked as login-protected redirect unauthenticated requests to the login page. The
/howtoguide is publicly accessible.
Broker management
- An authenticated user can add, view, edit, connect to, disconnect from, and delete their broker configurations.
- A broker configuration contains a display name, host/IP, port, and optional MQTT username and password. The add form defaults the port to
1883; if no name is supplied, the host/IP is used as the name. - Broker records are listed and operated on in the context of their owning user. A user does not see another user’s broker records in their broker list.
- The broker list displays runtime status as connected, disconnected, or error when an error is available. A connection attempt starts asynchronously; the initial request does not itself confirm that the broker accepted the connection.
- Editing a broker updates the stored connection details and removes the current runtime client so the changed configuration can be used on a subsequent connection attempt.
- Deleting a broker removes its runtime client if present and deletes its stored configuration.
Topic subscriptions and live message viewing
- An authenticated user can select one of their connected brokers and start listening on a topic.
- An empty topic is treated as the MQTT wildcard topic
#. - Starting a new topic subscription on a broker removes the client’s prior subscriptions before subscribing to the new topic. The UI presents the current subscription for each connected broker.
- Incoming MQTT messages are sent to the user’s active Socket.IO sessions and displayed in the browser. Displayed message information includes broker name, topic, payload, and a server-generated time string.
- The browser’s Clear Messages action clears the current page’s displayed messages. It does not alter the MQTT broker or persist/delete any server-side history.
Message publishing
- An authenticated user can publish a message through one of their connected brokers.
- A publish operation supplies a topic and message payload, supports QoS
0,1, or2, and supports the MQTT retain flag. - The publish page offers connected brokers. A request made when the selected broker client is not connected produces a user-visible “Broker not connected” error.
User interface
- The application uses server-rendered pages for login, registration, broker management, subscription, publishing, and a how-to guide.
- The common layout includes a light/dark theme toggle. The selected theme is stored in browser
localStorage; the default is light. - The subscription page uses Socket.IO for live updates. Its current status caption says “SSE Status”; this is a UI label mismatch, not the transport in use.
Business Rules
- Each broker record belongs to one user, and broker list operations are scoped to the authenticated user.
- The username is unique in the database. Passwords are stored as password hashes rather than plaintext.
- Broker name is optional in the add/edit UI; the host/IP is used as the name when the name is empty.
- The add-broker form defaults to port
1883. The application stores the submitted broker port as an integer. - A broker’s connection state and active MQTT client are runtime-only. Users must reconnect after an application restart.
- A new subscription replaces the subscriptions previously tracked by that broker’s runtime client. An empty topic maps to
#. - MQTT messages are streamed to the browser and are not stored as application history. Refreshing the page clears the displayed messages; restarting the application also does not restore messages.
- Broker configurations and user accounts are persistent application data. The selected storage location is described in the technical specification.
- Published message QoS is selected from
0,1, and2; retain is enabled only when the form checkbox is selected.
User and System Interactions
Register and sign in
- The visitor opens the registration page and supplies a username, password, and confirmation.
- The application checks for matching passwords and an existing username.
- If valid, the application stores a password hash, establishes a session, and redirects to the broker page. Otherwise, it displays an error and leaves the visitor unauthenticated.
- Returning users submit their credentials on the login page. Successful login redirects to broker management; invalid credentials display an error.
- Logging out removes the user’s session identifier and redirects to login.
Configure and connect a broker
- The authenticated user adds a broker with a host/IP, optional name, port, and optional credentials.
- The broker appears in that user’s broker list with its current runtime status.
- Selecting Connect starts an asynchronous MQTT connection. The list later reflects a successful connection or a connection error when reported by the MQTT client.
- The user can disconnect, edit, or delete a broker. Editing or deleting removes the current runtime MQTT client.
Subscribe and receive messages
- The user opens the subscription page and chooses a connected broker.
- The user submits a topic. An empty value means
#; otherwise, the submitted topic is used. - The broker client replaces its prior subscription and subscribes to the requested topic.
- When a message arrives from the broker, the application emits a
mqtt_messageSocket.IO event to the room for that user. The browser appends the message to its live display. - The user can stop listening, which clears the client’s tracked subscriptions, or clear only the current browser display.
Publish a message
- The user opens the publish page, chooses an available connected broker, and submits a topic, payload, QoS, and optional retain flag.
- If a connected client is available and the broker belongs to the user, the application invokes the MQTT client’s publish operation and displays a success flash message.
- If the broker is disconnected or no client is available, the application displays an error instead of publishing.
Validation and Error Handling
Implemented user-visible cases
- Registration reports password mismatch and duplicate username errors.
- Login reports invalid credentials without distinguishing an unknown username from a wrong password.
- Protected pages redirect a request without a logged-in session to login.
- Broker connection failures reported by the MQTT callback are reflected as an error status and error text in the broker list.
- The subscription form reports when no broker is selected. Attempting to publish without an available connected broker displays an error.
- Requests for a broker that is not owned by the current user are not returned as that user’s broker in the broker list; broker edit and delete lookup is scoped by the session user.
Current limitations and ToDos
- Several values are converted directly to integers or passed to MQTT operations. Malformed direct POST requests (for example, invalid port, broker ID, or QoS values) do not have comprehensive application-level validation and may result in errors rather than a friendly form message.
- The browser forms use required-field hints, but server-side validation is not comprehensive. No password length/complexity policy is implemented in the registration handler.
- If a subscription request refers to a broker without an active client, the current handler does not display a specific error.
- The publish route reports that a publish operation was invoked; it does not check the MQTT publish result or wait for broker acknowledgement before showing success.
- ToDo: confirm account-creation policy, including whether public self-registration is intended for every deployment and whether a first-user/admin setup policy exists.
- ToDo: review input-validation and error-message behavior if stronger guarantees are required.
Acceptance Criteria
These criteria describe checks for the current baseline; they are not claims that a new automated test has been added for every item.
- Given a new username and matching password confirmation, registration creates an account, establishes a session, and redirects to broker management.
- Given an existing username or mismatched password confirmation, registration does not create a logged-in account and provides the corresponding error message.
- Given valid credentials, login establishes an authenticated session; given invalid credentials, login displays a generic invalid-credentials message.
- Given a user with broker records, the broker page shows that user’s records and does not show records owned by another user.
- Given an empty broker name on creation, the resulting broker name defaults to the submitted host/IP; the add form’s default port is
1883. - Given a broker connect request, the application starts an asynchronous connection attempt and reflects later connected/error status from the MQTT client rather than treating initiation as proof of successful connection.
- Given a connected broker and an empty subscription topic, the MQTT client subscribes to
#; given a non-empty topic, it subscribes to that topic after removing its previously tracked subscription. - Given an MQTT message on a subscribed topic, an authenticated user’s Socket.IO session receives a
mqtt_messageevent containing broker ID/name, timestamp, topic, and payload, and the subscription page displays it. - Given a publish request to a connected broker owned by the user, the MQTT client receives the topic, payload, selected QoS, and retain flag from the request.
- Given a publish request when the selected broker client is disconnected or absent, the application reports “Broker not connected” and does not invoke publish.
- Given an application restart, user and broker records remain in the configured SQLite database, while runtime connection state and active subscriptions are not restored.
- Given a page refresh or use of Clear Messages, the page’s message display is cleared; no application message-history record is available to restore it.