Web API¶

The device hosts a simple web server that allows you to check status and switch modes.

Insecure Protocol

HTTP is an inherently insecure protocol that transmits data, including credentials, in plain text. Only use this feature on a trusted, private network.

Web Server Credentials¶

The web server can be protected by basic authentication. You can set the username and password in the WiFiManager setup page.

Connect with curl:
- Use the -u or --user flag to provide credentials.
- If you omit the password, curl will prompt for it securely.

Tip

To make the web server unauthenticated, make the user and password blank in the WiFiManager setup page.

Error Handling¶

This API uses standard HTTP status codes to indicate the success or failure of a request. Common status codes include:

200 OK: The request was successful.
400 Bad Request: The request was malformed or invalid (e.g., incorrect parameters, invalid data format).
401 Unauthorized: Authentication failed. Ensure you are providing valid credentials.
403 Forbidden: You are authenticated but do not have permission to perform the requested action.
404 Not Found: The requested resource or endpoint does not exist.
500 Internal Server Error: An unexpected error occurred on the server.

Specific endpoints may return additional details in the JSON response body to further clarify the error.

Web Server Commands¶

Tip

Run the test-api.sh script to automate API tests to verify the device's web API functionality.

GET /: Returns the current mode, display status, and SD card information.

UnauthenticatedAuthenticated

curl -X GET http://<DEVICE_IP>/

curl -u <USERNAME>:<PASSWORD> -X GET http://<DEVICE_IP>/

Example Response

{
  "mode": "USB MSC",
  "display": {
    "status": "on",
    "orientation": 1
  },
  "sd_card": {
    "total_size": 9876543210,
    "used_size": 1234567890,
    "free_size": 8641975320,
    "file_count": 42
  },
  "mqtt": {
    "enabled": true,
    "state": 0,
    "connected": true
  },
  "led": {
    "color": "green",
    "state": "on",
    "brightness": 13
  }
}

MQTT Icon

On the device's display, a small circle icon indicates the MQTT connection status:

Green: The MQTT client is connected to the broker.
Red: The MQTT client is disconnected from the broker.
Missing: The MQTT client is disabled.

MQTT State

State	Description	State	Description
`-4`	MQTT_CONNECTION_TIMEOUT	`1`	MQTT_CONNECT_BAD_PROTOCOL
`-3`	MQTT_CONNECTION_LOST	`2`	MQTT_CONNECT_BAD_CLIENT_ID
`-2`	MQTT_CONNECT_FAILED	`3`	MQTT_CONNECT_UNAVAILABLE
`-1`	MQTT_DISCONNECTED	`4`	MQTT_CONNECT_BAD_CREDENTIALS
`0`	MQTT_CONNECTED	`5`	MQTT_CONNECT_UNAUTHORIZED

GET /mode/msc: Returns the current mode (USB Mass Storage or FTP).

UnauthenticatedAuthenticated

curl -X GET http://<DEVICE_IP>/mode/msc

curl -u <USERNAME>:<PASSWORD> -X GET http://<DEVICE_IP>/mode/msc

Example Response

{"status":"success","mode":"USB MSC"}

POST /mode/msc: Switches the device to USB Mass Storage (MSC) mode.

UnauthenticatedAuthenticated

curl -X POST http://<DEVICE_IP>/mode/msc

curl -u <USERNAME>:<PASSWORD> -X POST http://<DEVICE_IP>/mode/msc

Example Responses

Success (200 OK)No Change (200 OK)Error (500 Internal Server Error)

{"status":"success","message":"Switched to MSC mode."}

{"status":"no_change","message":"Already in MSC mode."}

{"status":"error","message":"Failed to switch to MSC mode."}

GET /mode/ftp: Returns the current mode (USB Mass Storage or FTP).

UnauthenticatedAuthenticated

curl -X GET http://<DEVICE_IP>/mode/ftp

curl -u <USERNAME>:<PASSWORD> -X GET http://<DEVICE_IP>/mode/ftp

