DevicePlay Voice
Project: Pet Feeder | page_id: 1754
Device Alarm Audio Upload API Document (Device-Side Integration)
1. API Information
- API name: Alarm audio file upload
- Real path: /api/sys/uploadAlarmFile
- Method: POST
- Content-Type: multipart/form-data
- Caller: internal server-side forwarding
2. Intended Audience
This document is intended for device-side or firmware-side integration personnel.
You need to pay attention to the final HTTP request format received by the device, the query parameters, the file field, and the response conventions.
3. Function Description
The device receives the alarm audio file forwarded by the server and executes the business logic according to the command in the query parameters.
4. Final Request Address Format
The server assembles the device address based on deviceId and automatically appends the signature parameters.
The final request format is as follows:
[http://{deviceHost}/api/sys/uploadAlarmFile?from=media&name=feeder_speaker_audio.wav&command=alarmAudioFile](http://{deviceHost}/api/sys/uploadAlarmFile?from=media&name=feeder_speaker_audio.wav&command=alarmAudioFile)'/media/feeder_speaker_audio.wav'{times}&t={ts}&token=cloud_{sign}
5. Query Parameters
| Field | Type | Required | Description |
|---|---|---|---|
| from | string | Yes | Currently fixed to media |
| name | string | Yes | Currently fixed to feeder_speaker_audio.wav |
| command | string | Yes | Currently assembled dynamically by the server according to times |
| t | string | Yes | Current timestamp, generated by the server |
| token | string | Yes | Device signature, generated by the server, in the format cloud_{sign} |
6. multipart Request Body
6.1 File Field
| Field | Type | Required | Description |
|---|---|---|---|
| file | file | Yes | Audio file stream |
6.2 Current Implementation Details
- The file form field name is fixed to file.
- When the server forwards, the file name is fixed to feeder_speaker_audio.wav.
- The current command generation format is:
alarmAudioFile'/media/feeder_speaker_audio.wav'{times}
where times is the playback count parameter received by the server, with a default value of 1.
7. Response Conventions
The server passes through the HTTP status code and response body returned by the device, so the device should return the business result directly.
Success response example:
{
"code": 0,
"msg": "ok"
}
Recommended failure response example:
{
"code": 1001,
"msg": "upload failed"
}
8. Signature and Calling Notes
- The device side does not need to care about the upper-layer user JWT.
- The device side only needs to verify the business query parameters and signature parameters appended by the server.
- t and token are generated by the server.
- The current server timeout is 200 seconds.
9. Code Location
- Device-side call wrapper: internal/clouds/cloud_request.go
- Server-side entry: internal/handler/device_handler.go