API Reference
Start typing to search…

StartStop

The StartStop trait enables devices to control operational states beyond simple on/off functionality. This trait is used for devices that have distinct start and stop operations, such as appliances with running cycles, motors, pumps, and other equipment that perform specific tasks or operations.

Supported Attributes

1. pausable (Boolean)

  • Type: Boolean
  • Description: When true, the device supports pausing operations (not just start/stop)
  • Default: false
  • Usage: Enables the PauseUnpause command for devices that can pause mid-operation

2. availableZones (Array)

  • Type: Array of strings
  • Description: Defines zones or areas that can be controlled independently
  • Usage: For devices that can operate in specific zones (e.g., robotic vacuums, irrigation systems)
  • Example: ["zone1", "zone2", "kitchen", "living_room"]

Supported Commands

1. StartStop

Controls the start and stop operations of the device.

Parameters

{
  start: boolean,        // Required: true to start, false to stop
  zone?: string         // Optional: specific zone to control (if availableZones supported)
}

Parameter Validation

  • start: Required boolean value
  • zone: Optional string, must be in availableZones if provided
  • true: Starts the device operation
  • false: Stops the device operation

2. PauseUnpause

Controls pause and resume operations (only available if pausable is true).

Parameters

{
  pause: boolean  // Required: true to pause, false to unpause/resume
}

Parameter Validation

  • pause: Required boolean value
  • Only valid if pausable attribute is true
  • true: Pauses the current operation
  • false: Resumes the paused operation

Usage Examples

Basic Start/Stop Operations

Start Device Operation

{
  "sn": "WASHING_MACHINE_SERIAL",
  "iotDevs": ["washer_main"],
  "iotCmds": [
    {
      "command": "StartStop",
      "params": {
        "start": true
      }
    }
  ]
}

Stop Device Operation

{
  "sn": "WASHING_MACHINE_SERIAL",
  "iotDevs": ["washer_main"],
  "iotCmds": [
    {
      "command": "StartStop",
      "params": {
        "start": false
      }
    }
  ]
}

Robot Vacuum Operations

Start Cleaning

{
  "sn": "ROBOT_VACUUM_SERIAL",
  "iotDevs": ["vacuum_main"],
  "iotCmds": [
    {
      "command": "StartStop",
      "params": {
        "start": true
      }
    }
  ]
}

Stop and Return to Dock

{
  "sn": "ROBOT_VACUUM_SERIAL",
  "iotDevs": ["vacuum_main"],
  "iotCmds": [
    {
      "command": "StartStop",
      "params": {
        "start": false
      }
    }
  ]
}

Start Cleaning Specific Zone

{
  "sn": "ROBOT_VACUUM_SERIAL",
  "iotDevs": ["vacuum_main"],
  "iotCmds": [
    {
      "command": "StartStop",
      "params": {
        "start": true,
        "zone": "living_room"
      }
    }
  ]
}

Pause/Resume Operations

Pause Operation

{
  "sn": "DISHWASHER_SERIAL",
  "iotDevs": ["dishwasher_main"],
  "iotCmds": [
    {
      "command": "PauseUnpause",
      "params": {
        "pause": true
      }
    }
  ]
}

Resume Operation

{
  "sn": "DISHWASHER_SERIAL",
  "iotDevs": ["dishwasher_main"],
  "iotCmds": [
    {
      "command": "PauseUnpause",
      "params": {
        "pause": false
      }
    }
  ]
}

Irrigation System Operations

Start Watering Zone 1

{
  "sn": "IRRIGATION_CONTROLLER",
  "iotDevs": ["irrigation_main"],
  "iotCmds": [
    {
      "command": "StartStop",
      "params": {
        "start": true,
        "zone": "zone1"
      }
    }
  ]
}

Stop All Zones

{
  "sn": "IRRIGATION_CONTROLLER",
  "iotDevs": ["irrigation_main"],
  "iotCmds": [
    {
      "command": "StartStop",
      "params": {
        "start": false
      }
    }
  ]
}

