Control Scene

Control scenes by triggering saved scene configurations.

Description

The scene control allows you to activate predefined scenes that can control multiple devices simultaneously.

Example

Request Topic

LYT/41e0d6b2-37de-43d8-a348-4ba94853b6cd/SCENE/CONTROL

Request Payload

Trigger a scene:

{
   "version": "v1.0",
   "scene_number": 9955,
   "type": "scene"
}

Field Descriptions

Field	Type	Required	Description
version	string	Yes	API version identifier (must be "v1.0")
type	string	Yes	Message type (must be "scene")
scene_number	number	Yes	Unique identifier of the scene to trigger

Response Topic

LYT/41e0d6b2-37de-43d8-a348-4ba94853b6cd/SCENE/E/STATUS

Response Payload

Success Response

{
   "version": "v1.0",
   "message": "success",
   "type": "scene",
   "scene_number": 9955,
   "scene": {}
}

Error Handling

The API may return various error responses based on different scenarios:

1. Constraint Error (Code: 3005)

a. Version Constraint:

{
   "message": "error",
   "message_type": {
      "code": 3005,
      "message": "version must be one of the following values: v1.0",
      "errorCode": "CONSTRAINT_ERROR"
   }
}

b. Type Constraint:

{
   "message": "error",
   "message_type": {      
      "code": 3005,
      "message": "type must be one of the following values: scene, master-scene",
      "errorCode": "CONSTRAINT_ERROR"
   }
}

c. Scene Number Constraint:

{
   "message": "error",
   "message_type": {
      "code": 3005,
      "message": "scene_number must be a number conforming to the specified constraints",
      "errorCode": "CONSTRAINT_ERROR"
   }
}

Constraint errors occur in the following cases:

1. Scene Number Constraints:

   • Scene number must be a valid number
   • Scene number field is missing
   • Scene number field has incorrect type (must be number)

2. Version Constraints:

   • Version is not exactly "v1.0"
   • Version field is missing
   • Version field has incorrect format

3. Type Constraints:

   • Type must be "scene"
   • Type field is missing
   • Type field has incorrect value

Resolution:

• Ensure scene_number is a valid number
• Always use "v1.0" as the version value
• Use "scene" as the type value
• Validate all parameters before sending

2. Scene Not Found Error (Code: 2012)

{
   "message": "error",
   "message_type": {
      "code": 3007,
      "message": "Scene not found",
      "errorCode": "SCENE_NOT_FOUND"
   }
}

When it occurs:

• The specified scene_number doesn't exist
• Scene has been deleted
• Scene is not configured

How to resolve:

1. Verify the scene_number is correct
2. Check if the scene exists in the system
3. Ensure the scene is properly configured
4. Use scene management API to list available scenes

3. Project Not Found Error (Code: 2002)

{
   "message": "error",
   "message_type": {
      "code": 2002,
      "message": "Project not found",
      "errorCode": "PROJECT_NOT_FOUND"
   }
}

When it occurs:

• project_uuid in MQTT topic is invalid
• Project has been deleted
• User doesn't have access to the project

How to resolve:

1. Verify project_uuid in the MQTT topic
2. Ensure project exists
3. Check access permissions

Error Code Summary

Code	Error Code	Description	Solution
3005	CONSTRAINT_ERROR	Parameter validation failed	Check input values
2012	SCENE_NOT_FOUND	Scene doesn't exist	Verify scene number
2002	PROJECT_NOT_FOUND	Project doesn't exist	Check project_uuid

Implementation Notes

1. Scene Control:

   • Scenes allow controlling multiple devices with a single command
   • Scene configurations are predefined and stored in the system
   • Scene execution is atomic - all device states change together
   • Scene numbers must be unique within a project

2. Best Practices:

   • Keep track of scene numbers used in your project
   • Test scenes with all devices before deployment
   • Consider network latency when triggering multiple scenes
   • Implement error handling for all possible response codes