集成步骤

本文档详细介绍如何将 OMI 玩具车控制功能集成到您的应用中。

前置条件

1. 已创建 OMI 应用，获得 appId 和 appSecret
2. 已绑定玩具车设备到您的应用
3. 了解基本的 HTTP API 调用

集成流程

步骤 1：获取访问 Token

首先需要获取访问 Token，用于后续所有 API 调用的身份认证。

Token 有效期

Token 有效期为 3 小时，过期后需要重新获取。

API 调用示例：

async function getAccessToken(appId, appSecret) {
  const response = await fetch('http://182.254.182.254:9090/app/token', {
    method: 'GET',
    headers: {
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      appId: appId,
      appSecret: appSecret
    })
  });
  
  const data = await response.json();
  if (data.status === 200) {
    return data.data.token;
  } else {
    throw new Error(data.desc || '获取Token失败');
  }
}

步骤 2：查询设备列表（可选）

在发起控制前，可以先查询设备列表，查看设备状态。

API 调用示例：

async function getDeviceList(token, page = 1, pageSize = 10) {
  const response = await fetch(
    `http://182.254.182.254:9090/device/openList?page=${page}&pageSize=${pageSize}`,
    {
      method: 'GET',
      headers: {
        'token': token
      }
    }
  );
  
  const data = await response.json();
  if (data.status === 200) {
    return data.data;
  } else {
    throw new Error(data.desc || '获取设备列表失败');
  }
}

关键字段：

• status: 设备状态（在线/离线）
• useStatus: 使用状态（空闲/使用中）

设备独占

如果设备正在被其他人控制（useStatus 为"使用中"），您需要等待当前会话结束才能控制该设备。

步骤 3：获取控制地址

通过玩具车的 SN（序列号）获取控制面板地址。

API 调用示例：

async function getControlUrl(deviceSn, token, duration = 1800) {
  const response = await fetch(
    `http://182.254.182.254:9090/device/ctrlUrl?deviceSn=${deviceSn}&duration=${duration}`,
    {
      method: 'GET',
      headers: {
        'token': token
      }
    }
  );
  
  const data = await response.json();
  if (data.status === 200) {
    return data.data.url;
  } else {
    // 特殊处理：设备正在控制中
    if (data.desc && data.desc.includes('设备正在控制中')) {
      throw new Error('设备正在被其他人控制，请稍后再试');
    }
    throw new Error(data.desc || '获取控制地址失败');
  }
}

参数说明：

• deviceSn: 玩具车序列号（必填）
• duration: 控制时长，单位秒，默认 1800 秒（30 分钟）

步骤 4：嵌入控制面板

将获取到的控制面板 URL 嵌入到您的应用中。

示例代码：

function embedControlPanel(controlUrl, containerId) {
  const container = document.getElementById(containerId);
  if (!container) {
    throw new Error(`容器元素 ${containerId} 不存在`);
  }

  container.innerHTML = `
    <iframe 
      src="${controlUrl}" 
      width="100%" 
      height="600px" 
      frameborder="0"
      allow="camera; microphone; fullscreen"
      title="玩具车控制面板">
    </iframe>
  `;
}

完整集成示例

查看 代码示例 了解完整的集成示例代码。

独占控制机制

系统采用独占控制机制，确保同一时间只有一个用户可以控制同一辆玩具车。

设备占用时机

设备在以下情况下会变为"占用"状态：

• 调用 /device/ctrlUrl 接口成功创建控制会话后，设备立即进入 USING 状态
• 用户打开控制面板 URL，开始远程控制操作
• 在控制会话期间内（默认 30 分钟，由 duration 参数指定），设备持续被占用

设备释放时机

设备在以下场景下会被释放，恢复"空闲"状态：

• 控制时长到期：达到预设的控制时长后（默认 30 分钟），系统自动释放设备
• 用户主动结束：用户在控制面板中主动关闭或结束控制会话
• 浏览器关闭：用户关闭控制面板所在的浏览器窗口/标签页，会话结束
• 网络断开：用户网络异常断开超过一定时间，系统检测后释放设备

建议

在发起控制前，先调用 /device/openList 接口查询设备的 useStatus 状态，选择空闲设备进行控制。