环境感知系统 API 文档

简介

欢迎使用循星科技环境感知系统 (ESS) API。本 API 允许开发者通过标准 RESTful 接口与我们的环境感知硬件进行交互，获取实时传感器数据，并接收关键事件通知。

我们致力于提供一个安全、可靠且易于集成的接口，帮助您将环境智能融入您的应用程序和服务中。所有核心数据处理均在本地设备完成，API 调用仅限于授权访问和控制。

快速开始

要开始使用 API，您需要：

获取 API 密钥和设备 ID (请参考认证部分)。
熟悉 REST API 的基本概念。
选择您偏好的编程语言和 HTTP 客户端库。

(更多详细步骤和设置指南即将推出...)

认证

所有 API 请求都需要通过 API 密钥进行认证。请将您的密钥包含在请求的 `Authorization` 头中。

Authorization: Bearer YOUR_API_KEY

请妥善保管您的 API 密钥，不要在客户端代码中公开。(认证流程细节待补充...)

API 参考

获取传感器列表

GET /v1/sensors

返回当前设备连接的所有可用传感器及其元数据。

响应示例 (JSON):

{
  "sensors": [
    {
      "id": "temp-livingroom",
      "type": "temperature",
      "unit": "Celsius",
      "location": "客厅",
      "status": "active"
    },
    {
      "id": "humidity-bedroom",
      "type": "humidity",
      "unit": "%",
      "location": "卧室",
      "status": "active"
    }
    // ... more sensors
  ]
}

读取实时传感器数据

GET /v1/sensors/{sensor_id}/reading

获取指定传感器的最新读数。

路径参数:

sensor_id (string, required): 要查询的传感器 ID。

响应示例 (JSON):

{
  "sensor_id": "temp-livingroom",
  "value": 23.5,
  "unit": "Celsius",
  "timestamp": "2025-10-26T10:30:00Z"
}

订阅事件 (通过 WebSocket - 示例)

WS /v1/events/subscribe

通过 WebSocket 连接实时接收传感器事件（例如，阈值触发、状态变化）。

(连接协议和消息格式待详细说明...)

SDK

为了简化集成，我们提供了适用于常用语言的 SDK。(SDK 列表和下载链接即将推出...)

Python SDK
JavaScript SDK
Java SDK (规划中)

错误处理

API 使用标准的 HTTP 状态码来指示请求的成功或失败。

200 OK: 请求成功。
400 Bad Request: 请求参数无效。
401 Unauthorized: 无效的 API 密钥或未授权。
404 Not Found: 请求的资源（如传感器 ID）不存在。
500 Internal Server Error: 服务器内部错误。

失败的请求通常会在响应体中包含一个 JSON 对象，提供更详细的错误信息。(错误响应格式待定义...)

示例代码

以下是使用 Python 获取传感器列表的简单示例：

import requests

API_KEY = "YOUR_API_KEY"
BASE_URL = "https://ess.sidebystar.local/api" # 假设的本地设备地址

headers = {
    "Authorization": f"Bearer {API_KEY}"
}

try:
    response = requests.get(f"{BASE_URL}/v1/sensors", headers=headers, verify=False) # verify=False for local dev only
    response.raise_for_status() # Raise HTTPError for bad responses (4xx or 5xx)
    sensors = response.json()
    print("可用传感器:")
    for sensor in sensors.get('sensors', []):
        print(f"- {sensor['id']} ({sensor['type']} @ {sensor.get('location', 'N/A')})")
except requests.exceptions.RequestException as e:
    print(f"请求错误: {e}")
except Exception as e:
    print(f"发生错误: {e}")

(更多语言的示例即将添加...)