OpenClose

The OpenClose trait enables devices to control opening and closing mechanisms with precise positioning. This trait is used for curtains, blinds, garage doors, valves, and other devices that can be positioned anywhere between fully open and fully closed states.

Supported Attributes

1. `openDirection` (Array)

Type: Array of strings
Description: Specifies the supported opening directions
Possible Values: ["UP", "DOWN", "LEFT", "RIGHT", "IN", "OUT"]
Usage: Defines which directions the device can open/close

2. `queryOnlyOpenClose` (Boolean)

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

3. `discreteOnlyOpenClose` (Boolean)

Type: Boolean
Description: When true, the device only supports fully open or fully closed positions (no intermediate positions)
Default: false
Usage: Set to true for devices without variable positioning

4. `commandOnlyOpenClose` (Boolean)

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

5. `motorReversible` (Boolean)

Type: Boolean
Description: When true, the motor direction can be reversed for installation flexibility
Default: false
Usage: Allows reversing motor direction for different mounting orientations

Supported Commands

1. `OpenClose`

Controls the open/close position of the device.

Parameters

{
  openPercent: number  // Required: Position percentage (0-100)
}

Parameter Validation

openPercent: Must be between 0 and 100 (inclusive)
0: Fully closed position
100: Fully open position
Intermediate values: Partial open positions (if supported)
For discrete-only devices, only 0 and 100 are valid

Usage Examples

Basic Position Control

Fully Open

{
  "sn": "CURTAIN_MOTOR_SERIAL",
  "iotDevs": ["curtain_motor"],
  "iotCmds": [
    {
      "command": "OpenClose",
      "params": {
        "openPercent": 100
      }
    }
  ]
}

Fully Close

{
  "sn": "CURTAIN_MOTOR_SERIAL",
  "iotDevs": ["curtain_motor"],
  "iotCmds": [
    {
      "command": "OpenClose",
      "params": {
        "openPercent": 0
      }
    }
  ]
}

Half Open

{
  "sn": "CURTAIN_MOTOR_SERIAL",
  "iotDevs": ["curtain_motor"],
  "iotCmds": [
    {
      "command": "OpenClose",
      "params": {
        "openPercent": 50
      }
    }
  ]
}

Quarter Open

{
  "sn": "BLIND_CONTROLLER_SERIAL",
  "iotDevs": ["blind_motor"],
  "iotCmds": [
    {
      "command": "OpenClose",
      "params": {
        "openPercent": 25
      }
    }
  ]
}

Precise Positioning

75% Open for Privacy

{
  "sn": "WINDOW_BLIND_SERIAL",
  "iotDevs": ["blind_main"],
  "iotCmds": [
    {
      "command": "OpenClose",
      "params": {
        "openPercent": 75
      }
    }
  ]
}

10% Open for Ventilation

{
  "sn": "WINDOW_CONTROLLER",
  "iotDevs": ["window_actuator"],
  "iotCmds": [
    {
      "command": "OpenClose",
      "params": {
        "openPercent": 10
      }
    }
  ]
}

Multiple Device Control

Open All Curtains to 80%

{
  "sn": "MULTI_CURTAIN_CONTROLLER",
  "iotDevs": ["living_room", "bedroom", "kitchen"],
  "iotCmds": [
    {
      "command": "OpenClose",
      "params": {
        "openPercent": 80
      }
    }
  ]
}

Close All Blinds

{
  "sn": "BUILDING_BLIND_SYSTEM",
  "iotDevs": ["north_blinds", "south_blinds", "east_blinds", "west_blinds"],
  "iotCmds": [
    {
      "command": "OpenClose",
      "params": {
        "openPercent": 0
      }
    }
  ]
}

Garage Door Control

Open Garage Door

{
  "sn": "GARAGE_DOOR_OPENER",
  "iotDevs": ["main_door"],
  "iotCmds": [
    {
      "command": "OpenClose",
      "params": {
        "openPercent": 100
      }
    }
  ]
}

Close Garage Door

{
  "sn": "GARAGE_DOOR_OPENER",
  "iotDevs": ["main_door"],
  "iotCmds": [
    {
      "command": "OpenClose",
      "params": {
        "openPercent": 0
      }
    }
  ]
}

