The HumiditySetting trait enables devices to control humidity levels in an environment. This trait is used for humidifiers, dehumidifiers, HVAC systems, and other devices that can maintain specific humidity setpoints for comfort and air quality management.

Supported Attributes

1. `humiditySetpointRange` (Object)

Type: Object with humidity range limits
Description: Defines the valid humidity range for setpoints

Structure:

{
  "minPercent": 30,
  "maxPercent": 70
}

Usage: Validates humidity setpoint commands to ensure they're within device capabilities

2. `commandOnlyHumiditySetting` (Boolean)

Type: Boolean
Description: When true, the device only accepts humidity commands and cannot be queried for current settings
Default: false
Usage: Set to true for devices that can receive commands but don't report their humidity settings

3. `queryOnlyHumiditySetting` (Boolean)

Type: Boolean
Description: When true, the device can only be queried for humidity but cannot accept humidity commands
Default: false
Usage: Set to true for humidity sensors or read-only devices

4. `humiditySetpointStep` (Number)

Type: Float
Description: The minimum step size for humidity adjustments
Default: 1.0
Usage: Defines the precision of humidity control (e.g., 1% steps, 0.5% steps)

Supported Commands

1. `SetHumidity`

Sets the target humidity level.

Parameters

{
  humidity: number  // Required: Target humidity percentage (0-100)
}

Parameter Validation

humidity: Must be within humiditySetpointRange (minPercent to maxPercent)
Value represents relative humidity as a percentage
Must align with humiditySetpointStep if specified

2. `HumidityRelative`

Adjusts the current humidity setpoint by a relative amount.

Parameters

{
  humidityRelativePercent: number  // Required: Relative humidity change (-100 to +100)
}

Parameter Validation

humidityRelativePercent: Must be between -100 and +100
Final humidity must be within humiditySetpointRange
Positive values increase humidity, negative values decrease
Must align with humiditySetpointStep if specified

Usage Examples

Basic Humidity Control

Set Humidity to 50%

{
  "sn": "HUMIDIFIER_SERIAL",
  "iotDevs": ["humidity_controller"],
  "iotCmds": [
    {
      "command": "SetHumidity",
      "params": {
        "humidity": 50
      }
    }
  ]
}

Set Humidity to 40% (Dehumidifier)

{
  "sn": "DEHUMIDIFIER_SERIAL",
  "iotDevs": ["dehumid_main"],
  "iotCmds": [
    {
      "command": "SetHumidity",
      "params": {
        "humidity": 40
      }
    }
  ]
}

Set High Humidity (60%)

{
  "sn": "WHOLE_HOUSE_HUMIDIFIER",
  "iotDevs": ["hvac_humidity"],
  "iotCmds": [
    {
      "command": "SetHumidity",
      "params": {
        "humidity": 60
      }
    }
  ]
}

Relative Humidity Adjustments

Increase Humidity by 10%

{
  "sn": "HUMIDIFIER_SERIAL",
  "iotDevs": ["humidity_controller"],
  "iotCmds": [
    {
      "command": "HumidityRelative",
      "params": {
        "humidityRelativePercent": 10
      }
    }
  ]
}

Decrease Humidity by 5%

{
  "sn": "DEHUMIDIFIER_SERIAL",
  "iotDevs": ["dehumid_main"],
  "iotCmds": [
    {
      "command": "HumidityRelative",
      "params": {
        "humidityRelativePercent": -5
      }
    }
  ]
}

Seasonal Humidity Control

Winter Humidity Setting (Lower)

{
  "sn": "HVAC_CONTROLLER",
  "iotDevs": ["climate_control"],
  "iotCmds": [
    {
      "command": "SetHumidity",
      "params": {
        "humidity": 35
      }
    }
  ]
}

Summer Humidity Setting (Higher)

{
  "sn": "HVAC_CONTROLLER",
  "iotDevs": ["climate_control"],
  "iotCmds": [
    {
      "command": "SetHumidity",
      "params": {
        "humidity": 55
      }
    }
  ]
}

Combined Climate Control

Set Temperature and Humidity

{
  "sn": "SMART_THERMOSTAT",
  "iotDevs": ["climate_main"],
  "iotCmds": [
    {
      "command": "ThermostatTemperatureSetpoint",
      "params": {
        "thermostatTemperatureSetpoint": 22.0
      }
    },
    {
      "command": "SetHumidity",
      "params": {
        "humidity": 45
      }
    }
  ]
}

Room-Specific Humidity Control

Bedroom Humidity Control

{
  "sn": "BEDROOM_HUMIDIFIER",
  "iotDevs": ["bedroom_unit"],
  "iotCmds": [
    {
      "command": "SetHumidity",
      "params": {
        "humidity": 50
      }
    }
  ]
}