Pool Equipment Operations

Start Pool Pump

{
  "sn": "POOL_CONTROLLER_SERIAL",
  "iotDevs": ["pump_controller"],
  "iotCmds": [
    {
      "command": "StartStop",
      "params": {
        "start": true
      }
    }
  ]
}

Start Pool Cleaner

{
  "sn": "POOL_CLEANER_SERIAL",
  "iotDevs": ["cleaner_main"],
  "iotCmds": [
    {
      "command": "StartStop",
      "params": {
        "start": true
      }
    }
  ]
}

Kitchen Appliance Operations

Start Dishwasher Cycle

{
  "sn": "SMART_DISHWASHER_SERIAL",
  "iotDevs": ["dishwasher_main"],
  "iotCmds": [
    {
      "command": "StartStop",
      "params": {
        "start": true
      }
    }
  ]
}

Start Coffee Brewing

{
  "sn": "COFFEE_MAKER_SERIAL",
  "iotDevs": ["brew_controller"],
  "iotCmds": [
    {
      "command": "StartStop",
      "params": {
        "start": true
      }
    }
  ]
}

Device Types Using StartStop Trait

Laundry Appliances

  • Washing machines
  • Dryers
  • Washer-dryer combos
  • Steam cleaners

Kitchen Appliances

  • Dishwashers
  • Coffee makers
  • Blenders
  • Food processors

Cleaning Devices

  • Robot vacuums
  • Robot mops
  • Carpet cleaners
  • Steam cleaners

Outdoor Equipment

  • Irrigation systems
  • Pool pumps
  • Pool cleaners
  • Lawn mowers

Industrial Equipment

  • Pumps
  • Compressors
  • Conveyor systems
  • Manufacturing equipment

HVAC Systems

  • Ventilation fans
  • Air purifiers
  • Dehumidifiers
  • Heat recovery systems

Best Practices

1. State Management

  • Track device operational states in your application
  • Handle state transitions appropriately
  • Provide clear feedback on the operation status
  • Monitor for error conditions during operation

2. Zone Management

  • Validate zone names against availableZones
  • Handle zone conflicts and scheduling
  • Provide zone status information to users
  • Consider zone priorities and dependencies

3. Pause/Resume Handling

  • Check pausable attribute before offering pause functionality
  • Handle pause state persistence across network interruptions
  • Provide clear indication of paused state
  • Consider timeout for paused operations

4. Error Prevention

  • Validate device readiness before starting operations
  • Check for conflicting operations
  • Implement proper error recovery procedures
  • Provide meaningful error messages to users

5. User Experience

  • Provide clear operation status feedback
  • Allow easy start/stop/pause controls
  • Show progress indicators for long operations
  • Implement operation history and logging

Related Traits

The StartStop trait is commonly combined with:

  • OnOff: For basic device power control
  • Modes: For operational mode settings
  • Timer: For timed operations
  • StatusReport: For operation status monitoring
  • Dock: For robotic devices
  • RunCycle: For cyclical operations

State Reporting

Devices with the StartStop trait typically report:

  • isRunning: Whether the device is currently running
  • isPaused: Whether device is currently paused (if pausable)
  • operationState: Current operational state
  • activeZones: Currently active zones (if zone-capable)
  • lastOperationStart: Timestamp of last operation start
  • lastOperationEnd: Timestamp of last operation end
  • operationProgress: Progress percentage (if available)
  • online: Device connectivity status

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

The StartStop trait enables devices to control operational states beyond simple on/off functionality. This trait is used for devices that have distinct start and stop operations, such as appliances with running cycles, motors, pumps, and other equipment that performs specific tasks or operations.

Supported Attributes

1. pausable (Boolean)

  • Type: Boolean
  • Description: When true, the device supports pausing operations (not just start/stop)
  • Default: false
  • Usage: Enables the PauseUnpause command for devices that can pause mid-operation

