API Reference
Start typing to search…

HumiditySetting

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"]}'