Basement Dehumidification

{
  "sn": "BASEMENT_DEHUMIDIFIER",
  "iotDevs": ["basement_unit"],
  "iotCmds": [
    {
      "command": "SetHumidity",
      "params": {
        "humidity": 35
      }
    }
  ]
}

Precision Humidity Control

Fine Adjustment (0.5% steps)

{
  "sn": "PRECISION_HUMIDIFIER",
  "iotDevs": ["precision_controller"],
  "iotCmds": [
    {
      "command": "SetHumidity",
      "params": {
        "humidity": 47.5
      }
    }
  ]
}

Scene Integration

Comfort Scene with Humidity

{
  "sn": "HOME_AUTOMATION_HUB",
  "iotDevs": ["climate_scene"],
  "iotCmds": [
    {
      "command": "ActivateScene",
      "params": {
        "scene": "comfort_mode",
        "sceneSettings": {
          "temperature": 23,
          "humidity": 50
        }
      }
    }
  ]
}

Device Types Using HumiditySetting Trait

Humidifiers

Ultrasonic humidifiers
Evaporative humidifiers
Steam humidifiers
Whole-house humidifiers

Dehumidifiers

Portable dehumidifiers
Whole-house dehumidifiers
Basement dehumidifiers
Commercial dehumidifiers

HVAC Systems

Smart thermostats with humidity control
HVAC controllers
Zone control systems
Heat recovery ventilators

Specialized Equipment

Greenhouse controllers
Wine cellar controllers
Museum climate control
Laboratory equipment

Air Quality Devices

Air purifiers with humidity control
Ventilation systems
Climate monitoring systems

Humidity Range Guidelines

Comfort Ranges

Optimal Comfort: 40-60% RH
Winter Indoor: 30-40% RH (to prevent condensation)
Summer Indoor: 40-50% RH (for comfort and efficiency)
Health Range: 40-60% RH (reduces allergens and pathogens)

Application-Specific Ranges

Bedrooms: 45-55% RH
Living Areas: 40-50% RH
Basements: 30-40% RH
Attics: 30-50% RH
Greenhouses: 50-70% RH
Wine Storage: 50-70% RH

Device Configuration Examples

Basic Humidifier

{
  "traits": ["OnOff", "HumiditySetting"],
  "attributes": [
    {
      "name": "humiditySetpointRange",
      "value": {
        "minPercent": 30,
        "maxPercent": 70
      }
    }
  ]
}

Precision Dehumidifier

{
  "traits": ["OnOff", "HumiditySetting", "FanSpeed"],
  "attributes": [
    {
      "name": "humiditySetpointRange",
      "value": {
        "minPercent": 25,
        "maxPercent": 65
      }
    },
    {
      "name": "humiditySetpointStep",
      "value": 0.5
    }
  ]
}

HVAC Humidity Control

{
  "traits": ["TemperatureSetting", "HumiditySetting", "FanSpeed"],
  "attributes": [
    {
      "name": "humiditySetpointRange",
      "value": {
        "minPercent": 20,
        "maxPercent": 80
      }
    }
  ]
}

Command-Only Humidity Controller

{
  "traits": ["HumiditySetting"],
  "attributes": [
    {
      "name": "commandOnlyHumiditySetting",
      "value": true
    },
    {
      "name": "humiditySetpointRange",
      "value": {
        "minPercent": 35,
        "maxPercent": 65
      }
    }
  ]
}

Humidity Sensor Only

{
  "traits": ["HumiditySetting", "SensorState"],
  "attributes": [
    {
      "name": "queryOnlyHumiditySetting",
      "value": true
    }
  ]
}

Related Traits

The HumiditySetting trait is commonly combined with:

TemperatureSetting: For complete climate control
OnOff: For basic device power control
FanSpeed: For circulation control
SensorState: For humidity monitoring
Timer: For scheduled humidity control
Modes: For different humidity control modes

State Reporting

Devices with HumiditySetting trait typically report:

humiditySetpoint: Current humidity setpoint
humidityAmbient: Current ambient humidity level
humidityMode: Current humidity control mode
waterLevel: Water tank level (for humidifiers)
filterStatus: Filter condition status
operatingState: Current device operating state
online: Device connectivity status

Query current humidity state:

curl -X POST "https://api.ultroncloud.com/usr/v5/GetGroupDeviceStates" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Ultron-Cloud-Appid: YOUR_APP_ID" \
  -H "Content-Type: application/json" \
  -d '{"groupId": "YOUR_LOCATION_ID", "snList": ["SN1", "SN2"]}'