Smart Home HumiditySetting Trait Schema

action.devices.traits.HumiditySetting - This trait belongs to devices that support humidity settings such as humidifiers and dehumidifiers.

Device ATTRIBUTES

Attribute Definition
humiditySetpointRange

Optional. Contains the minimum and maximum humidity levels as percentages.

  • minPercent Integer in the range of [0 - 100]. Optional. Defaults to 0. Represents the minimum humidity level as a percentage.
  • maxPercent Integer in the range of [0 - 100]. Optional. Defaults to 100. Represents the maximum humidity level as a percentage.
commandOnlyHumiditySetting Boolean. Optional. Defaults to false. Indicates if the device control uses one-way or two-way communication. Set to false if the device can confirm the state of the device after executing a command. If the device cannot confirm a command execution, set this value to true. If this value is set to true, use the HumidityRelative command. Avoid setting both commandOnlyHumiditySetting and queryOnlyHumiditySetting to true.
queryOnlyHumiditySetting Boolean. Optional. Defaults to false. Indicates if the device can only be queried for state information and cannot be controlled. Sensors that can only report humidity should set this field to true. Avoid setting both commandOnlyHumiditySetting and queryOnlyHumiditySetting to true.

Sample SYNC Request and Response

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.HUMIDIFIER',
        traits: [
          'action.devices.traits.StartStop',
          'action.devices.traits.FanSpeed',
          'action.devices.traits.HumiditySetting'
        ],
        name: {
          defaultNames: ['Sirius Cybernetics Corporation Humidifer'],
          name: 'Humidifier',
          nicknames: ['Bedroom Humidifier']
        },
        roomHint: 'Bedroom',
        willReportState: true,
        attributes: {
          pausable: true,
          availableFanSpeeds: {
            speeds: [{
              speed_name: 'Low',
              speed_values: [{
                speed_synonym: ['low', 'slow'],
                lang: 'en'
              }, {
                speed_synonym: ['niedrig', 'schleppend'],
                lang: 'de'
              }]
            }, {
              speed_name: 'High',
              speed_values: [{
                speed_synonym: ['high'],
                lang: 'en'
              }, {
                speed_synonym: ['hoch'],
                lang: 'de'
              }]
            }],
            ordered: true
          },
          reversible: true,
          humiditySetpointRange: {
            minPercent: 30,
            maxPercent: 100
          }
        },
        deviceInfo: {
          manufacturer: 'Sirius Cybernetics Corporation',
          model: '8675309',
          hwVersion: '3.2',
          swVersion: '11.4'
        },
        customData: {
          fooValue: 74,
          barValue: true,
          bazValue: 'goatjive'
        }
      }]
    }
  };
});

// ...

exports.smarthome = functions.https.onRequest(app);
Java
@NotNull
@Override
public SyncResponse onSync(@NotNull SyncRequest syncRequest, @Nullable Map<?, ?> headers) {
  Payload payload = new Payload();
  payload.setAgentUserId("1836.15267389");
  payload.setDevices(new SyncResponse.Payload.Device[] {
    new SyncResponse.Payload.Device.Builder()
        .setId("1836.15267389")
        .setType("action.devices.types.HUMIDIFIER")
        .addTrait("action.devices.traits.StartStop")
        .addTrait("action.devices.traits.FanSpeed")
        .addTrait("action.devices.traits.HumiditySetting")
        .setName(
            Collections.singletonList("Sirius Cybernetics Corporation Humidifier"),
            "Humidifier",
            Collections.singletonList("Bedroom Humidifier")
        )
        .setWillReportState(true)
        .setAttributes(new JSONObject()
            .put("pausable", true)
            .put("humiditySetpointRange", new JSONObject()
                .put("minPercent", 30)
                .put("maxPercent", 100)
            )
            .put("availableFanSpeeds", new JSONObject()
                .put("speeds", new JSONObject[] {
                    new JSONObject()
                        .put("speed_name", "Low")
                        .put("speed_values", new JSONObject[] {
                        new JSONObject()
                            .put("speed_synonym", new String[] {"low", "slow"})
                            .put("lang", "en"),
                        new JSONObject()
                            .put("speed_synonym", new String[] {"niedrig", "schleppend"})
                            .put("lang", "de")
                    }),
                    new JSONObject()
                        .put("speed_name", "High")
                        .put("speed_values", new JSONObject[] {
                        new JSONObject()
                            .put("speed_synonym", new String[] {"high"})
                            .put("lang", "en"),
                        new JSONObject()
                            .put("speed_synonym", new String[] {"hoch"})
                            .put("lang", "de")
                    })
                })
                .put("ordered", true)
            )
            .put("reversible", true)
        )
        .setDeviceInfo("Sirius Cybernetics Corporation", "233451", "3.2", "11.4")
        .setCustomData(new JSONObject()
            .put("fooValue", 74)
            .put("barValue", true)
            .put("bazValue", "goatjive")
            .toString()
        )
        .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.HUMIDIFIER",
        "traits": [
          "action.devices.traits.StartStop",
          "action.devices.traits.FanSpeed",
          "action.devices.traits.HumiditySetting"
        ],
        "name": {
          "defaultNames": [
            "Sirius Cybernetics Corporation Humidifer"
          ],
          "name": "Humidifier",
          "nicknames": [
            "Bedroom Humidifier"
          ]
        },
        "roomHint": "Bedroom",
        "willReportState": true,
        "attributes": {
          "pausable": true,
          "availableFanSpeeds": {
            "speeds": [
              {
                "speed_name": "Low",
                "speed_values": [
                  {
                    "speed_synonym": [
                      "low",
                      "slow"
                    ],
                    "lang": "en"
                  },
                  {
                    "speed_synonym": [
                      "niedrig",
                      "schleppend"
                    ],
                    "lang": "de"
                  }
                ]
              },
              {
                "speed_name": "High",
                "speed_values": [
                  {
                    "speed_synonym": [
                      "high"
                    ],
                    "lang": "en"
                  },
                  {
                    "speed_synonym": [
                      "hoch"
                    ],
                    "lang": "de"
                  }
                ]
              }
            ],
            "ordered": true
          },
          "reversible": true,
          "humiditySetpointRange": {
            "minPercent": 30,
            "maxPercent": 100
          }
        },
        "deviceInfo": {
          "manufacturer": "Sirius Cybernetics Corporation",
          "model": "8675309",
          "hwVersion": "3.2",
          "swVersion": "11.4"
        },
        "customData": {
          "fooValue": 74,
          "barValue": true,
          "bazValue": "goatjive"
        }
      }
    ]
  }
}
Validator

