闹钟

摘要

本接口定义设置、管理以及取消定时器/闹钟的指令和事件。本文档覆盖以下两个主题：

1. 闹钟模块状态
2. 闹钟指令与事件

端的职责

1. 之前在设备端设置成功的定时器/闹钟，在网络连接断开之后也能够正常触发；设备端需要能够保存和维护多个定时器/闹钟
2. 用NTP（Network Time Protocol）来管理设备端本地的时钟
3. 在断电/重启时，能够保存并正确执行之前设置成功的闹钟/定时器

闹钟模块状态

闹钟模块有以下几种状态：

• IDLE
  • 在之前设定的闹钟响起之前，闹钟模块应该处于IDLE状态；当一个闹钟被关闭或者闹铃结束之后，闹钟模块应该回到IDLE状态
• FOREGROUND ALERT和BACKGROUND ALERT
  • 假定已经设定了设备端闹钟，当闹钟开始响起并且上报了AlertStarted事件到服务端时，闹钟模块应该从IDLE状态进入到FOREGROUND ALERT或者BACKGROUND ALERT状态
  • 在闹钟正在响铃时：如果Alerts Channel在前景（意味着Dialog Channel在非活跃状态），则闹钟模块应该在FOREGROUND ALERT状态；如果Alerts Channel在背景（意味着Dialog Channel也在活跃状态），则闹钟模块应该在BACKGROUND ALERT状态

SetAlert指令

设备端在收到SetAlert指令时，应该在本地设置一个闹钟，到设定的时间能够自动触发闹铃。在用户通过语音请求设置闹钟时，或者通过Companion App重新启用先前设置的闹钟时，都有可能使服务端下发该指令。

消息样例

"directive": {
    "header": {
        "namespace": "ai.dueros.device_interface.alerts",
        "name": "SetAlert",
        "messageId": "{{STRING}}",
        "dialogRequestId": "{{STRING}}"
    },
    "payload": {
        "token": "{{STRING}}",
        "type": "{{STRING}}",
        "scheduledTime": "{{STRING}}"
    }
}

Payload参数说明

• token
  • 本闹钟的唯一token
• type
  • 闹钟类型
  • 取值
    • "TIMER": 定时器
    • "ALARM": 闹钟
• scheduledTime
  • 触发时间，ISO 8601格式

SetAlertSucceeded事件

设备端收到SetAlert指令，闹钟设置成功之后，上报该事件给服务端。

消息样例

"event": {
    "header": {
        "namespace": "ai.dueros.device_interface.alerts",
        "name": "SetAlertSucceeded",
        "messageId": "{{STRING}}"
    },
    "payload": {
        "token": "{{STRING}}"
    }
}

Payload参数说明

• token
  • 所设置的闹钟的token，对应SetAlert指令中的token

SetAlertFailed事件

设备端收到SetAlert指令，但设置闹钟失败时，上报该事件给服务端。

消息样例

"event": {
    "header": {
        "namespace": "ai.dueros.device_interface.alerts",
        "name": "SetAlertFailed",
        "messageId": "{{STRING}}"
    },
    "payload": {
        "token": "{{STRING}}"
    }
}

Payload参数说明

• token
  • 设置失败的闹钟的token，对应SetAlert指令中的token

DeleteAlert指令

该指令用于删除一个闹钟，设备端收到指令之后应该从本地删除token对应的闹钟，如果该闹钟正在闹铃当中，则应该先停止闹铃（并上报AlertStopped事件），再删除闹钟。在用户通过语音请求取消/删除一个闹钟，或通过Companion App取消/删除时，服务端都有可能会下发DeleteAlert指令。

消息样例

"directive": {
    "header": {
        "namespace": "ai.dueros.device_interface.alerts",
        "name": "DeleteAlert",
        "messageId": "{{STRING}}",
        "dialogRequestId": "{{STRING}}"
    },
    "payload": {
        "token": "{{STRING}}"
    }
}

Payload参数说明

• token
  • 要删除的闹钟的token

DeleteAlertSucceeded事件

设备端收到DeleteAlert指令，闹钟删除成功之后，上报该事件给服务端。

消息样例