2. availableZones (Array)

  • Type: Array of strings
  • Description: Defines zones or areas that can be controlled independently
  • Usage: For devices that can operate in specific zones (e.g., robotic vacuums, irrigation systems)
  • Example: ["zone1", "zone2", "kitchen", "living_room"]

Supported Commands

1. StartStop

Controls the start and stop operations of the device.

Parameters

{
  start: boolean,        // Required: true to start, false to stop
  zone?: string         // Optional: specific zone to control (if availableZones supported)
}

Parameter Validation

  • start: Required boolean value
  • zone: Optional string, must be in availableZones if provided
  • true: Starts the device operation
  • false: Stops the device operation

2. PauseUnpause

Controls pause and resume operations (only available if pausable is true).

Parameters

{
  pause: boolean  // Required: true to pause, false to unpause/resume
}

Parameter Validation

  • pause: Required boolean value
  • Only valid if pausable attribute is true
  • true: Pauses the current operation
  • false: Resumes the paused operation

Usage Examples

Basic Start/Stop Operations

Start Device Operation

{
  "sn": "WASHING_MACHINE_SERIAL",
  "iotDevs": ["washer_main"],
  "iotCmds": [
    {
      "command": "StartStop",
      "params": {
        "start": true
      }
    }
  ]
}

Stop Device Operation

{
  "sn": "WASHING_MACHINE_SERIAL",
  "iotDevs": ["washer_main"],
  "iotCmds": [
    {
      "command": "StartStop",
      "params": {
        "start": false
      }
    }
  ]
}

Robot Vacuum Operations

Start Cleaning

{
  "sn": "ROBOT_VACUUM_SERIAL",
  "iotDevs": ["vacuum_main"],
  "iotCmds": [
    {
      "command": "StartStop",
      "params": {
        "start": true
      }
    }
  ]
}

Stop and Return to Dock

{
  "sn": "ROBOT_VACUUM_SERIAL",
  "iotDevs": ["vacuum_main"],
  "iotCmds": [
    {
      "command": "StartStop",
      "params": {
        "start": false
      }
    }
  ]
}

Start Cleaning Specific Zone

{
  "sn": "ROBOT_VACUUM_SERIAL",
  "iotDevs": ["vacuum_main"],
  "iotCmds": [
    {
      "command": "StartStop",
      "params": {
        "start": true,
        "zone": "living_room"
      }
    }
  ]
}

Pause/Resume Operations

Pause Operation

{
  "sn": "DISHWASHER_SERIAL",
  "iotDevs": ["dishwasher_main"],
  "iotCmds": [
    {
      "command": "PauseUnpause",
      "params": {
        "pause": true
      }
    }
  ]
}

Resume Operation

{
  "sn": "DISHWASHER_SERIAL",
  "iotDevs": ["dishwasher_main"],
  "iotCmds": [
    {
      "command": "PauseUnpause",
      "params": {
        "pause": false
      }
    }
  ]
}

Irrigation System Operations

Start Watering Zone 1

{
  "sn": "IRRIGATION_CONTROLLER",
  "iotDevs": ["irrigation_main"],
  "iotCmds": [
    {
      "command": "StartStop",
      "params": {
        "start": true,
        "zone": "zone1"
      }
    }
  ]
}

Stop All Zones

{
  "sn": "IRRIGATION_CONTROLLER",
  "iotDevs": ["irrigation_main"],
  "iotCmds": [
    {
      "command": "StartStop",
      "params": {
        "start": false
      }
    }
  ]
}

Pool Equipment Operations

Start Pool Pump

{
  "sn": "POOL_CONTROLLER_SERIAL",
  "iotDevs": ["pump_controller"],
  "iotCmds": [
    {
      "command": "StartStop",
      "params": {
        "start": true
      }
    }
  ]
}

Start Pool Cleaner

{
  "sn": "POOL_CLEANER_SERIAL",
  "iotDevs": ["cleaner_main"],
  "iotCmds": [
    {
      "command": "StartStop",
      "params": {
        "start": true
      }
    }
  ]
}