Device STATES

State Definition
humiditySetpointPercent Integer. Required for Humidifier and Dehumidifier devices. Optional for Sensor devices. Indicates the current target humidity percentage of the device. Percentage in the range [minHumidityPercent- maxHumidityPercent].
humidityAmbientPercent Integer in the range of [1 - 100]. Optional. Indicates the current ambient humidity reading of the device as a percentage.

Sample QUERY Request and Response

User What humidity does my humidifier show?
Google Assistant The humidifier is set to 20 percent and the current humidity reading is 15 percent.
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: {
          humiditySetpointPercent: 20,
          humidityAmbientPercent: 15
        },
        status: 'SUCCESS'
      }
    }
  };
});

// ...

exports.smarthome = functions.https.onRequest(app);
Java
@NotNull
@Override
public QueryResponse onQuery(@NotNull QueryRequest queryRequest, @Nullable Map<?, ?> map) {
  QueryResponse.Payload payload = new QueryResponse.Payload();
  payload.setDevices(new HashMap<String, Object>() {{      put("123", new HashMap<String, Object>() {{          put("online", true);
          put("humiditySetpointPercent", 20);
          put("humidityAmbientPercent", 15);
      }});
      put("status", "SUCCESS");
  }});

  return new QueryResponse(queryRequest.getRequestId(), payload);
}
JSON
{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "payload": {
    "devices": {
      "123": {
        "humiditySetpointPercent": 20,
        "humidityAmbientPercent": 15
      },
      "status": "SUCCESS"
    }
  }
}

Device COMMANDS

Command Parameters/Definition
action.devices.commands.SetHumidity

humidity: Integer in the range of [minHumidityPercent - maxHumidityPercent]. Required. Setpoint humidity percentage.

action.devices.commands.HumidityRelative

This command is only available if the commandOnlyHumiditySetting attribute of the device is set to true. This command, returns one of the following parameters in the response:

  • humidityRelativePercent: Integer in the range [-100, 100]. The exact percentage value to adjust the humidity level. For example, Turn down 5 percent results in decreasing the humidity by 5 percent.

  • humidityRelativeWeight: Integer in the range [-5, 5]. This indicates the amount of ambiguous humidity change from a small amount, Turn down a little, to a large amount, A lot more humid.

Sample EXECUTE Request and Response

User Set the humidity to 20 percent.
Google Assistant Sure, setting the humidity on bedroom humidifier to 20 percent.
Request
{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "inputs": [{
    "intent": "action.devices.EXECUTE",
    "payload": {
      "commands": [{
        "devices": [{
          "id": "123",
          "customData": {
            "fooValue": 74,
            "barValue": true,
            "bazValue": "lambtwirl"
          }
        }],
        "execution": [{
          "command": "action.devices.commands.SetHumidity",
          "params": {
            "humidity": 20
          }
        }]
      }]
    }
  }]
}
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: {
          humiditySetpointPercent: 20,
          humidityAmbientPercent: 15
        }
      }]
    }
  };
});

// ...

exports.smarthome = functions.https.onRequest(app);
Java
@NotNull
@Override
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("humiditySetpointPercent", 20);
              put("humidityAmbientPercent", 15);
          }},
          null
      )
  });
  return new ExecuteResponse(executeRequest.getRequestId(), payload);
}
JSON
{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "payload": {
    "commands": [
      {
        "ids": [
          "123"
        ],
        "status": "SUCCESS",
        "states": {
          "humiditySetpointPercent": 20,
          "humidityAmbientPercent": 15
        }
      }
    ]
  }
}

Device ERRORS

See the full list of errors and exceptions.