获取控制地址

接口说明

获取指定玩具车的远程控制面板地址。返回的 URL 包含临时访问 Token，可直接在浏览器中打开进行玩具车控制。

请求

GET /device/ctrlUrl

请求参数

名称	位置	类型	必选	说明
deviceSn	query	string	是	玩具车序列号，唯一标识玩具车
duration	query	integer	否	控制时长，默认30分钟（1800秒），单位秒
token	header	string	是	授权token，通过 /app/token 接口获取

请求示例

curl -X GET "http://182.254.182.254:9090/device/ctrlUrl?deviceSn=TOY_CAR_001&duration=1800" \
  -H "token: <your_access_token>"

const response = await fetch(
  'http://182.254.182.254:9090/device/ctrlUrl?deviceSn=TOY_CAR_001&duration=1800',
  {
    method: 'GET',
    headers: {
      'token': '<your_access_token>'
    }
  }
);

const data = await response.json();

响应

成功响应

状态码：200

{
  "status": 200,
  "desc": "string",
  "time": 0,
  "data": {
    "url": "string"
  }
}

响应字段

名称	类型	必选	说明
status	integer	是	响应状态：200-成功，401-需要重新授权，404-接口不存在，500-错误信息
desc	string	是	响应描述
time	integer	是	响应时间戳
data	object	是	响应数据
url	string	是	控制面板地址

业务场景

• 远程玩具车体验：用户通过手机应用远程控制玩具车，体验驾驶乐趣
• 亲子互动：家长远程控制玩具车与孩子互动，增进亲子关系
• 教育培训：通过玩具车进行驾驶教学和交通安全教育
• 娱乐竞技：组织远程玩具车比赛和竞技活动

安全机制

• 需要应用 Token 认证
• 控制会话有时长限制（默认 30 分钟）
• 玩具车必须已绑定到当前应用
• 独占控制：同一时间只能有一个控制会话

错误处理

设备正在控制中

当设备正在被其他人控制时，接口会返回以下错误响应：

{
  "status": 500,
  "desc": "设备正在控制中！",
  "time": 1640995200,
  "data": null
}

独占控制

系统通过 DeviceSession 状态管理控制会话，确保同一时间只有一个控制会话处于 USING 状态。如果检测到设备正在被控制，接口立即返回"设备正在控制中！"错误，拒绝新的控制请求。

独占控制机制说明

• 互斥访问：系统通过 DeviceSession 状态管理控制会话，确保同一时间只有一个控制会话处于 USING 状态
• 状态检测：在创建新的控制会话前，系统会检测设备是否存在 USING 状态的控制会话
• 拒绝策略：如果检测到设备正在被控制，接口立即返回"设备正在控制中！"错误，拒绝新的控制请求
• 应用场景：防止多个用户同时控制同一辆玩具车，确保控制命令的唯一性和可控性

控制面板URL参数

获取到控制地址后，可以在URL中添加额外的查询参数来配置控制面板行为：

playerId 参数

通过 playerId 参数可以设置玩家ID，用于标识当前控制会话的玩家身份。

使用方式：

在返回的控制面板URL后添加 playerId 参数：

https://dev-ctrl.omiok.cn/?token=xxx&sn=xxx&playerId=xxx

参数说明：

参数名	类型	必选	说明
playerId	string	否	玩家ID，用于标识当前控制会话的玩家身份

示例：

// 获取控制地址
const response = await fetch(
  'http://182.254.182.254:9090/device/ctrlUrl?deviceSn=TOY_CAR_001',
  {
    method: 'GET',
    headers: {
      'token': '<your_access_token>'
    }
  }
);

const data = await response.json();
if (data.status === 200) {
  const baseUrl = data.data.url;
  const playerId = 'user_12345'; // 您的玩家ID
  
  // 在URL中添加playerId参数
  const controlUrl = `${baseUrl}&playerId=${playerId}`;
  
  // 打开控制面板
  window.open(controlUrl, '_blank');
}

console 参数

通过 console 参数可以控制是否显示调试控制台，用于开发和调试场景。

使用方式：

在返回的控制面板URL后添加 console=1 参数来打开调试控制台：

https://dev-ctrl.omiok.cn/?token=xxx&sn=xxx&console=1

