# Smart Home NetworkControl Trait Schema

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

> [!NOTE]
> **Note:** You should use [secondary user verification](https://developers.home.google.com/cloud-to-cloud/enhancements/secondary-user-verification) for this trait with the `DOOR`, `GARAGE`, `GATE`, or `WINDOW` device type.

## Device ATTRIBUTES

Devices with this trait may report the following
attributes as part of the [`SYNC`](https://developers.home.google.com/cloud-to-cloud/intents/sync) operation. To learn
more about handling `SYNC` intents, see
[Intent fulfillment](https://developers.home.google.com/cloud-to-cloud/integration/sync).

| 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`](https://developers.home.google.com/cloud-to-cloud/intents/query) operation. To learn
more about handling `QUERY` intents, see
[Intent fulfillment](https://developers.home.google.com/cloud-to-cloud/integration/query-execute).

| 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

> [!NOTE]
> **Note:** This trait supports providing additional state with a secondary user verification challenge response. See [supported challenge types](https://developers.home.google.com/cloud-to-cloud/enhancements/secondary-user-verification#supported_challenge_types) for more details.

Devices with this trait may respond to the following
commands as part of the [`EXECUTE`](https://developers.home.google.com/cloud-to-cloud/intents/execute) operation. To learn
more about handling `EXECUTE` intents, see
[Intent fulfillment](https://developers.home.google.com/cloud-to-cloud/integration/query-execute#handle_execute_intents).

### `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
  }
}
```

#### Related errors

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

#### Related errors

An error occurred while attempting to request a speed test.

Supported values:

`networkSpeedTestInProgress`

> [!NOTE]
> **Note:** You cannot send a synchronous `EXECUTE` response to this command. The response to the command must be sent via a follow-up response using the following payload format.

#### 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](https://developers.home.google.com/cloud-to-cloud/integration/notifications).

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](https://developers.home.google.com/cloud-to-cloud/intents/errors-exceptions#error_list) 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](https://developers.home.google.com/cloud-to-cloud/intents/errors-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`