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.

networkProfiles Array <String>

Indicates the supported network profile names.

supportsEnablingNetworkProfile Boolean

Set to true if network profiles can be enabled.

supportsDisablingNetworkProfile Boolean

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.

supportsGettingGuestNetworkPassword Boolean

(Default: false)

Set to true if the guest network password can be obtained via the action.devices.commands.GetGuestNetworkPassword command.

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"
  ]
}
Request
{
    "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
    "inputs": [{
      "intent": "action.devices.SYNC"
    }]
}
Node.js
'use strict';

const {smarthome} = require('actions-on-google');
const functions = require('firebase-functions');

const app = smarthome();

app.onSync((body, headers) => {
  return {
    requestId: body.requestId,
    payload: {
      agentUserId: '1836.15267389',
      devices: [{
        id: '123',
        type: 'action.devices.types.ROUTER',
        traits: [
          'action.devices.traits.NetworkControl'
        ],
        name: {
          defaultNames: ['Sirius Cybernetics Router 2331'],
          name: 'Router',
          nicknames: ['Upstairs Router']
        },
        willReportState: true,
        attributes: {
          supportsEnablingGuestNetwork: true,
          supportsDisablingGuestNetwork: true,
          supportsEnablingNetworkProfile: true,
          supportsDisablingNetworkProfile: true,
          supportsNetworkDownloadSpeedTest: true,
          supportsNetworkUploadSpeedTest: true,
          supportsGettingGuestNetworkPassword: true,
          networkProfiles: [
            'kids'
          ]
        },
        deviceInfo: {
          manufacturer: 'Sirius Cybernetics',
          model: '2331B',
          hwVersion: '11.2',
          swVersion: '11.4'
        }
      }]
    }
  };
});

// ...

exports.smarthome = functions.https.onRequest(app);
Java
@NotNull
@Override
@SmartHomeSnippetJson("smart-home-traits-networkcontrol_sync.json")
public SyncResponse onSync(@NotNull SyncRequest syncRequest, @Nullable Map<?, ?> headers) {
  Payload payload = new Payload();
  payload.setAgentUserId("1836.15267389");

  payload.setDevices(
      new Device[] {
        new Device.Builder()
            .setId("123")
            .setType("action.devices.types.ROUTER")
            .addTrait("action.devices.traits.NetworkControl")
            .setName(
                Collections.singletonList("Sirius Cybernetics Router 2331"),
                "Router",
                Collections.singletonList("Upstairs Router"))
            .setWillReportState(true)
            .setAttributes(
                new JSONObject()
                    .put("supportsEnablingGuestNetwork", true)
                    .put("supportsDisablingGuestNetwork", true)
                    .put("supportsEnablingNetworkProfile", true)
                    .put("supportsDisablingNetworkProfile", true)
                    .put("supportsNetworkDownloadSpeedTest", true)
                    .put("supportsNetworkUploadSpeedTest", true)
                    .put("supportsGettingGuestNetworkPassword", true)
                    .put("networkProfiles", new String[] {"kids"}))
            .setDeviceInfo("Sirius Cybernetics", "2331B", "11.2", "11.4")
            .build()
      });

  return new SyncResponse(syncRequest.getRequestId(), payload);
}
JSON
{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "payload": {
    "agentUserId": "1836.15267389",
    "devices": [
      {
        "id": "123",
        "type": "action.devices.types.ROUTER",
        "traits": [
          "action.devices.traits.NetworkControl"
        ],
        "name": {
          "defaultNames": [
            "Sirius Cybernetics Router 2331"
          ],
          "name": "Router",
          "nicknames": [
            "Upstairs Router"
          ]
        },
        "willReportState": true,
        "attributes": {
          "supportsEnablingGuestNetwork": true,
          "supportsDisablingGuestNetwork": true,
          "supportsEnablingNetworkProfile": true,
          "supportsDisablingNetworkProfile": true,
          "supportsNetworkDownloadSpeedTest": true,
          "supportsNetworkUploadSpeedTest": true,
          "supportsGettingGuestNetworkPassword": true,
          "networkProfiles": [
            "kids"
          ]
        },
        "deviceInfo": {
          "manufacturer": "Sirius Cybernetics",
          "model": "2331B",
          "hwVersion": "11.2",
          "swVersion": "11.4"
        }
      }
    ]
  }
}
Validator

Device STATES

Devices 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 network is enabled.

networkSettings Object

Contains the SSID of the network.

ssid String

Required:

  • ssid
guestNetworkEnabled Boolean

Whether the guest network is enabled.

guestNetworkSettings Object

Contains the SSID of the guest network.

ssid String

Required:

  • 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.

Examples

Device with an active network.
{
  "networkEnabled": true,
  "networkSettings": {
    "ssid": "home-network-123"
  },
  "guestNetworkSettings": {
    "ssid": "home-network-123-guest"
  },
  "numConnectedDevices": 4,
  "networkUsageMB": 100.8
}

Sample QUERY Request and Response