Valve Control

Open Water Valve 60%

{
  "sn": "SMART_VALVE_SERIAL",
  "iotDevs": ["water_valve"],
  "iotCmds": [
    {
      "command": "OpenClose",
      "params": {
        "openPercent": 60
      }
    }
  ]
}

Close Gas Valve (Safety)

{
  "sn": "GAS_VALVE_CONTROLLER",
  "iotDevs": ["main_gas_valve"],
  "iotCmds": [
    {
      "command": "OpenClose",
      "params": {
        "openPercent": 0
      }
    }
  ]
}

Device Types Using OpenClose Trait

Window Treatments

Motorized curtains
Automated blinds
Roller shades
Vertical blinds

Doors and Gates

Garage doors
Sliding doors
Gate operators
Barn doors

HVAC Components

Dampers
Louvers
Vent controls
Air intake controls

Industrial Applications

Valves
Conveyor gates
Loading dock doors
Industrial shutters

Specialty Applications

Skylight openers
Greenhouse vents
Awning controls
Projection screens

Device Configurations

Basic Curtain Motor

{
  "traits": ["OpenClose"],
  "attributes": [
    {
      "name": "openDirection",
      "value": ["LEFT", "RIGHT"]
    }
  ]
}

Vertical Blind Controller

{
  "traits": ["OpenClose"],
  "attributes": [
    {
      "name": "openDirection",
      "value": ["UP", "DOWN"]
    }
  ]
}

Discrete Garage Door

{
  "traits": ["OpenClose"],
  "attributes": [
    {
      "name": "discreteOnlyOpenClose",
      "value": true
    },
    {
      "name": "openDirection",
      "value": ["UP"]
    }
  ]
}

Reversible Motor System

{
  "traits": ["OpenClose"],
  "attributes": [
    {
      "name": "motorReversible",
      "value": true
    },
    {
      "name": "openDirection",
      "value": ["UP", "DOWN"]
    }
  ]
}

Position Sensor Only

{
  "traits": ["OpenClose"],
  "attributes": [
    {
      "name": "queryOnlyOpenClose",
      "value": true
    }
  ]
}

Opening Directions Explained

UP/DOWN

UP: Opens upward (roller shades, garage doors)
DOWN: Opens downward (top-hung windows)
Usage: Vertical movement devices

LEFT/RIGHT

LEFT: Opens to the left
RIGHT: Opens to the right
Usage: Horizontal sliding devices (curtains, sliding doors)

IN/OUT

IN: Opens inward (casement windows)
OUT: Opens outward (awning windows)
Usage: Hinged devices with directional opening

Best Practices

1. Understand Device Capabilities

Check discreteOnlyOpenClose before using intermediate positions
Verify supported openDirection values
Respect queryOnlyOpenClose and commandOnlyOpenClose restrictions

2. Safety Considerations

Implement obstruction detection for motorized devices
Provide manual override capabilities
Consider safety stops for large/heavy devices
Monitor motor current and temperature

3. Position Accuracy

Allow time for devices to reach target positions
Monitor actual position vs. commanded position
Implement position calibration procedures
Handle position drift over time

4. User Experience

Provide visual feedback during movement
Use reasonable movement speeds
Implement soft start/stop for smooth operation
Consider noise levels during operation

5. Maintenance

Regular cleaning of tracks and mechanisms
Lubrication of moving parts
Calibration of position sensors
Motor brush replacement (if applicable)

Related Traits

The OpenClose trait is often combined with:

OnOff: For basic motor on/off control
Timer: For scheduled opening/closing
Scene: For preset position configurations
SensorState: For position feedback and obstruction detection
StatusReport: For motor health and maintenance alerts

State Reporting

Devices with OpenClose trait typically report:

openPercent: Current open percentage (0-100)
openState: Current state ("OPEN", "CLOSED", "OPENING", "CLOSING")
motorRunning: Whether motor is currently operating
obstruction: Obstruction detection status
position: Absolute position (if available)
calibrated: Whether device position is calibrated
online: Device connectivity status

Query current position:

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