智能家居 NetworkControl 特征架构
action.devices.traits.NetworkControl
- 此特征属于支持报告网络数据和执行网络特定操作的设备。
设备属性
具有此特征的设备可以在 SYNC
操作中报告以下属性。如需详细了解如何处理 SYNC
intent,请参阅 intent 执行方式。
属性 | 类型 | 说明 |
---|---|---|
supportsEnablingGuestNetwork |
Boolean |
(默认: 如果访客网络可以启用,则设置为 true。 |
supportsDisablingGuestNetwork |
Boolean |
(默认: 如果访客网络可以停用,则设置为 true。 |
supportsGettingGuestNetworkPassword |
Boolean |
(默认: 如果可以通过 |
networkProfiles |
数组 |
指明支持的网络配置文件名称。 |
[item, ...] |
String |
表示一组相关设备的网络配置文件的名称。 |
supportsEnablingNetworkProfile |
Boolean |
(默认: 如果可以启用网络配置文件,则设置为 true。 |
supportsDisablingNetworkProfile |
Boolean |
(默认: 如果可以停用网络配置文件,则设置为 true。 |
supportsNetworkDownloadSpeedTest |
Boolean |
(默认: 如果可以运行下载速度测试,则设置为 true。 |
supportsNetworkUploadSpeedTest |
Boolean |
(默认: 如果可以运行上传速度测试,则设置为 true。 |
示例
支持访客网络、配置文件和速度测试的网络设备。
{ "supportsEnablingGuestNetwork": true, "supportsDisablingGuestNetwork": true, "supportsEnablingNetworkProfile": true, "supportsDisablingNetworkProfile": true, "supportsNetworkDownloadSpeedTest": true, "supportsNetworkUploadSpeedTest": true, "supportsGettingGuestNetworkPassword": true, "networkProfiles": [ "Kids" ] }
设备状态
具有此特征的实体可以在 QUERY
操作中报告以下状态。如需详细了解如何处理 QUERY
intent,请参阅 intent 执行方式。
州 | 类型 | 说明 |
---|---|---|
networkEnabled |
Boolean |
主网络是否已启用。 |
networkSettings |
对象 |
包含主网络的 SSID。 |
ssid |
String |
必填。 网络 SSID。 |
guestNetworkEnabled |
Boolean |
访客网络是否已启用。 |
guestNetworkSettings |
对象 |
包含访客网络的 SSID。 |
ssid |
String |
必填。 网络 SSID。 |
numConnectedDevices |
整数 |
连接到网络的设备数量。 |
networkUsageMB |
编号 |
网络用量(以 MB 为单位)。网络使用量在当前的结算周期内,便于您监控结算周期内的网络用量限额。 |
networkUsageLimitMB |
编号 |
网络用量上限(以 MB 为单位)。网络用量限额在当前结算周期内。 |
networkUsageUnlimited |
Boolean |
网络用量是否不受限制。如果此政策设为 true,系统会忽略设备状态 networkUsageLimitMB。 |
lastNetworkDownloadSpeedTest |
对象 |
包含最近的网络下载速度测试的结果。 |
downloadSpeedMbps |
编号 |
上次网络速度测试的下载速度(以 Mbps 为单位)。 |
unixTimestampSec |
整数 |
上次运行网络下载速度测试时的 Unix 时间戳(自 Unix 纪元起的秒数)。 |
status |
String |
指示上次网络下载速度测试是成功还是失败。 支持的值:
|
lastNetworkUploadSpeedTest |
对象 |
包含最近一次网络上传速度测试的结果。 |
uploadSpeedMbps |
编号 |
上次网络速度测试的上传速度(以 Mbps 为单位)。 |
unixTimestampSec |
整数 |
上次运行网络上传速度测试时的 Unix 时间戳(自 Unix 纪元起的秒数)。 |
status |
String |
指示上次网络上传速度测试是成功还是失败。 支持的值:
|
networkSpeedTestInProgress |
Boolean |
(默认: 是否正在运行速度测试。 |
networkProfilesState |
对象 |
网络配置文件的状态。此顶级对象应包含键值对,其中键是 |
<string> |
对象 |
用于存储单个网络配置文件的状态的对象。 |
enabled |
Boolean |
网络配置文件的当前启用/停用状态。 |
示例
具有活跃网络的设备。
{ "networkEnabled": true, "networkSettings": { "ssid": "home-network-123" }, "guestNetworkSettings": { "ssid": "home-network-123-guest" }, "numConnectedDevices": 4, "networkUsageMB": 100.8 }
具有活跃网络和速度测试结果的设备。
{ "networkEnabled": true, "networkSettings": { "ssid": "home-network-123" }, "guestNetworkSettings": { "ssid": "home-network-123-guest" }, "numConnectedDevices": 4, "networkUsageMB": 100.8, "lastNetworkDownloadSpeedTest": { "downloadSpeedMbps": 159.8, "unixTimestampSec": 1563215576, "status": "SUCCESS" }, "lastNetworkUploadSpeedTest": { "uploadSpeedMbps": 64.1, "unixTimestampSec": 1563215576, "status": "SUCCESS" } }
正在进行活跃网络和正在进行速度测试的设备。
{ "networkEnabled": true, "networkSettings": { "ssid": "home-network-123" }, "guestNetworkSettings": { "ssid": "home-network-123-guest" }, "numConnectedDevices": 4, "networkUsageMB": 100.8, "networkSpeedTestInProgress": true }
已停用“kids”networkProfile 的设备。
{ "networkEnabled": true, "networkSettings": { "ssid": "home-network-123" }, "networkProfilesState": { "parents": { "enabled": true }, "kids": { "enabled": false } } }
设备命令
具有此特征的设备可能会在 EXECUTE
操作中响应以下命令。如需详细了解如何处理 EXECUTE
intent,请参阅 intent 执行方式。
action.devices.commands.EnableDisableGuestNetwork
启用或停用访客网络。必须使用 PIN 码进行第二层用户身份验证。如果其他安全设备已通过以下命令停用,则用户的家居安全可能会受到影响。
此命令需要以下属性:{ "supportsEnablingGuestNetwork": true, "supportsDisablingGuestNetwork": true }
参数
参数 | 类型 | 说明 |
---|---|---|
enable |
Boolean |
必填。 如果启用,则启用访客网络;如果停用,则停用访客网络。 |
示例
开启访客网络。
{ "command": "action.devices.commands.EnableDisableGuestNetwork", "params": { "enable": true } }
action.devices.commands.EnableDisableNetworkProfile
启用或停用网络配置文件。必须使用 PIN 码进行第二层用户身份验证。如果其他安全设备已通过以下命令停用,则用户的家居安全可能会受到影响。
此命令需要以下属性:{ "supportsEnablingNetworkProfile": true, "supportsDisablingNetworkProfile": true }
参数
参数 | 类型 | 说明 |
---|---|---|
profile |
String |
必填。 来自 |
enable |
Boolean |
必填。 设为 true 时启用配置文件,设为 false 时停用配置文件。 |
示例
为孩子关闭互联网。
{ "command": "action.devices.commands.EnableDisableNetworkProfile", "params": { "profile": "Kids", "enable": false } }
相关错误
尝试控制指定的网络配置文件时出错。
支持的值:
networkProfileNotRecognized
action.devices.commands.GetGuestNetworkPassword
获取访客网络密码。必须使用 PIN 码进行第二层用户身份验证。如果其他安全设备已通过以下命令停用,则用户的家居安全可能会受到影响。
此命令需要以下属性:{ "supportsGettingGuestNetworkPassword": true }
参数
参数 | 类型 | 说明 |
---|---|---|
没有属性 |
示例
显示我的访客 Wi-Fi 密码。
{ "command": "action.devices.commands.GetGuestNetworkPassword", "params": {} }
成果
成果 | 类型 | 说明 |
---|---|---|
guestNetworkPassword |
String |
必填。 访客网络的密码。 |
示例
显示我的访客 Wi-Fi 密码。
{ "guestNetworkPassword": "123456" }
action.devices.commands.TestNetworkSpeed
测试网络下载和上传速度。
此命令需要以下属性:{ "supportsNetworkDownloadSpeedTest": true, "supportsNetworkUploadSpeedTest": true }
参数
参数 | 类型 | 说明 |
---|---|---|
testDownloadSpeed |
Boolean |
必填。 指示是否应测试下载速度。 |
testUploadSpeed |
Boolean |
必填。 指示是否应测试上传速度。 |
followUpToken |
String |
必填。 Google 提供的用于跟进响应的令牌。 |
示例
什么是 Wi-Fi 网速?
{ "command": "action.devices.commands.TestNetworkSpeed", "params": { "testDownloadSpeed": true, "testUploadSpeed": true, "followUpToken": "123" } }
相关错误
尝试请求速度测试时出错。
支持的值:
networkSpeedTestInProgress
后续回复
具有此特征的设备可能会在 EXECUTE
操作中返回以下后续响应载荷。如需详细了解如何实现后续响应,请参阅智能家居 Action 通知。
载荷包含下列各项之一:
成功:networkDownloadSpeedMbps
字段 | 类型 | 说明 |
---|---|---|
followUpToken |
String |
必填。 原始 EXECUTE 请求中提供的令牌。 |
status |
String |
必填。 请求的结果。 支持的值:
|
networkDownloadSpeedMbps |
编号 |
必填。 网络下载速度(以 MB/秒为单位)。 |
成功:networkUploadSpeedMbps
字段 | 类型 | 说明 |
---|---|---|
followUpToken |
String |
必填。 原始 EXECUTE 请求中提供的令牌。 |
status |
String |
必填。 请求的结果。 支持的值:
|
networkUploadSpeedMbps |
编号 |
必填。 网络上传速度(以 MB/秒为单位)。 |
成功:networkDownloadSpeedMbps 和 networkUploadSpeedMbps
字段 | 类型 | 说明 |
---|---|---|
followUpToken |
String |
必填。 原始 EXECUTE 请求中提供的令牌。 |
status |
String |
必填。 请求的结果。 支持的值:
|
networkDownloadSpeedMbps |
编号 |
必填。 网络下载速度(以 MB/秒为单位)。 |
networkUploadSpeedMbps |
编号 |
必填。 网络上传速度(以 MB/秒为单位)。 |
失败
字段 | 类型 | 说明 |
---|---|---|
followUpToken |
String |
必填。 原始 EXECUTE 请求中提供的令牌。 |
status |
String |
必填。 请求的结果。 支持的值:
|
errorCode |
String |
必填。 该值可以是此特征的任何错误代码,例如 |
示例
Wi-Fi 网速是多少?(跟进回复)
{ "NetworkControl": { "priority": 0, "followUpResponse": { "status": "SUCCESS", "networkDownloadSpeedMbps": 23.3, "networkUploadSpeedMbps": 10.2, "followUpToken": "1234" } } }
Wi-Fi 网速是多少?(失败的跟进响应)
{ "NetworkControl": { "priority": 0, "followUpResponse": { "status": "FAILURE", "errorCode": "transientError", "followUpToken": "1234" } } }
设备错误
查看错误和异常的完整列表。尝试控制指定的网络配置文件时出错。
支持的值:
networkProfileNotRecognized
尝试请求速度测试时出错。
支持的值:
networkSpeedTestInProgress