Example Response

{"status":"success","mode":"Application (FTP Server)"}

POST /mode/ftp: Switches the device to FTP mode.

UnauthenticatedAuthenticated

curl -X POST http://<DEVICE_IP>/mode/ftp

curl -u <USERNAME>:<PASSWORD> -X POST http://<DEVICE_IP>/mode/ftp

Example Responses

Success (200 OK)No Change (200 OK)Error (500 Internal Server Error)

{"status":"success","message":"Switched to Application (FTP) mode."}

{"status":"no_change","message":"Already in Application (FTP) mode."}

{"status":"error","message":"Failed to re-initialize SD card."}

POST /device/restart: Restarts the device.

UnauthenticatedAuthenticated

curl -X POST http://<DEVICE_IP>/device/restart

curl -u <USERNAME>:<PASSWORD> -X POST http://<DEVICE_IP>/device/restart

Example Response:

Success (200 OK)

{"status":"success","message":"Restarting device..."}

GET /display/status: Returns the current display status.

UnauthenticatedAuthenticated

curl -X GET http://<DEVICE_IP>/display/status

curl -u <USERNAME>:<PASSWORD> -X GET http://<DEVICE_IP>/display/status

Example Response

{"status":"success","display_status":"on"}

POST /display/toggle: Toggles the display on and off.

UnauthenticatedAuthenticated

curl -X POST http://<DEVICE_IP>/display/toggle

curl -u <USERNAME>:<PASSWORD> -X POST http://<DEVICE_IP>/display/toggle

Example Responses

Success (200 OK)Success (200 OK)

{"status":"success","message":"Display toggled on."}

{"status":"success","message":"Display toggled off."}

POST /display/on: Turns the display on.

UnauthenticatedAuthenticated

curl -X POST http://<DEVICE_IP>/display/on

curl -u <USERNAME>:<PASSWORD> -X POST http://<DEVICE_IP>/display/on

Example Response

Success (200 OK)

{"status":"success","message":"Display turned on."}

POST /display/off: Turns the display off.

UnauthenticatedAuthenticated

curl -X POST http://<DEVICE_IP>/display/off

curl -u <USERNAME>:<PASSWORD> -X POST http://<DEVICE_IP>/display/off

Example Response

Success (200 OK)

{"status":"success","message":"Display turned off."}

POST /wifi/reset: Resets the Wi-Fi settings and restarts the device.

UnauthenticatedAuthenticated

curl -X POST http://<DEVICE_IP>/wifi/reset

curl -u <USERNAME>:<PASSWORD> -X POST http://<DEVICE_IP>/wifi/reset

Example Response

Success (200 OK)

{"status":"success","message":"Resetting Wi-Fi and restarting..."}

Device Unreachable After Reset

After resetting the Wi-Fi settings, the device will restart and will no longer be connected to your Wi-Fi network. It will become unreachable at its previous IP address. You must reconnect to its Access Point (AP) to configure the new Wi-Fi credentials. See the Modes of Operation section for details on connecting to the AP.

GET /mqtt/status: Returns the current MQTT client status.

UnauthenticatedAuthenticated

curl -X GET http://<DEVICE_IP>/mqtt/status

curl -u <USERNAME>:<PASSWORD> -X GET http://<DEVICE_IP>/mqtt/status

Example Response

{
  "status": "success",
  "mqtt_enabled": true,
  "mqtt_connected": true,
  "mqtt_state": 0
}

POST /mqtt/enable: Enables the MQTT client.

UnauthenticatedAuthenticated

curl -X POST http://<DEVICE_IP>/mqtt/enable

curl -u <USERNAME>:<PASSWORD> -X POST http://<DEVICE_IP>/mqtt/enable

Example Response

Success (200 OK)

{"status":"success","message":"MQTT enabled."}

POST /mqtt/disable: Disables the MQTT client.

UnauthenticatedAuthenticated

curl -X POST http://<DEVICE_IP>/mqtt/disable

