API Reference
Start typing to search…

FanSpeed

The FanSpeed trait enables devices to control fan speed levels and direction. This trait is used for ceiling fans, exhaust fans, HVAC systems, and other devices with variable speed fan control capabilities.

Supported Attributes

1. availableFanSpeeds (Array)

  • Type: Array of objects
  • Description: Defines the named fan speed levels supported by the device
  • Structure: 
    [
  {
    "speed_name": "low",
    "speed_values": [
      {
        "speed_synonym": ["low", "slow", "quiet"],
        "lang": "en"
      }
    ]
  },
  {
    "speed_name": "medium",
    "speed_values": [
      {
        "speed_synonym": ["medium", "med", "normal"],
        "lang": "en"
      }
    ]
  },
  {
    "speed_name": "high",
    "speed_values": [
      {
        "speed_synonym": ["high", "fast", "max"],
        "lang": "en"
      }
    ]
  }
]
  • Usage: Defines available named speed settings and their synonyms

2. reversible (Boolean)

  • Type: Boolean
  • Description: When true, the fan supports direction reversal
  • Default: false
  • Usage: Enables the Reverse command for changing fan rotation direction

3. commandOnlyFanSpeed (Boolean)

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

4. supportsFanSpeedPercent (Boolean)

  • Type: Boolean
  • Description: When true, the device supports percentage-based fan speed control
  • Default: false
  • Usage: Enables precise speed control using percentage values (0-100%)

Supported Commands

1. SetFanSpeed

Sets the fan to a specific speed level or percentage.

Parameters

{
  fanSpeed?: string,        // Optional: Named speed level
  fanSpeedPercent?: number  // Optional: Speed percentage (0-100)
}

Parameter Validation

  • Either fanSpeed or fanSpeedPercent must be provided (not both)
  • fanSpeed: Must be one of the speed names from availableFanSpeeds
  • fanSpeedPercent: Must be between 0 and 100, only valid if supportsFanSpeedPercent is true

2. Reverse

Reverses the fan rotation direction (only available if reversible is true).

Parameters

{"reverse":true}

Parameter Validation

  • Command is only valid if reversible attribute is true
  • Reverses the current rotation direction

Usage Examples

Named Speed Control

Set Fan to Low Speed

{
  "sn": "FAN_SERIAL_NUMBER",
  "iotDevs": ["fan_motor"],
  "iotCmds": [
    {
      "command": "SetFanSpeed",
      "params": {
        "fanSpeed": "low"
      }
    }
  ]
}

Set Fan to Medium Speed

{
  "sn": "FAN_SERIAL_NUMBER",
  "iotDevs": ["fan_motor"],
  "iotCmds": [
    {
      "command": "SetFanSpeed",
      "params": {
        "fanSpeed": "medium"
      }
    }
  ]
}

Set Fan to High Speed

{
  "sn": "FAN_SERIAL_NUMBER",
  "iotDevs": ["fan_motor"],
  "iotCmds": [
    {
      "command": "SetFanSpeed",
      "params": {
        "fanSpeed": "high"
      }
    }
  ]
}

Turn Fan Off (Speed Zero)

{
  "sn": "FAN_SERIAL_NUMBER",
  "iotDevs": ["fan_motor"],
  "iotCmds": [
    {
      "command": "SetFanSpeed",
      "params": {
        "fanSpeed": "off"
      }
    }
  ]
}

Percentage Speed Control

Set Fan to 25% Speed

{
  "sn": "FAN_SERIAL_NUMBER",
  "iotDevs": ["fan_motor"],
  "iotCmds": [
    {
      "command": "SetFanSpeed",
      "params": {
        "fanSpeedPercent": 25
      }
    }
  ]
}

Set Fan to 75% Speed

{
  "sn": "FAN_SERIAL_NUMBER",
  "iotDevs": ["fan_motor"],
  "iotCmds": [
    {
      "command": "SetFanSpeed",
      "params": {
        "fanSpeedPercent": 75
      }
    }
  ]
}

Set Fan to Maximum Speed