User What's my network usage?
Google Assistant The network usage is 100.8 megabytes.
Request
{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "inputs": [{
    "intent": 'action.devices.QUERY',
    "payload": {
      "devices": [{
        "id": "123",
        "customData": {
          "fooValue": 74,
          "barValue": true,
          "bazValue": "foo"
        }
      }]
    }
  }]
}
Node.js
'use strict';

const {smarthome} = require('actions-on-google');
const functions = require('firebase-functions');

const app = smarthome();

app.onQuery((body, headers) => {
  return {
    requestId: body.requestId,
    payload: {
      devices: {
        123: {
          online: true,
          networkEnabled: true,
          networkSettings: {
            ssid: 'home-network-123'
          },
          numConnectedDevices: 4,
          networkUsageMB: 100.8,
          status: 'SUCCESS'
        }
      }
    }
  };
});

// ...

exports.smarthome = functions.https.onRequest(app);
Java
@NotNull
@Override
@SmartHomeSnippetJson("smart-home-traits-networkcontrol_query.json")
public QueryResponse onQuery(@NotNull QueryRequest queryRequest, @Nullable Map<?, ?> map) {
  QueryResponse.Payload payload = new QueryResponse.Payload();
  payload.setDevices(
      new HashMap<String, Map<String, Object>>() {
        {
          put(
              "123",
              new HashMap<String, Object>() {
                {
                  put("online", true);
                  put("networkEnabled", true);
                  put(
                      "networkSettings",
                      new HashMap<String, Object>() {
                        {
                          put("ssid", "home-network-123");
                        }
                      });
                  put("numConnectedDevices", 4);
                  put("networkUsageMB", 100.8);
                  put("status", "SUCCESS");
                }
              });
        }
      });
  return new QueryResponse(queryRequest.getRequestId(), payload);
}
JSON
{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "payload": {
    "devices": {
      "123": {
        "online": true,
        "networkEnabled": true,
        "networkSettings": {
          "ssid": "home-network-123"
        },
        "numConnectedDevices": 4,
        "networkUsageMB": 100.8,
        "status": "SUCCESS"
      }
    }
  }
}

Device COMMANDS

action.devices.commands.EnableDisableGuestNetwork

Enable or disable the guest network.

Parameters Type Description
enable Boolean

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

Required:

  • enable

action.devices.commands.EnableDisableNetworkProfile

Enable or disable a network by profile.

Parameters Type Description
profile String

The profile name from networkProfiles attribute.

enable Boolean

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

Required:

  • profile
  • enable

Related errors:

  • networkProfileNotRecognized: The user tried to enable or disable the network for an unrecognized network profile.

action.devices.commands.GetGuestNetworkPassword

Get the guest network password. This command has no parameters.

Response payload:

States Type Description
guestNetworkPassword String

The password for the guest network.

Required:

  • guestNetworkPassword

action.devices.commands.TestNetworkSpeed

Test the network download and upload speed.

Parameters Type Description
testDownloadSpeed Boolean

Indicates whether the download speed should be tested.

testUploadSpeed Boolean

Indicates whether the upload speed should be tested.

followUpToken String

Google-provided token for follow-up response.

Required:

  • testDownloadSpeed
  • testUploadSpeed
  • followUpToken

Related errors:

  • networkSpeedTestInProgress: The user tried to get the network speed when a speed test is already being run.

Sample EXECUTE Request and Response

Example: Turn on the guest network

Request
{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "inputs": [{
    "intent": "action.devices.EXECUTE",
    "payload": {
      "commands": [{
        "devices": [{
          "id": "123"
         }],
        "execution": [{
          "command": "action.devices.commands.EnableDisableGuestNetwork",
          "params": {
            "enable": true
          }
        }]
      }]
    }
  }]
}
Node.js
'use strict';

const {smarthome} = require('actions-on-google');
const functions = require('firebase-functions');

const app = smarthome();

app.onExecute((body, headers) => {
  return {
    requestId: body.requestId,
    payload: {
      commands: [{
        ids: ['123'],
        status: 'SUCCESS',
        states: {
          guestNetworkEnabled: true
        }
      }]
    }
  };
});

// ...

exports.smarthome = functions.https.onRequest(app);
Java
@NotNull
@Override
@SmartHomeSnippetJson("smart-home-traits-networkcontrol_execute_1.json")
public ExecuteResponse onExecute(
    @NotNull ExecuteRequest executeRequest, @Nullable Map<?, ?> map) {
  ExecuteResponse.Payload payload = new ExecuteResponse.Payload();
  payload.setCommands(
      new Commands[] {
        new Commands(
            new String[] {"123"},
            "SUCCESS",
            new HashMap<String, Object>() {
              {
                put("guestNetworkEnabled", true);
              }
            },
            null,
            null)
      });
  return new ExecuteResponse(executeRequest.getRequestId(), payload);
}
JSON
{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "payload": {
    "commands": [
      {
        "ids": [
          "123"
        ],
        "status": "SUCCESS",
        "states": {
          "guestNetworkEnabled": true
        }
      }
    ]
  }
}