Kitchen Appliance Operations

Start Dishwasher Cycle

{
  "sn": "SMART_DISHWASHER_SERIAL",
  "iotDevs": ["dishwasher_main"],
  "iotCmds": [
    {
      "command": "StartStop",
      "params": {
        "start": true
      }
    }
  ]
}

Start Coffee Brewing

{
  "sn": "COFFEE_MAKER_SERIAL",
  "iotDevs": ["brew_controller"],
  "iotCmds": [
    {
      "command": "StartStop",
      "params": {
        "start": true
      }
    }
  ]
}

Combined Operations

Set Mode and Start Operation

{
  "sn": "WASHING_MACHINE_SERIAL",
  "iotDevs": ["washer_main"],
  "iotCmds": [
    {
      "command": "SetModes",
      "params": {
        "updateModeSettings": {
          "wash_cycle": "delicate"
        }
      }
    },
    {
      "command": "StartStop",
      "params": {
        "start": true
      }
    }
  ]
}

Start with Timer

{
  "sn": "DRYER_SERIAL",
  "iotDevs": ["dryer_main"],
  "iotCmds": [
    {
      "command": "TimerStart",
      "params": {
        "timerTimeSec": 3600
      }
    },
    {
      "command": "StartStop",
      "params": {
        "start": true
      }
    }
  ]
}

Device Types Using StartStop Trait

Laundry Appliances

  • Washing machines
  • Dryers
  • Washer-dryer combos
  • Steam cleaners

Kitchen Appliances

  • Dishwashers
  • Coffee makers
  • Blenders
  • Food processors

Cleaning Devices

  • Robot vacuums
  • Robot mops
  • Carpet cleaners
  • Steam cleaners

Outdoor Equipment

  • Irrigation systems
  • Pool pumps
  • Pool cleaners
  • Lawn mowers

Industrial Equipment

  • Pumps
  • Compressors
  • Conveyor systems
  • Manufacturing equipment

HVAC Systems

  • Ventilation fans
  • Air purifiers
  • Dehumidifiers
  • Heat recovery systems

Device Configuration Examples

Basic Start/Stop Device

{
  "traits": ["StartStop"],
  "deviceType": "pump"
}

Pausable Appliance

{
  "traits": ["StartStop", "Modes"],
  "attributes": [
    {
      "name": "pausable",
      "value": true
    }
  ],
  "deviceType": "washing_machine"
}

Zone-Controlled System

{
  "traits": ["StartStop", "Timer"],
  "attributes": [
    {
      "name": "availableZones",
      "value": ["zone1", "zone2", "zone3", "zone4"]
    }
  ],
  "deviceType": "irrigation_controller"
}

Robot Vacuum with Zones and Pause

{
  "traits": ["StartStop", "Dock", "Modes"],
  "attributes": [
    {
      "name": "pausable",
      "value": true
    },
    {
      "name": "availableZones",
      "value": ["living_room", "kitchen", "bedroom", "bathroom"]
    }
  ],
  "deviceType": "robot_vacuum"
}

Smart Dishwasher

{
  "traits": ["OnOff", "StartStop", "Modes", "Timer"],
  "attributes": [
    {
      "name": "pausable",
      "value": true
    }
  ],
  "deviceType": "dishwasher"
}

Related Traits

The StartStop trait is commonly combined with:

  • OnOff: For basic device power control
  • Modes: For operational mode settings
  • Timer: For timed operations
  • StatusReport: For operation status monitoring
  • Dock: For robotic devices
  • RunCycle: For cyclical operations

State Reporting

Devices with the StartStop trait typically report:

  • isRunning: Whether the device is currently running
  • isPaused: Whether device is currently paused (if pausable)
  • operationState: Current operational state
  • activeZones: Currently active zones (if zone-capable)
  • lastOperationStart: Timestamp of last operation start
  • lastOperationEnd: Timestamp of last operation end
  • operationProgress: Progress percentage (if available)
  • online: Device connectivity status

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