{
  "sn": "FAN_SERIAL_NUMBER",
  "iotDevs": ["fan_motor"],
  "iotCmds": [
    {
      "command": "SetFanSpeed",
      "params": {
        "fanSpeedPercent": 100
      }
    }
  ]
}

Turn Fan Off (0% Speed)

{
  "sn": "FAN_SERIAL_NUMBER",
  "iotDevs": ["fan_motor"],
  "iotCmds": [
    {
      "command": "SetFanSpeed",
      "params": {
        "fanSpeedPercent": 0
      }
    }
  ]
}

Direction Control

Reverse Fan Direction

{
  "sn": "CEILING_FAN_SERIAL",
  "iotDevs": ["fan_motor"],
  "iotCmds": [
    {
      "command": "Reverse",
      "params": {}
    }
  ]
}

Combined Operations

Set Speed and Reverse Direction

{
  "sn": "CEILING_FAN_SERIAL",
  "iotDevs": ["fan_motor"],
  "iotCmds": [
    {
      "command": "SetFanSpeed",
      "params": {
        "fanSpeed": "medium"
      }
    },
    {
      "command": "Reverse",
      "params": {}
    }
  ]
}

Turn On Fan with Specific Speed

{
  "sn": "FAN_SERIAL_NUMBER",
  "iotDevs": ["fan_motor"],
  "iotCmds": [
    {
      "command": "OnOff",
      "params": {
        "on": true
      }
    },
    {
      "command": "SetFanSpeed",
      "params": {
        "fanSpeed": "high"
      }
    }
  ]
}

Multi-Speed Fan Examples

5-Speed Fan Control

{
  "sn": "MULTI_SPEED_FAN_SERIAL",
  "iotDevs": ["fan_motor"],
  "iotCmds": [
    {
      "command": "SetFanSpeed",
      "params": {
        "fanSpeed": "speed3"
      }
    }
  ]
}

Variable Speed with Percentage

{
  "sn": "VARIABLE_FAN_SERIAL",
  "iotDevs": ["fan_motor"],
  "iotCmds": [
    {
      "command": "SetFanSpeed",
      "params": {
        "fanSpeedPercent": 45
      }
    }
  ]
}

Device Types Using FanSpeed Trait

Ceiling Fans

  • Residential ceiling fans
  • Commercial ceiling fans
  • Industrial ceiling fans
  • Outdoor ceiling fans

Exhaust Fans

  • Bathroom exhaust fans
  • Kitchen range hoods
  • Whole house fans
  • Attic ventilation fans

HVAC Components

  • Air handler fans
  • Condenser fans
  • Heat pump fans
  • Ventilation system fans

Portable Fans

  • Tower fans
  • Desk fans
  • Pedestal fans
  • Bladeless fans

Industrial Fans

  • Warehouse fans
  • Agricultural fans
  • Manufacturing ventilation
  • Cooling system fans

Fan Speed Configurations

Basic 3-Speed Fan

{
  "traits": ["OnOff", "FanSpeed"],
  "attributes": [
    {
      "name": "availableFanSpeeds",
      "value": [
        {
          "speed_name": "low",
          "speed_values": [
            {
              "speed_synonym": ["low", "slow", "1"],
              "lang": "en"
            }
          ]
        },
        {
          "speed_name": "medium",
          "speed_values": [
            {
              "speed_synonym": ["medium", "med", "2"],
              "lang": "en"
            }
          ]
        },
        {
          "speed_name": "high",
          "speed_values": [
            {
              "speed_synonym": ["high", "fast", "3"],
              "lang": "en"
            }
          ]
        }
      ]
    }
  ]
}

Reversible Ceiling Fan

{
  "traits": ["OnOff", "FanSpeed"],
  "attributes": [
    {
      "name": "reversible",
      "value": true
    },
    {
      "name": "availableFanSpeeds",
      "value": [
        {
          "speed_name": "low",
          "speed_values": [{"speed_synonym": ["low"], "lang": "en"}]
        },
        {
          "speed_name": "medium",
          "speed_values": [{"speed_synonym": ["medium"], "lang": "en"}]
        },
        {
          "speed_name": "high",
          "speed_values": [{"speed_synonym": ["high"], "lang": "en"}]
        }
      ]
    }
  ]
}

