Microcontroller and Backend Communication
This document outlines how microcontroller devices (e.g., ESP32) communicate with the backend, specifying the data types used, message formats, API addresses, and more. It is designed to assist develo
1. WebSocket Usage
Communication between microcontroller devices and the backend is done using the WebSocket protocol. WebSocket enables real-time, persistent communication between the microcontroller and the backend. The following sections detail the message formats and workflows to facilitate this communication.
2. Data Types and Message Formats
Data transmission generally falls into two main categories:
Authentication & Connection
Device Control & Data Transfer
2.1 Authentication & Connection
When the microcontroller connects to the backend, it first sends an authentication message containing a token. If the token is valid, the connection is established successfully.
Message Format:
auth:<token>Example Send:
auth:abc123tokenBackend Response:
Successfully connected2.2 Device Connection & Data Sending
The backend can send commands to the microcontroller to perform actions on a device, such as turning it on or setting a specific value. Messages sent to the microcontroller typically follow the format outlined below:
Message Format:
device_id: The unique ID of the device (Long Integer).
control_type: The type of control for the device (e.g., SWITCH, SLIDER, RGB_PICKER, etc. — defined as an enum).
value: The data to be sent to the device, which can vary in type (boolean, string, int, etc.).
Example Sending (Turning a device ON):
Example Sending (Turning a device OFF):
2.3 Device Status Reporting
The microcontroller can also send status updates back to the backend, providing information such as device status or sensor values.
Message Format:
device_id: The unique ID of the device.
bind_value: A value representing the device’s state. For example, a device's on/off status (0 or 1).
Example Send:
3. WebSocket URL & Endpoints
The WebSocket endpoint in the backend specifies the address the microcontroller will use to connect. The URL is typically structured as follows:
WebSocket Address (URL):
<backend_server_address>: The IP address or domain name where the backend server is hosted.
/ws/esp32: The WebSocket endpoint.
Example URL:
4. Data Formats
Data transmission is typically done using BinaryMessage or StringMessage types. These messages are sent over the WebSocket connection.
4.1 BinaryMessage:
Binary format is used for transmitting data between the backend and microcontroller, as it is more efficient for large or real-time data.
Example:
4.2 StringMessage:
If the message is text-based, it may be transmitted in string format. JSON or similar text formats can be used.
Example:
5. Error Handling & Message Formats
The backend checks for invalid message formats or incorrect data inputs and sends appropriate error responses. For example:
Invalid Authentication:
Invalid Message Format:
6. Microcontroller Device Response
After processing the data, the microcontroller can respond to the backend with a status update, such as the state of the device or a sensor value.
Response Message Format:
device_id: The ID of the device.
status: The status of the device or a response (e.g., "opened", "closed", "value:23").
Example Send:
7. WebSocket Connection and Connection Closure
When the WebSocket connection is established, a success message is sent. When the connection is closed, the backend is notified of this event.
Connection Established Message:
Connection Closed Message:
Conclusion
The data types and message formats outlined above enable seamless communication between microcontroller devices and the backend. A developer can use these data types to control devices, receive sensor data, and maintain an efficient real-time communication flow via WebSocket.
This guide provides the essential information needed for developing a microcontroller-backend communication system, focusing on sending and receiving data between devices and the backend server.
Documentation and Support
For full documentation, including additional usage examples and configuration details, refer to the GitHub repository.
Feel free to check out the repository for updates, bug fixes, and community contributions.
Last updated