Govee (Independent Publisher) (#3194)
* init * description and summary updates
This commit is contained in:
Rick Wilson
GitHub
Родитель
29f850a229
Коммит
05475b68d3
|
|
@ -0,0 +1,68 @@
|
|||
# Govee
|
||||
Offers seamless integration with [Govee's](https://us.govee.com) smart lighting systems, enabling users to effortlessly control and manage their devices. It allows for a wide range of functionalities including adjusting light settings, changing colors, modifying brightness, and accessing real-time device status.
|
||||
|
||||
The ability to automate and customize lighting setups makes this connector particularly useful for enhancing ambiance in smart homes, creating dynamic lighting scenes for various occasions, and integrating smart lighting into broader home automation systems. It offers a convenient and intuitive way for users to personalize their lighting experience and fully leverage the capabilities of Govee's smart lighting technology.
|
||||
|
||||
## Publisher: Richard Wilson
|
||||
|
||||
## Prerequisites
|
||||
|
||||
Before you can use the Govee connector, you must obtain a Govee Developer API Key. Follow these steps to acquire the key:
|
||||
|
||||
### Obtaining a Govee Developer API Key
|
||||
|
||||
1. **Download the Govee Home App:**
|
||||
- For iOS: [Govee Home on the App Store](https://apps.apple.com/us/app/govee-home/id1395696823)
|
||||
- For Android: [Govee Home on Google Play](https://play.google.com/store/apps/details?id=com.govee.home)
|
||||
|
||||
2. **Access Your Profile:**
|
||||
- Open the Govee Home App and navigate to the 'My Profile' page by tapping the profile icon (👤).
|
||||
|
||||
3. **Go to Settings:**
|
||||
- Click on the settings icon (⚙️) located at the top right corner to access the Settings menu.
|
||||
|
||||
4. **Apply for API Key:**
|
||||
- Select 'Apply for API Key' within the Settings menu.
|
||||
|
||||
5. **Complete Application Form:**
|
||||
- Fill in the required fields for 'Name' and 'Reason for application'.
|
||||
- Example reasons include home automation, third-party integration, or educational purposes.
|
||||
|
||||
6. **Agree to Terms of Service:**
|
||||
- Carefully read the Govee Developer API Terms of Service. Once you have understood the terms, check the box to indicate your acceptance.
|
||||
|
||||
7. **Submit Application:**
|
||||
- Click 'Submit' to send your application for an API key. Once approved, you will receive your Govee API Key, which is necessary to use this connector.
|
||||
|
||||
Please be aware that the API key approval process may take some time, and approval is at the discretion of Govee. Ensure that your application includes a valid and clear reason for requesting the API key to increase the likelihood of approval.
|
||||
|
||||
## Supported Operations
|
||||
|
||||
### 1. Run Command on Device
|
||||
|
||||
This operation allows you to send various commands to control your Govee device.
|
||||
|
||||
- **Input Properties:**
|
||||
- **Device MAC Address:** The unique MAC address of the Govee device to be controlled.
|
||||
- **Device Model:** The model number of the Govee device.
|
||||
- **Command Details:** An object containing the command to be executed. It includes:
|
||||
- **Name:** The command name (e.g., 'turn', 'brightness', 'color', 'colorTem').
|
||||
- Additional Parameters (based on the command):
|
||||
- **Turn:** (Optional) 'on' or 'off' - used when the command is 'turn'.
|
||||
- **Brightness:** (Optional) Numeric value (0-100) - used when the command is 'brightness'.
|
||||
- **Color:** (Optional) Object with 'r', 'g', 'b' values - used when the command is 'color'.
|
||||
- **Color Temperature:** (Optional) Numeric value for color temperature - used when the command is 'colorTem'.
|
||||
|
||||
### 2. Get Device Information
|
||||
|
||||
Retrieve information about a specific Govee device or all devices associated with your account.
|
||||
|
||||
- **Input Properties:**
|
||||
- **Device MAC Address:** (Optional) The MAC address of the specific Govee device for which information is being requested. If omitted, information for all devices is returned.
|
||||
- **Device Model:** (Optional) The model of the Govee device. If specified along with the MAC address, it refines the query to that specific device.
|
||||
|
||||
## API Documentation
|
||||
For detailed information about the Govee Lights Developer API, including its capabilities, endpoints, parameters, and responses, refer to the official [Govee API Documentation](https://govee-public.s3.amazonaws.com/developer-docs/GoveeDeveloperAPIReference.pdf). The documentation provides comprehensive guidance and examples to help you effectively integrate and utilize the API within your applications and workflows.
|
||||
|
||||
## Known Issues and Limitations
|
||||
Currently, no known issues or limitations exist. Always refer to this section for updated information.
|
||||
|
|
@ -0,0 +1,324 @@
|
|||
{
|
||||
"swagger": "2.0",
|
||||
"info": {
|
||||
"version": "1.0.0",
|
||||
"title": "Govee",
|
||||
"description": "Integrate Govee smart light devices into your applications with the Govee Developer API. Control lights, change colors, adjust brightness, and set timers. Access real-time device status for advanced application development.",
|
||||
"contact": {
|
||||
"name": "Richard Wilson",
|
||||
"email": "richard.a.wilson@microsoft.com",
|
||||
"url": "https://www.richardawilson.com/"
|
||||
}
|
||||
},
|
||||
"host": "developer-api.govee.com",
|
||||
"basePath": "/v1",
|
||||
"schemes": [
|
||||
"https"
|
||||
],
|
||||
"consumes": [
|
||||
"application/json"
|
||||
],
|
||||
"produces": [
|
||||
"application/json"
|
||||
],
|
||||
"paths": {
|
||||
"/devices/control": {
|
||||
"put": {
|
||||
"summary": "Run Command on Device",
|
||||
"description": "Execute a specific command on a Govee device. This endpoint allows you to control various aspects of the device such as power state, brightness, color, and color temperature. Provide the device's MAC address and model along with the command details. Supported commands include 'turn' for power control, 'brightness' for adjusting brightness levels, 'color' for setting RGB color values, and 'colorTem' for adjusting color temperature.",
|
||||
"operationId": "RunCommandOnDevice",
|
||||
"parameters": [
|
||||
{
|
||||
"name": "body",
|
||||
"in": "body",
|
||||
"required": true,
|
||||
"schema": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"device": {
|
||||
"type": "string",
|
||||
"title": "Device MAC Address",
|
||||
"x-ms-summary": "Device MAC Address",
|
||||
"description": "The unique MAC address of the Govee device. This identifier is used to specify which device you want to control.",
|
||||
"x-ms-visibility": "important"
|
||||
},
|
||||
"model": {
|
||||
"type": "string",
|
||||
"title": "Device Model",
|
||||
"x-ms-summary": "Device Model",
|
||||
"description": "The model number of your Govee device. This information helps in identifying the specific features and capabilities available for the device.",
|
||||
"x-ms-visibility": "important"
|
||||
},
|
||||
"cmd": {
|
||||
"type": "object",
|
||||
"description": "Command details",
|
||||
"properties": {
|
||||
"name": {
|
||||
"type": "string",
|
||||
"description": "The command to be executed on the device. This object includes the command name (e.g., 'turn', 'brightness', 'color', 'colorTem') and its associated value. The command name dictates the type of action to be performed on the device.",
|
||||
"title": "Command Name",
|
||||
"x-ms-summary": "Command Name",
|
||||
"enum": [
|
||||
"turn",
|
||||
"brightness",
|
||||
"color",
|
||||
"colorTem"
|
||||
]
|
||||
}
|
||||
},
|
||||
"required": [
|
||||
"name"
|
||||
]
|
||||
},
|
||||
"turn": {
|
||||
"title": "Turn",
|
||||
"x-ms-summary": "Turn",
|
||||
"description": "This parameter is used to turn the device on or off. Use this only when the 'turn' command is selected. Valid values are 'on' or 'off'.",
|
||||
"type": "string",
|
||||
"enum": [
|
||||
"on",
|
||||
"off"
|
||||
],
|
||||
"x-ms-visibility": "important"
|
||||
},
|
||||
"brightness": {
|
||||
"title": "Brightness",
|
||||
"x-ms-summary": "Brightness",
|
||||
"description": "The brightness level to set for the device. Use this parameter only when the 'brightness' command is selected. Enter a value between 0 (minimum brightness) and 100 (maximum brightness).",
|
||||
"type": "integer",
|
||||
"x-ms-visibility": "important"
|
||||
},
|
||||
"color": {
|
||||
"type": "object",
|
||||
"description": "The RGB color value to set for the device. Use this parameter only when the 'color' command is selected. Specify the red, green, and blue components of the color.",
|
||||
"properties": {
|
||||
"r": {
|
||||
"title": "Color - Red",
|
||||
"x-ms-summary": "Color - Red",
|
||||
"description": "This parameter represents the red component of the RGB color value for the device. It is a part of the 'color' command. Specify an integer value ranging from 0 to 255, where 0 means no red and 255 represents the maximum intensity of red.",
|
||||
"type": "integer",
|
||||
"x-ms-visibility": "important"
|
||||
},
|
||||
"g": {
|
||||
"title": "Color - Green",
|
||||
"x-ms-summary": "Color - Green",
|
||||
"description": "This parameter defines the green component of the RGB color value for the device. It is used in conjunction with the 'color' command. Provide an integer value between 0 and 255, with 0 indicating no green and 255 signifying the highest intensity of green.",
|
||||
"type": "integer",
|
||||
"x-ms-visibility": "important"
|
||||
},
|
||||
"b": {
|
||||
"title": "Color - Blue",
|
||||
"x-ms-summary": "Color - Blue",
|
||||
"description": "The blue component of the RGB color value to set on the device. This parameter is part of the 'color' command. The value should be an integer ranging from 0 to 255, where 0 is the absence of blue and 255 denotes the brightest blue.",
|
||||
"type": "integer",
|
||||
"x-ms-visibility": "important"
|
||||
}
|
||||
}
|
||||
},
|
||||
"colorTem": {
|
||||
"title": "Color Temperature",
|
||||
"x-ms-summary": "Color Temperature",
|
||||
"description": "The color temperature value to set for the device. Use this parameter only when the 'colorTem' command is selected. Enter the color temperature value as required by your device.",
|
||||
"type": "integer",
|
||||
"x-ms-visibility": "important"
|
||||
}
|
||||
},
|
||||
"required": [
|
||||
"model",
|
||||
"device",
|
||||
"cmd"
|
||||
]
|
||||
}
|
||||
}
|
||||
],
|
||||
"responses": {
|
||||
"200": {
|
||||
"description": "Successful operation",
|
||||
"schema": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"code": {
|
||||
"type": "integer",
|
||||
"format": "int32",
|
||||
"description": "The HTTP status code of the response",
|
||||
"x-ms-summary": "Status Code"
|
||||
},
|
||||
"message": {
|
||||
"type": "string",
|
||||
"description": "A message describing the result of the operation",
|
||||
"x-ms-summary": "Message"
|
||||
},
|
||||
"data": {
|
||||
"type": "object",
|
||||
"description": "The data returned with the response."
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"400": {
|
||||
"description": "Bad request"
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"/devices": {
|
||||
"get": {
|
||||
"summary": "Get Device Information",
|
||||
"description": "Access detailed information about your Govee devices. This endpoint retrieves data for a specific device when provided with its MAC address and model. If no specific device is specified, the endpoint returns information for all devices associated with your account. The response includes device details such as the device name, controllability, retrievability, supported commands, and additional properties. This is useful for understanding the capabilities and current configuration of your Govee devices.\n",
|
||||
"operationId": "GetDeviceInformation",
|
||||
"parameters": [
|
||||
{
|
||||
"name": "device",
|
||||
"in": "query",
|
||||
"required": false,
|
||||
"type": "string",
|
||||
"description": "An optional parameter representing the MAC address of the Govee device for which information is being requested. If provided, the API will return details specifically for this device. Leave this parameter empty to retrieve information for all devices associated with the account.",
|
||||
"x-ms-summary": "Device MAC Address"
|
||||
},
|
||||
{
|
||||
"name": "model",
|
||||
"in": "query",
|
||||
"required": false,
|
||||
"type": "string",
|
||||
"description": "An optional parameter indicating the model of the Govee device. If specified, the API will return information for devices matching this model. This parameter can be used in conjunction with the Device MAC Address.",
|
||||
"x-ms-summary": "Device Model"
|
||||
}
|
||||
],
|
||||
"responses": {
|
||||
"200": {
|
||||
"description": "Successful operation",
|
||||
"schema": {
|
||||
"type": "object",
|
||||
"description": "The response body contains information about the requested device(s).",
|
||||
"properties": {
|
||||
"data": {
|
||||
"type": "object",
|
||||
"description": "The data returned with the response. This includes information about the requested device(s).",
|
||||
"properties": {
|
||||
"devices": {
|
||||
"type": "array",
|
||||
"x-ms-summary": "Devices",
|
||||
"description": "A list of devices associated with the account. If a specific device is requested, the list will only contain one device.",
|
||||
"items": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"device": {
|
||||
"type": "string",
|
||||
"description": "The unique MAC address of the device",
|
||||
"x-ms-summary": "Device MAC Address"
|
||||
},
|
||||
"model": {
|
||||
"type": "string",
|
||||
"description": "The model number of the device",
|
||||
"x-ms-summary": "Device Model"
|
||||
},
|
||||
"deviceName": {
|
||||
"type": "string",
|
||||
"description": "The name of the device",
|
||||
"x-ms-summary": "Device Name"
|
||||
},
|
||||
"controllable": {
|
||||
"type": "boolean",
|
||||
"description": "Indicates if the device is controllable",
|
||||
"x-ms-summary": "Controllable"
|
||||
},
|
||||
"properties": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"colorTem": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"range": {
|
||||
"type": "object",
|
||||
"x-ms-summary": "Range",
|
||||
"description": "The range of color temperature values supported by the device",
|
||||
"properties": {
|
||||
"min": {
|
||||
"type": "integer",
|
||||
"x-ms-summary": "Minimum",
|
||||
"description": "Minimum color temperature value"
|
||||
},
|
||||
"max": {
|
||||
"type": "integer",
|
||||
"x-ms-summary": "Maximum",
|
||||
"description": "Maximum color temperature value"
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"description": "Color temperature properties of the device",
|
||||
"x-ms-summary": "Color Temperature"
|
||||
}
|
||||
},
|
||||
"description": "Additional properties of the device",
|
||||
"x-ms-summary": "Properties"
|
||||
},
|
||||
"retrievable": {
|
||||
"type": "boolean",
|
||||
"description": "Indicates if the device is retrievable",
|
||||
"x-ms-summary": "Retrievable"
|
||||
},
|
||||
"supportCmds": {
|
||||
"type": "array",
|
||||
"items": {
|
||||
"type": "string"
|
||||
},
|
||||
"description": "Supported commands for the device",
|
||||
"x-ms-summary": "Supported Commands"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"message": {
|
||||
"type": "string",
|
||||
"description": "A message describing the result of the operation",
|
||||
"x-ms-summary": "Message"
|
||||
},
|
||||
"code": {
|
||||
"type": "integer",
|
||||
"description": "The HTTP status code of the response",
|
||||
"x-ms-summary": "Status Code"
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"400": {
|
||||
"description": "Bad request"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"definitions": {},
|
||||
"parameters": {},
|
||||
"responses": {},
|
||||
"securityDefinitions": {
|
||||
"API Key": {
|
||||
"type": "apiKey",
|
||||
"in": "header",
|
||||
"name": "Govee-API-Key"
|
||||
}
|
||||
},
|
||||
"security": [
|
||||
{
|
||||
"API Key": []
|
||||
}
|
||||
],
|
||||
"tags": [],
|
||||
"x-ms-connector-metadata": [
|
||||
{
|
||||
"propertyName": "Website",
|
||||
"propertyValue": "https://us.govee.com/"
|
||||
},
|
||||
{
|
||||
"propertyName": "Privacy policy",
|
||||
"propertyValue": "https://us.govee.com/policies/privacy-policy"
|
||||
},
|
||||
{
|
||||
"propertyName": "Categories",
|
||||
"propertyValue": "Internet of Things"
|
||||
}
|
||||
]
|
||||
}
|
||||
|
|
@ -0,0 +1,26 @@
|
|||
{
|
||||
"properties": {
|
||||
"connectionParameters": {
|
||||
"api_key": {
|
||||
"type": "securestring",
|
||||
"uiDefinition": {
|
||||
"displayName": "Govee API Key",
|
||||
"description": "The Govee API Key which can be requested within the Govee mobile app.",
|
||||
"tooltip": "Provide the Govee API Key",
|
||||
"constraints": {
|
||||
"tabIndex": 2,
|
||||
"clearText": false,
|
||||
"required": "true"
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"iconBrandColor": "#da3b01",
|
||||
"scriptOperations": [
|
||||
"RunCommandOnDevice"
|
||||
],
|
||||
"capabilities": [],
|
||||
"publisher": "Richard Wilson",
|
||||
"stackOwner": "Govee"
|
||||
}
|
||||
}
|
||||
|
|
@ -0,0 +1,57 @@
|
|||
public class Script : ScriptBase
|
||||
{
|
||||
public override async Task<HttpResponseMessage> ExecuteAsync()
|
||||
{
|
||||
// Read the original request body as a string and parse it into a JObject
|
||||
string requestBodyString = await this.Context.Request.Content.ReadAsStringAsync();
|
||||
JObject originalRequestBody = JObject.Parse(requestBodyString);
|
||||
|
||||
// Determine the command type and prepare the appropriate command value
|
||||
string commandType = originalRequestBody["cmd"]?["name"]?.ToString();
|
||||
object commandValue = DetermineCommandValue(commandType, originalRequestBody);
|
||||
|
||||
if (commandValue == null)
|
||||
{
|
||||
return new HttpResponseMessage(HttpStatusCode.BadRequest)
|
||||
{
|
||||
Content = CreateJsonContent("{\"message\": \"Invalid or missing command parameters.\"}")
|
||||
};
|
||||
}
|
||||
|
||||
// Modify the request body with the determined command value
|
||||
var modifiedRequestBody = new JObject
|
||||
{
|
||||
["device"] = originalRequestBody["device"],
|
||||
["model"] = originalRequestBody["model"],
|
||||
["cmd"] = new JObject
|
||||
{
|
||||
["name"] = commandType,
|
||||
["value"] = JToken.FromObject(commandValue)
|
||||
}
|
||||
};
|
||||
|
||||
// Update the original request with the modified body
|
||||
this.Context.Request.Content = CreateJsonContent(modifiedRequestBody.ToString());
|
||||
|
||||
// Send the modified request
|
||||
var response = await this.Context.SendAsync(this.Context.Request, this.CancellationToken).ConfigureAwait(continueOnCapturedContext: false);
|
||||
return response;
|
||||
}
|
||||
|
||||
private object DetermineCommandValue(string commandType, JObject requestBody)
|
||||
{
|
||||
switch (commandType)
|
||||
{
|
||||
case "turn":
|
||||
return requestBody["turn"]?.ToString();
|
||||
case "brightness":
|
||||
return requestBody["brightness"]?.ToObject<int>();
|
||||
case "color":
|
||||
return requestBody["color"]?.ToObject<JObject>();
|
||||
case "colorTem":
|
||||
return requestBody["colorTem"]?.ToObject<int>();
|
||||
default:
|
||||
return null;
|
||||
}
|
||||
}
|
||||
}
|
||||
Загрузка…
Ссылка в новой задаче