Variable Speed Fan with Percentage

{
  "traits": ["OnOff", "FanSpeed"],
  "attributes": [
    {
      "name": "supportsFanSpeedPercent",
      "value": true
    },
    {
      "name": "availableFanSpeeds",
      "value": [
        {
          "speed_name": "low",
          "speed_values": [{"speed_synonym": ["low"], "lang": "en"}]
        },
        {
          "speed_name": "high",
          "speed_values": [{"speed_synonym": ["high"], "lang": "en"}]
        }
      ]
    }
  ]
}

Multi-Speed Industrial Fan

{
  "traits": ["OnOff", "FanSpeed"],
  "attributes": [
    {
      "name": "availableFanSpeeds",
      "value": [
        {
          "speed_name": "speed1",
          "speed_values": [{"speed_synonym": ["speed1", "lowest"], "lang": "en"}]
        },
        {
          "speed_name": "speed2",
          "speed_values": [{"speed_synonym": ["speed2", "low"], "lang": "en"}]
        },
        {
          "speed_name": "speed3",
          "speed_values": [{"speed_synonym": ["speed3", "medium"], "lang": "en"}]
        },
        {
          "speed_name": "speed4",
          "speed_values": [{"speed_synonym": ["speed4", "high"], "lang": "en"}]
        },
        {
          "speed_name": "speed5",
          "speed_values": [{"speed_synonym": ["speed5", "maximum"], "lang": "en"}]
        }
      ]
    },
    {
      "name": "supportsFanSpeedPercent",
      "value": true
    }
  ]
}

Fan Direction Explained

Forward Direction (Standard)

  • Summer Mode: Pushes air downward
  • Usage: Creates cooling breeze effect
  • Airflow: Downward and outward
  • Energy: More effective for cooling

Reverse Direction

  • Winter Mode: Pulls air upward
  • Usage: Circulates warm air from ceiling
  • Airflow: Upward and inward
  • Energy: Helps distribute heated air

Best Practices

1. Understand Fan Capabilities

  • Check availableFanSpeeds for supported named speeds
  • Verify supportsFanSpeedPercent before using percentage control
  • Confirm reversible attribute before attempting direction changes

2. Choose Appropriate Control Method

  • Use named speeds for simple user interfaces
  • Use percentage control for precise speed adjustment
  • Consider user preferences and device capabilities

3. Optimize for Energy Efficiency

  • Use lower speeds when possible to reduce energy consumption
  • Consider seasonal direction changes for ceiling fans
  • Combine with temperature sensors for automatic control

4. Handle Speed Transitions

  • Allow time for fan speed changes to stabilize
  • Consider motor startup characteristics
  • Monitor actual speed vs. commanded speed

5. User Experience Considerations

  • Provide clear feedback on speed changes
  • Use intuitive speed names and synonyms
  • Consider noise levels at different speeds

Related Traits

The FanSpeed trait is commonly combined with:

  • OnOff: Essential for complete fan control
  • TemperatureSetting: For climate control systems
  • Timer: For scheduled fan operation
  • Modes: For different operating modes (normal, sleep, etc.)

State Reporting

Devices with FanSpeed trait typically report:

  • currentFanSpeedSetting: Current named speed setting
  • currentFanSpeedPercent: Current speed percentage (if supported)
  • fanDirection: Current rotation direction (if reversible)
  • on: Current on/off state
  • online: Device connectivity status

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

Technical Considerations

Motor Types

  • AC Motors: Typically use named speeds (low/medium/high)
  • DC Motors: Often support percentage control for precise speed
  • Variable Frequency Drives: Support both named and percentage control

Power Consumption

  • Lower speeds consume significantly less power
  • Consider energy efficiency ratings
  • Monitor power consumption at different speeds

Noise Levels

  • Higher speeds typically produce more noise
  • Consider acoustic ratings for residential applications
  • Balance airflow needs with noise tolerance

Installation Considerations

  • Verify electrical compatibility for speed control
  • Consider ceiling height for optimal airflow
  • Ensure proper mounting for reversible fans