# 本地闹钟

消息类型 名称 必须实现
response set_alarm
delete_alarm
request state_sync

# 选择闹钟实现方式

TIP

  • iFLYOS 系统提供两种闹钟能力,云端闹钟和本地闹钟只能二选一。为了降低设备开发成本,iFLYOS 建议你使用云端闹钟。
  • 为了更好的用用户体验,我们约定,无论实现设备闹钟还是本地闹钟,在闹钟响起后,设备均应该在语音唤醒或按键操作之后停止闹钟。
  • 纯软件项目无需实现闹钟能力(无论云端闹钟还是设备闹钟)。

# 云端闹钟

在请求时,context中不包含alarm对象,则代表设备使用云端闹钟。用户设置闹钟后,云端会记住用户的闹钟列表,当闹钟时间到时,你的设备会收到如下iflyos_response

# 闹钟时间到

{
  "iflyos_responses": [
    ...,
    {
      "header": {
        "name": "audio_player.audio_out"
      },
      "payload": {
        "type": "RING",
        "url": "https://music.iflyos.cn/tts/sadf.mp3?token=xxxxxxxx",
        "resource_id": "e52e7xxxxxxxxxxxe52e7"
      }
    }
  ]
}

收到该iflyos_response后,设备使用 RING 通道的播放器播放闹钟铃音即可。

# 更新云端闹钟列表

在闹钟列表发生变更后(可能是因为闹钟响铃、用户通过语音或关联APP增删查改闹钟),云端会下发以下指令。

{
  "iflyos_responses": [
   ...,
    {
      "header": {
        "name": "system.update_cloud_alarm_list"
      },
      "payload": {
      }
    }
  ]
}

在收到指令后,若你的设备本地需要显示闹钟列表,我们建议你立即调用GET /alerts,更新闹钟列表中的数据。

# 本地闹钟

在请求时,context中包含alarm对象,则代表设备使用本地闹钟。如果你想在设备本地保存闹钟列表,需要实现alarmiflyos_response

在此之前你需要考虑以下几个问题:

  • 实现本地闹钟需要设备本地做闹钟列表持久化保存,不能因为设备重启等原因造成设备闹钟列表丢失。(这样会造成设备开发的复杂度提升)
  • 实现本地闹钟需要保证设备本地时间正确。iFLYOS 在接入大量厂商时发现很多芯片的时间钟不稳定,我们建议使用 system.ping 来保证你的设备系统时间是准确的。(这样会造成设备开发的复杂度提升)
  • 实现本地闹钟需要在设备本地对设备闹钟进行一定的容错处理。(这样会造成设备开发的复杂度提升)

如果选择了客户端闹钟,请按照本篇的内容,完成本地闹钟的实现和处理。

注意

闹钟的设置、修改、删除和响铃,都必须使用状态同步(system.state_sync)来告知云端;

# context

"iflyos_context": {
  ...
  "alarm": {
    "version": "1.0",
    "local": [
      {
        "alarm_id": "xxxxx",
        "timestamp": 1558598737
      }
    ],
    "active": {
      "alarm_id": "xxxxx"
    }
  },
  ...
}
参数 类型 说明 必填
version String 模块版本,现在是1.1
local List 设备本地闹钟列表,如果没有,请传输空数组
local.alarm_id String 设备闹钟的唯一标识
local.timestamp Long unix时间戳
active Object 正在活动的闹钟
active.alarm_id String 设备闹钟的唯一标识

版本说明

版本 说明 更新日期
1.0 基础实现 2019-07-01

# response

# 设置闹钟

在设备发起recognize请求或状态同步之后,可能会得到一个闹钟response。在收到这个iflyos_response之后,你需要根据信息在设备本地记录和设置闹钟。

回复示例

{
  "iflyos_responses": [
    ...,
    {
      "header": {
        "name": "alarm.set_alarm"
      },
      "payload": {
        "alarm_id": "xxxxx",
        "timestamp": 1558598737,
        "url": "https://www.iflyos.cn/example....2.m4a"
      }
    }
  ]
}
参数 类型 说明 必有
alarm_id String 闹钟ID
timestamp Long 响铃时间的 unix 时间戳
url String 铃声地址

# 删除闹钟

在设备发起recognize请求或状态同步之后,可能会得到一个闹钟response。在收到这个iflyos_response之后,你需要根据信息在设备本地记录中删除对应alarm_id的闹钟。

回复示例

{
  "iflyos_responses": [
    ...,
    {
      "header": {
        "name": "alarm.delete_alarm"
      },
      "payload": {
        "alarm_id": "xxxxx",
      }
    }
  ]
}
参数 类型 说明 必有
alarm_id String 闹钟ID

# request

# 状态同步

当本地闹钟时间到时,你需要在闹钟开始响和结束响的时候发送request至 iFLYOS 云端

请求示例

{ 
  "iflyos_header": {...}, 
  "iflyos_context": {...}, 
  "iflyos_request": { 
    "header": { 
      "name": "alarm.state_sync", 
      "request_id": "xxxxxxxx" 
    }, 
    "payload": { 
      "type": "STARTED", 
      "alarm_id": "xxxxx" 
    } 
  } 
}
参数 类型 说明 必填
iflyos_header Object 构建的通用 iflyos_header
iflyos_context Object 构建的通用 iflyos_context
type String 状态类型,取值:
- STARTED:alarm开始响铃
- STOPPED:alarm响铃停止,无论是自然响铃完成还是用户操作(唤醒或按键)停止了闹钟,均发送该请求。
alarm_id String 该状态对应的闹钟ID