"event": {
    "header": {
        "namespace": "ai.dueros.device_interface.alerts",
        "name": "DeleteAlertSucceeded",
        "messageId": "{{STRING}}"
    },
    "payload": {
        "token": "{{STRING}}"
    }
}

Payload参数说明

• token
  • 所删除的闹钟的token，对应DeleteAlert指令中的token

DeleteAlertFailed事件

设备端收到DeleteAlert指令，但删除闹钟失败时，上报该事件给服务端。

消息样例

"event": {
    "header": {
        "namespace": "ai.dueros.device_interface.alerts",
        "name": "DeleteAlertFailed",
        "messageId": "{{STRING}}"
    },
    "payload": {
        "token": "{{STRING}}"
    }
}

Payload参数说明

• token
  • 删除失败的闹钟的token，对应DeleteAlert指令中的token

AlertStarted事件

到了定点时间，触发了闹钟，闹铃开始响起时上报。

消息样例

"event": {
    "header": {
        "namespace": "ai.dueros.device_interface.alerts",
        "name": "AlertStarted",
        "messageId": "{{STRING}}"
    },
    "payload": {
        "token": "{{STRING}}"
    }
}

Payload参数说明

• token
  • 所触发的闹钟的token

AlertStopped事件

正在闹铃中的闹钟被停止时上报，有以下情况：

• 收到DeleteAlert指令，停止了正在闹铃中的闹钟
• 通过端上按钮或者端上屏幕操作停止了闹铃
• 端在闹钟设定时间点处于断电状态，回到有电状态时已经离设定时间点超过30分钟

消息样例

"event": {
    "header": {
        "namespace": "ai.dueros.device_interface.alerts",
        "name": "AlertStopped",
        "messageId": "{STRING}"
    },
    "payload": {
        "token": "{{STRING}}"
    }
}

Payload参数说明

• token
  • 对应闹钟的token

AlertEnteredForeground事件

闹铃响起时Alert Channel在前景（意味着Dialog Channel在非活跃状态），或者在闹铃播放当中Dialog Channel从活跃状态进入非活跃状态时（意味着Alert Channel从背景变为前景），上报该事件。

消息样例

"event": {
    "header": {
        "namespace": "ai.dueros.device_interface.alerts",
        "name": "AlertEnteredForeground",
        "messageId": "{{STRING}}"
    },
    "payload": {
        "token": "{{STRING}}"
    }
}

Payload参数说明

• token
  • 对应闹钟的token

AlertEnteredBackground事件

闹铃播放当中，用户开始了语音请求，或者服务端下发了Speak指令，Dialog Channel从非活跃状态进入了活跃状态（意味着Alert Channel从前景变味背景），上报该事件。

消息样例

"event": {
    "header": {
        "namespace": "ai.dueros.device_interface.alerts",
        "name": "AlertEnteredBackground",
        "messageId": "{{STRING}}"
    },
    "payload": {
        "token": "{{STRING}}"
    }
}

Payload参数说明

• token
  • 对应闹钟的token

状态上报

消息样例

"clientContext": [
    {
        "header": {
            "namespace": "ai.dueros.device_interface.alerts",
            "name": "AlertsState"
        },
        "payload": {
            "allAlerts": [
                {
                  "token": "{{STRING}}",
                  "type": "{{STRING}}",
                  "scheduledTime": "{{STRING}}"
                },
                ...
            ],
            "activeAlerts": [
                {
                  "token": "{{STRING}}",
                  "type": "{{STRING}}",
                  "scheduledTime": "{{STRING}}"
                },
                ...
            ]
        }
    }
]

Payload参数说明

• allAlerts[]
  • 设备端上设置的所有闹钟列表
• allAlerts[].token
  • 闹钟的token，对应SetAlert指令中的token
• allAlerts[].type
  • 闹钟的类型，TIMER或ALARM
• allAlerts[].scheduledTime
  • 闹钟的触发时间，ISO 8601格式
• activeAlerts[]
  • 设备端上所有活跃的闹钟列表，即正在闹铃中的闹钟列表
• activeAlerts[].token
  • 闹钟的token，对应SetAlert指令中的token
• activeAlerts[].type
  • 闹钟的类型，TIMER或ALARM
• activeAlerts[].scheduledTime
  • 闹钟的触发时间，ISO 8601格式