curl -u <USERNAME>:<PASSWORD> -X POST http://<DEVICE_IP>/mqtt/disable

Example Response

Success (200 OK)

{"status":"success","message":"MQTT disabled."}

POST /mqtt/toggle: Toggles the MQTT client on and off.

UnauthenticatedAuthenticated

curl -X POST http://<DEVICE_IP>/mqtt/toggle

curl -u <USERNAME>:<PASSWORD> -X POST http://<DEVICE_IP>/mqtt/toggle

Example Responses

Success (200 OK)Success (200 OK)

{"status":"success","message":"MQTT enabled."}

{"status":"success","message":"MQTT disabled."}

GET /led/status: Returns the current LED color and state.

UnauthenticatedAuthenticated

curl -X GET http://<DEVICE_IP>/led/status

curl -u <USERNAME>:<PASSWORD> -X GET http://<DEVICE_IP>/led/status

Example Response

{
  "status": "success",
  "color": "green",
  "state": "on",
  "brightness": 13
}

POST /led/on: Turns the LED on.

UnauthenticatedAuthenticated

curl -X POST http://<DEVICE_IP>/led/on

curl -u <USERNAME>:<PASSWORD> -X POST http://<DEVICE_IP>/led/on

Example Response

{"status":"success","message":"LED turned on."}

POST /led/off: Turns the LED off.

UnauthenticatedAuthenticated

curl -X POST http://<DEVICE_IP>/led/off

curl -u <USERNAME>:<PASSWORD> -X POST http://<DEVICE_IP>/led/off

Example Response

Success (200 OK)

{"status":"success","message":"LED turned off."}

POST /led/toggle: Toggles the LED on and off.

UnauthenticatedAuthenticated

curl -X POST http://<DEVICE_IP>/led/toggle

curl -u <USERNAME>:<PASSWORD> -X POST http://<DEVICE_IP>/led/toggle

Example Responses

Success (200 OK)Success (200 OK)

{"status":"success","message":"LED toggled on."}

{"status":"success","message":"LED toggled off."}

GET /led/brightness: Returns the current LED brightness.

UnauthenticatedAuthenticated

curl -X GET http://<DEVICE_IP>/led/brightness

curl -u <USERNAME>:<PASSWORD> -X GET http://<DEVICE_IP>/led/brightness

Example Response

{"status":"success","brightness":128}

POST /led/brightness: Sets the LED brightness. The body of the request should be a plain text integer between 0 and 255.

UnauthenticatedAuthenticated

curl -X POST -H 'Content-Type: text/plain' -d '128' http://<DEVICE_IP>/led/brightness

curl -u <USERNAME>:<PASSWORD> -X POST -H 'Content-Type: text/plain' -d '128' http://<DEVICE_IP>/led/brightness

Example Responses

Success (200 OK)Error (400 Bad Request)

{"status":"success","message":"LED brightness set to 128."}

{"status":"error","message":"Invalid brightness value. Body must be a plain text integer between 0 and 255."}

POST /upload: Uploads a file to the device's SD card using multipart/form-data.

Cannot Upload in MSC Mode

File uploads are only supported when the device is in FTP Server Mode. Attempts to upload in USB Mass Storage (MSC) mode will result in an error.

UnauthenticatedAuthenticated

curl -X POST -F "file=@/path/to/your/image.jpg;filename=image.jpg" http://<DEVICE_IP>/upload

curl -u <USERNAME>:<PASSWORD> -X POST -F "file=@/path/to/your/image.jpg;filename=image.jpg" http://<DEVICE_IP>/upload

Example Responses

Success (200 OK)Error (400 Bad Request)Error (500 Internal Server Error)

{"status":"success","message":"File uploaded successfully."}

{"status":"error","message":"Cannot upload in MSC mode."}

{"status":"error","message":"Failed to open file for writing."}

Web API¶

Web Server Credentials¶

Error Handling¶

Web Server Commands¶

References¶