Example: Turn off the kids network

Request
{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "inputs": [{
    "intent": "action.devices.EXECUTE",
    "payload": {
      "commands": [{
        "devices": [{
          "id": "123"
         }],
        "execution": [{
          "command": "action.devices.commands.EnableDisableNetworkProfile",
          "params": {
            "profile": "kids",
            "enable": false
          }
        }]
      }]
    }
  }]
}
Node.js
'use strict';

const {smarthome} = require('actions-on-google');
const functions = require('firebase-functions');

const app = smarthome();

app.onExecute((body, headers) => {
  return {
    requestId: body.requestId,
    payload: {
      commands: [{
        ids: ['123'],
        status: 'SUCCESS'
      }]
    }
  };
});

// ...

exports.smarthome = functions.https.onRequest(app);
Java
@NotNull
@Override
@SmartHomeSnippetJson("smart-home-traits-networkcontrol_execute_2.json")
public ExecuteResponse onExecute(
    @NotNull ExecuteRequest executeRequest, @Nullable Map<?, ?> map) {
  ExecuteResponse.Payload payload = new ExecuteResponse.Payload();
  payload.setCommands(
      new Commands[] {new Commands(new String[] {"123"}, "SUCCESS", null, null, null)});

  return new ExecuteResponse(executeRequest.getRequestId(), payload);
}
JSON
{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "payload": {
    "commands": [
      {
        "ids": [
          "123"
        ],
        "status": "SUCCESS"
      }
    ]
  }
}

Example: Test the Wi-Fi speed

Request
{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "inputs": [{
    "intent": "action.devices.EXECUTE",
    "payload": {
      "commands": [{
        "devices": [{
          "id": "123"
         }],
        "execution": [{
          "command": "action.devices.commands.TestNetworkSpeed",
          "params": {
            "testDownloadSpeed": true,
            "testUploadSpeed": true
          }
        }]
      }]
    }
  }]
}
Node.js
'use strict';

const {smarthome} = require('actions-on-google');
const functions = require('firebase-functions');

const app = smarthome();

app.onExecute((body, headers) => {
  return {
    requestId: body.requestId,
    payload: {
      commands: [{
        ids: ['123'],
        status: 'PENDING'
      }]
    }
  };
});

// ...

exports.smarthome = functions.https.onRequest(app);
Java
@NotNull
@Override
@SmartHomeSnippetJson("smart-home-traits-networkcontrol_execute_3.json")
public ExecuteResponse onExecute(
    @NotNull ExecuteRequest executeRequest, @Nullable Map<?, ?> map) {
  ExecuteResponse.Payload payload = new ExecuteResponse.Payload();
  payload.setCommands(
      new Commands[] {new Commands(new String[] {"123"}, "PENDING", null, null, null)});

  return new ExecuteResponse(executeRequest.getRequestId(), payload);
}
JSON
{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "payload": {
    "commands": [
      {
        "ids": [
          "123"
        ],
        "status": "PENDING"
      }
    ]
  }
}

Example: Show my guest Wi-Fi password

Request
{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "inputs": [{
    "intent": "action.devices.EXECUTE",
    "payload": {
      "commands": [{
        "devices": [{
          "id": "123"
         }],
        "execution": [{
          "command": "action.devices.commands.GetGuestNetworkPassword"
        }]
      }]
    }
  }]
}
Node.js
'use strict';

const {smarthome} = require('actions-on-google');
const functions = require('firebase-functions');

const app = smarthome();

app.onExecute((body, headers) => {
  return {
    requestId: body.requestId,
    payload: {
      commands: [{
        ids: ['123'],
        states: {
          guestNetworkPassword: '123456'
        },
        status: 'SUCCESS'
      }]
    }
  };
});

// ...

exports.smarthome = functions.https.onRequest(app);
Java
@NotNull
@Override
@SmartHomeSnippetJson("smart-home-traits-networkcontrol_execute_4.json")
public ExecuteResponse onExecute(
    @NotNull ExecuteRequest executeRequest, @Nullable Map<?, ?> map) {
  ExecuteResponse.Payload payload = new ExecuteResponse.Payload();
  payload.setCommands(
      new Commands[] {
        new Commands(
            new String[] {"123"},
            "SUCCESS",
            new HashMap<String, Object>() {
              {
                put("guestNetworkPassword", "123456");
              }
            },
            null,
            null)
      });
  return new ExecuteResponse(executeRequest.getRequestId(), payload);
}
JSON
{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "payload": {
    "commands": [
      {
        "ids": [
          "123"
        ],
        "states": {
          "guestNetworkPassword": "123456"
        },
        "status": "SUCCESS"
      }
    ]
  }
}

Device ERRORS

See the full list of errors and exceptions.
  • networkProfileNotRecognized: The user tried to enable or disable the network for an unrecognized network profile.
  • networkSpeedTestInProgress: The user tried to get the network speed when a speed test is already being run.