DeviceUnified Report

Project: Pet Feeder | page_id: 1720

Device Report Interface Documentation

1. Interface Information

• Interface name: Unified Device Report
• Path: /api/device/report
• Method: POST
• Content-Type: application/json
• Authentication method: device signature authentication
• Handler function: deviceH.Report

2. Function Description

The device reports different types of data through the same interface, using action to distinguish the business type.

Supported actions:

• status: report device status
• feedlog: report feeding records
• alarm: report alarm information

3. Authentication Rules

When reportSecret is configured on the server side, the token and timestamp must be verified.

• token calculation rule:

md5(reportSecret + ":" + deviceId + ":" + timestamp + ":" + action)

• timestamp unit: seconds
• timestamp validity period: reportTokenTTL (default 300 seconds)
• Failure response:
• 401 + code=401 + msg=Device authentication has expired
• 401 + code=401 + msg=Device authentication failed

4. Common Request Body

5. data Structure for Each action

5.1 action = status

Example:

{
  "deviceId": "dev_001",
  "action": "status",
  "timestamp": 1752297600,
  "token": "md5signature",
  "data": "{\"batteryLevel\":90,\"isCharging\":false,\"foodLevel\":80,\"wifiName\":\"Home-2.4G\",\"wifiSignal\":-58,\"firmwareVersion\":\"1.0.2\"}"
}

5.2 action = feedlog

Example:

{
  "deviceId": "dev_001",
  "action": "feedlog",
  "timestamp": 1752297600,
  "token": "md5signature",
  "data": "{\"amount\":20,\"planId\":1,\"feedTime\":1752297600,\"userId\":10001,\"userName\":\"Tom\"}"
}

5.3 action = alarm

Example:

{
  "deviceId": "dev_001",
  "action": "alarm",
  "timestamp": 1752297600,
  "token": "md5signature",
  "data": "{\"alarmType\":\"low_battery\",\"message\":\"Battery level below 10%\"}"
}

6. Response Description

Unified response structure:

6.1 Success Response

• HTTP status code: 200
• Response example:

{
  "code": 200,
  "msg": "Report successful",
  "data": null
}

6.2 Failure Responses (Common)

• Parameter error or business processing failure

{
  "code": 400,
  "msg": "Parameter error",
  "data": null
}

• Unknown action

{
  "code": 400,
  "msg": "Unknown action: xxx",
  "data": null
}

• Authentication expired or failed (HTTP 401)

{
  "code": 401,
  "msg": "Device authentication failed",
  "data": null
}

7. Notes

• Code location:
• Route registration: cmd/main.go
• Handler function: internal/handler/device_handler.go
• The data field is agreed by the interface to be a JSON string, and the server continues to parse it in the corresponding action branch.
• If data is an empty string or missing, parsing will not report an error, but the business layer may fail because the fields are empty.