Smart Home NetworkControl Trait Schema

action.devices.traits.NetworkControl - This trait belongs to devices that support reporting network data and performing network specific operations.

Device ATTRIBUTES

Devices with this trait may report the following attributes as part of the SYNC operation. To learn more about handling SYNC intents, see Intent fulfillment.

Attributes Type Description
supportsEnablingGuestNetwork Boolean

(Default: false)

Set to true if the guest network can be enabled.
supportsDisablingGuestNetwork Boolean

(Default: false)

Set to true if the guest network can be disabled.
supportsGettingGuestNetworkPassword Boolean

(Default: false)

Set to true if the guest network password can be obtained via the GetGuestNetworkPassword command.
networkProfiles Array

Indicates the supported network profile names.
[item, ...] String

Name of a network profile representing a group of related devices.
supportsEnablingNetworkProfile Boolean

(Default: "false")

Set to true if network profiles can be enabled.
supportsDisablingNetworkProfile Boolean

(Default: "false")

Set to true if network profiles can be disabled.
supportsNetworkDownloadSpeedTest Boolean

(Default: false)

Set to true if a download speed test can be run.
supportsNetworkUploadSpeedTest Boolean

(Default: false)

Set to true if an upload speed test can be run.

Examples

Network device that supports guest network, profiles, and speed test.

{
  "supportsEnablingGuestNetwork": true,
  "supportsDisablingGuestNetwork": true,
  "supportsEnablingNetworkProfile": true,
  "supportsDisablingNetworkProfile": true,
  "supportsNetworkDownloadSpeedTest": true,
  "supportsNetworkUploadSpeedTest": true,
  "supportsGettingGuestNetworkPassword": true,
  "networkProfiles": [
    "Kids"
  ]
}

Device STATES

Entities with this trait may report the following states as part of the QUERY operation. To learn more about handling QUERY intents, see Intent fulfillment.

States Type Description
networkEnabled Boolean

Whether the main network is enabled.
networkSettings Object

Contains the SSID of the main network.
ssid String

Required.

Network SSID.
guestNetworkEnabled Boolean

Whether the guest network is enabled.
guestNetworkSettings Object

Contains the SSID of the guest network.
ssid String

Required.

Network SSID.
numConnectedDevices Integer

The number of devices connected to the network.
networkUsageMB Number

The network usage in MB (megabytes). The network usage is within the current billing period, which can be useful to monitor with respect to a billing period network usage limit.
networkUsageLimitMB Number

The network usage limit in MB (megabytes). The network usage limit is within the current billing period.
networkUsageUnlimited Boolean

Whether the network usage is unlimited. The device state networkUsageLimitMB will be ignored if this is set to true.
lastNetworkDownloadSpeedTest Object

Contains the results of the most recent network download speed test.
downloadSpeedMbps Number

The download speed in Mbps (megabits per second) of the last network speed test.
unixTimestampSec Integer

The Unix timestamp (number of seconds since the Unix Epoch) of when the last network download speed test was run.
status String

Indicates whether the last network download speed test succeeded or failed.

Supported values:

SUCCESS
FAILURE
lastNetworkUploadSpeedTest Object

Contains the results of the most recent network upload speed test.
uploadSpeedMbps Number

The upload speed in Mbps (megabits per second) of the last network speed test.
unixTimestampSec Integer

The Unix timestamp (number of seconds since the Unix Epoch) of when the last network upload speed test was run.
status String

Indicates whether the last network upload speed test succeeded or failed.

Supported values:

SUCCESS
FAILURE
networkSpeedTestInProgress Boolean

(Default: false)

Whether a speed test is currently being run.
networkProfilesState Object

State for network profiles. This top level object should contain key value pairs where the key is the name of one of the network profiles listed in the networkProfiles attribute and the value should be that profile's corresponding state.
<string> Object

An object storing the state of an individual network profile. The value of the key should be the name of one of the network profiles in the networkProfiles attribute.
enabled Boolean

The current enabled/disabled state of the network profile.

Examples

Device with an active network.

{
  "networkEnabled": true,
  "networkSettings": {
    "ssid": "home-network-123"
  },
  "guestNetworkSettings": {
    "ssid": "home-network-123-guest"
  },
  "numConnectedDevices": 4,
  "networkUsageMB": 100.8
}

Device with an active network and speed test results.

{
  "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"
  }
}

Device with an active network and speed test in progress.

{
  "networkEnabled": true,
  "networkSettings": {
    "ssid": "home-network-123"
  },
  "guestNetworkSettings": {
    "ssid": "home-network-123-guest"
  },
  "numConnectedDevices": 4,
  "networkUsageMB": 100.8,
  "networkSpeedTestInProgress": true
}

Device with the "kids" networkProfile disabled.

{
  "networkEnabled": true,
  "networkSettings": {
    "ssid": "home-network-123"
  },
  "networkProfilesState": {
    "parents": {
      "enabled": true
    },
    "kids": {
      "enabled": false
    }
  }
}

Device COMMANDS

Devices with this trait may respond to the following commands as part of the EXECUTE operation. To learn more about handling EXECUTE intents, see Intent fulfillment.