参数说明：

参数名	类型	必选	说明
console	integer	否	调试控制台开关，设置为 1 时打开调试控制台，默认不显示

使用场景：

• 开发调试：在开发阶段需要查看控制面板的调试信息
• 问题排查：当控制面板出现问题时，可以通过调试控制台查看详细日志
• 性能监控：查看控制面板的运行状态和性能指标

示例：

// 获取控制地址
const response = await fetch(
  'http://182.254.182.254:9090/device/ctrlUrl?deviceSn=TOY_CAR_001',
  {
    method: 'GET',
    headers: {
      'token': '<your_access_token>'
    }
  }
);

const data = await response.json();
if (data.status === 200) {
  const baseUrl = data.data.url;
  const isDebug = true; // 是否开启调试模式
  
  // 在URL中添加console参数
  const controlUrl = isDebug ? `${baseUrl}&console=1` : baseUrl;
  
  // 打开控制面板
  window.open(controlUrl, '_blank');
}

调试控制台

调试控制台仅在URL中包含 console=1 参数时才会显示。生产环境建议移除该参数，避免向最终用户暴露调试信息。

App 接入说明

控制面板支持在 App 中通过 WebView 方式接入，特别是 uniapp 框架的应用。

uniapp WebView 返回方式

控制面板支持通过事件通知的方式与 App 进行交互。当用户点击控制面板左上角的房子图标时，会向 App 发送一个返回事件，开发者可以监听该事件并自行处理返回逻辑。

功能说明：

• 返回按钮：控制面板左上角显示房子图标（返回按钮）
• 事件通知：点击房子图标时，控制面板会向 App 发送一个事件
• 事件类型：事件类型为 back
• 自定义处理：开发者需要监听该事件，并根据业务需求自行处理返回逻辑

事件格式：

控制面板会通过 WebView 的消息机制向 App 发送事件，事件格式如下：

{
  "type": "back"
}

使用方式：

1. 在 uniapp 中使用 WebView 组件加载控制面板地址
2. 监听 WebView 的 @message 事件
3. 判断事件类型是否为 back
4. 根据业务需求处理返回逻辑（如调用 uni.navigateBack() 返回上一页）

示例代码：

<template>
  <view>
    <web-view :src="controlUrl" @message="handleMessage"></web-view>
  </view>
</template>

<script>
export default {
  data() {
    return {
      controlUrl: ''
    }
  },
  async onLoad() {
    // 获取控制地址
    const response = await fetch(
      'http://182.254.182.254:9090/device/ctrlUrl?deviceSn=TOY_CAR_001',
      {
        method: 'GET',
        headers: {
          'token': '<your_access_token>'
        }
      }
    );
    
    const data = await response.json();
    if (data.status === 200) {
      this.controlUrl = data.data.url;
    }
  },
  methods: {
    handleMessage(event) {
      // 处理 WebView 发送的消息
      const message = event.detail.data[0];
      
      // 判断事件类型
      if (message && message.type === 'back') {
        // 处理返回逻辑
        // 例如：返回上一页
        uni.navigateBack({
          delta: 1
        });
        
        // 或者执行其他自定义逻辑
        // this.handleBack();
      }
    }
  }
}
</script>

事件处理

控制面板通过事件机制与 App 通信，开发者需要监听 @message 事件并判断事件类型。当收到 type 为 back 的事件时，可以根据业务需求自行处理返回逻辑，例如调用 uni.navigateBack() 返回上一页，或执行其他自定义操作。

使用建议

1. 在调用此接口前，先通过 /device/openList 接口查询设备的 useStatus 状态
2. 选择 useStatus 为"IDLE"的设备进行控制
3. 根据业务需求设置合适的 duration 参数
4. 在应用中嵌入返回的 URL（使用 iframe 或直接跳转）
5. 如需标识玩家身份，可在控制面板URL中添加 playerId 参数
6. 开发调试时，可通过添加 console=1 参数打开调试控制台查看详细信息

注意事项

• Token 有效期：3 小时
• 默认控制时长：30 分钟（1800 秒）
• 设备独占：同一设备不能同时被多个用户控制
• 控制会话到期后会自动释放设备