action.devices.commands.EnableDisableGuestNetwork

Enable or disable the guest network. Secondary user verification with PIN must be used. A user's home security can be considered affected if other security devices are disabled via these commands.

This command requires the following attributes: 
{
  "supportsEnablingGuestNetwork": true,
  "supportsDisablingGuestNetwork": true
}

Parameters

Parameters Type Description
enable Boolean

Required.

True to enable the guest network, false to disable the guest network.

Examples

Turn on the guest network.

{
  "command": "action.devices.commands.EnableDisableGuestNetwork",
  "params": {
    "enable": true
  }
}

action.devices.commands.EnableDisableNetworkProfile

Enable or disable a network profile. Secondary user verification with PIN must be used. A user's home security can be considered affected if other security devices are disabled via these commands.

This command requires the following attributes: 
{
  "supportsEnablingNetworkProfile": true,
  "supportsDisablingNetworkProfile": true
}

Parameters

Parameters Type Description
profile String

Required.

The profile name from networkProfiles attribute.
enable Boolean

Required.

True to enable the profile, false to disable the profile.

Examples

Turn off the internet for the kids.

{
  "command": "action.devices.commands.EnableDisableNetworkProfile",
  "params": {
    "profile": "Kids",
    "enable": false
  }
}

An error occurred while attempting to control the given network profile.

Supported values:

networkProfileNotRecognized

action.devices.commands.GetGuestNetworkPassword

Get the guest network password. Secondary user verification with PIN must be used. A user's home security can be considered affected if other security devices are disabled via these commands.

This command requires the following attributes: 
{
  "supportsGettingGuestNetworkPassword": true
}

Parameters

Parameters Type Description

No properties

Examples

Show my guest Wi-Fi password.

{
  "command": "action.devices.commands.GetGuestNetworkPassword",
  "params": {}
}

Results

Results Type Description
guestNetworkPassword String

Required.

The password for the guest network.

Examples

Show my guest Wi-Fi password.

{
  "guestNetworkPassword": "123456"
}

action.devices.commands.TestNetworkSpeed

Test the network download and upload speed.

This command requires the following attributes: 
{
  "supportsNetworkDownloadSpeedTest": true,
  "supportsNetworkUploadSpeedTest": true
}

Parameters

Parameters Type Description
testDownloadSpeed Boolean

Required.

Indicates whether the download speed should be tested.
testUploadSpeed Boolean

Required.

Indicates whether the upload speed should be tested.
followUpToken String

Required.

Google-provided token for follow-up response.

Examples

What's the Wi-Fi speed?

{
  "command": "action.devices.commands.TestNetworkSpeed",
  "params": {
    "testDownloadSpeed": true,
    "testUploadSpeed": true,
    "followUpToken": "123"
  }
}

An error occurred while attempting to request a speed test.

Supported values:

networkSpeedTestInProgress

Follow-up responses

Devices with this trait may return the following follow-up response payload as part of the EXECUTE operation. To learn more about implementing follow-up responses, see Notifications for smart home Actions.

The payload contains one of the following:

Success: networkDownloadSpeedMbps

Fields Type Description
followUpToken String

Required.

Token provided in the original EXECUTE request.
status String

Required.

Result of the request.

Supported values:

SUCCESS
networkDownloadSpeedMbps Number

Required.

The network download speed measured in megabits per second.

Success: networkUploadSpeedMbps

Fields Type Description
followUpToken String

Required.

Token provided in the original EXECUTE request.
status String

Required.

Result of the request.

Supported values:

SUCCESS
networkUploadSpeedMbps Number

Required.

The network upload speed measured in megabits per second.

Success: networkDownloadSpeedMbps and networkUploadSpeedMbps

Fields Type Description
followUpToken String

Required.

Token provided in the original EXECUTE request.
status String

Required.

Result of the request.

Supported values:

SUCCESS
networkDownloadSpeedMbps Number

Required.

The network download speed measured in megabits per second.
networkUploadSpeedMbps Number

Required.

The network upload speed measured in megabits per second.

Failure

Fields Type Description
followUpToken String

Required.

Token provided in the original EXECUTE request.
status String

Required.

Result of the request.

Supported values:

FAILURE
errorCode String

Required.

The value can be any error code for this trait, for example, transientError.

Examples

What's the Wi-Fi speed? (follow-up response)

{
  "NetworkControl": {
    "priority": 0,
    "followUpResponse": {
      "status": "SUCCESS",
      "networkDownloadSpeedMbps": 23.3,
      "networkUploadSpeedMbps": 10.2,
      "followUpToken": "1234"
    }
  }
}

What's the Wi-Fi speed? (follow-up response with failure)

{
  "NetworkControl": {
    "priority": 0,
    "followUpResponse": {
      "status": "FAILURE",
      "errorCode": "transientError",
      "followUpToken": "1234"
    }
  }
}

Device ERRORS

See the full list of errors and exceptions.

An error occurred while attempting to control the given network profile.

Supported values:

networkProfileNotRecognized

An error occurred while attempting to request a speed test.

Supported values:

networkSpeedTestInProgress