esp32_ethernet_milight_hub/docs/openapi.yaml

1057 lines
33 KiB
YAML

openapi: 3.0.1
info:
title: ESP8266 MiLight Hub
description: Official documention for MiLight Hub's REST API.
contact:
email: chris@sidoh.org
license:
name: MIT
version: 1.0.0
servers:
- url: http://milight-hub
tags:
- name: System
description: >
Routes that return system information and allow you to control the device.
- name: Settings
description: Read and write settings
- name: Device Control
description: Control lighting devices
- name: Device Control by Alias
description: Control lighting devices using aliases rather than raw IDs
- name: Raw Packet Handling
description: Read and write raw Milight packets
- name: Transitions
description: Control transitions
x-tagGroups:
- name: Admin
tags:
- System
- Settings
- name: Devices
tags:
- Device Control
- Device Control by Alias
- Raw Packet Handling
- name: Transitions
tags:
- Transitions
paths:
/about:
get:
tags:
- System
summary: Get system information
responses:
200:
description: success
content:
application/json:
schema:
$ref: '#/components/schemas/About'
/remote_configs:
get:
tags:
- System
summary: List supported remote types
responses:
200:
description: success
content:
applicaiton/json:
schema:
type: array
items:
type: string
example:
$ref: '#/components/schemas/RemoteType/enum'
/system:
post:
tags:
- System
summary: Send a system command
description: >
Send commands to the system. Supported commands:
1. `restart`. Restart the ESP8266.
1. `clear_wifi_config`. Clears on-board wifi information. ESP8266 will reboot and enter wifi config mode.
requestBody:
content:
application/json:
schema:
type: object
required:
- command
properties:
command:
type: string
enum:
- restart
- clear_wifi_config
responses:
200:
description: command handled successfully
content:
application/json:
schema:
$ref: '#/components/schemas/BooleanResponse'
400:
description: error
content:
application/json:
schema:
$ref: '#/components/schemas/BooleanResponse'
/settings:
get:
tags:
- Settings
summary: Get existing settings
responses:
200:
description: success
content:
application/json:
schema:
$ref: '#/components/schemas/Settings'
put:
tags:
- Settings
summary: Patch existing settings
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/Settings'
responses:
200:
description: success
content:
application/json:
schema:
$ref: '#/components/schemas/BooleanResponse'
post:
tags:
- Settings
summary: Overwrite existing settings with a file
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/Settings'
responses:
200:
description: success
content:
application/json:
schema:
$ref: '#/components/schemas/BooleanResponse'
/gateway_traffic/{remote-type}:
get:
tags:
- Raw Packet Handling
summary: Read a packet from a specific remote
description:
Read a packet from the given remote type. Does not return a response until a packet is read.
If `remote-type` is unspecified, will read from all remote types simultaneously.
parameters:
- $ref: '#/components/parameters/RemoteType'
responses:
200:
description: success
content:
application/json:
schema:
$ref: '#/components/schemas/ReadPacket'
/gateway_traffic:
get:
tags:
- Raw Packet Handling
summary: Read a packet from any remote
description:
Read a packet from any remote type. Does not return a response until a packet is read.
responses:
200:
description: success
content:
application/json:
schema:
$ref: '#/components/schemas/ReadPacket'
/gateways/{device-id}/{remote-type}/{group-id}:
parameters:
- $ref: '#/components/parameters/DeviceId'
- $ref: '#/components/parameters/RemoteType'
- $ref: '#/components/parameters/GroupId'
get:
tags:
- Device Control
summary:
Get device state
description:
If `blockOnQueue` is provided, a response will not be returned until any unprocessed
packets in the command queue are finished sending.
parameters:
- $ref: '#/components/parameters/BlockOnQueue'
responses:
200:
description: success
content:
application/json:
schema:
$ref: '#/components/schemas/GroupState'
put:
tags:
- Device Control
summary:
Patch device state
description:
Update state of the bulbs with the provided parameters. Existing parameters will be
unchanged.
if `blockOnQueue` is set to true, the response will not return until packets corresponding
to the commands sent are processed, and the updated `GroupState` will be returned. If
`blockOnQueue` is false or not provided, a simple response indicating success will be
returned.
parameters:
- $ref: '#/components/parameters/BlockOnQueue'
requestBody:
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/GroupState'
- $ref: '#/components/schemas/GroupStateCommands'
responses:
400:
description: error with request
content:
application/json:
schema:
$ref: '#/components/schemas/BooleanResponse'
200:
description: >
Success.
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/BooleanResponse'
- $ref: '#/components/schemas/GroupState'
delete:
tags:
- Device Control
summary:
Delete kept state
description:
Usets all known values for state fields for the corresponding device. If MQTT is
configured, the retained state message corresponding to this device will also be
deleted.
responses:
200:
description: success
content:
application/json:
schema:
$ref: '#/components/schemas/BooleanResponse'
/gateways/{device-alias}:
parameters:
- $ref: '#/components/parameters/DeviceAlias'
get:
tags:
- Device Control by Alias
summary: Get device state by alias
responses:
404:
description: provided device alias does not exist
200:
description: success
content:
application/json:
schema:
$ref: '#/components/schemas/GroupState'
put:
tags:
- Device Control by Alias
summary: Patch device state by alias
parameters:
- $ref: '#/components/parameters/BlockOnQueue'
requestBody:
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/GroupState'
- $ref: '#/components/schemas/GroupStateCommands'
responses:
400:
description: error with request
content:
application/json:
schema:
$ref: '#/components/schemas/BooleanResponse'
200:
description: success
content:
application/json:
schema:
$ref: '#/components/schemas/GroupState'
delete:
tags:
- Device Control by Alias
summary: Delete kept state for alias
description:
Usets all known values for state fields for the corresponding device. If MQTT is
configured, the retained state message corresponding to this device will also be
deleted.
responses:
200:
description: success
content:
application/json:
schema:
$ref: '#/components/schemas/BooleanResponse'
/raw_commands/{remote-type}:
parameters:
- $ref: '#/components/parameters/RemoteType'
post:
tags:
- Raw Packet Handling
summary: Send a raw packet
requestBody:
content:
application/json:
schema:
type: object
properties:
packet:
type: string
pattern: "([A-Fa-f0-9]{2}[ ])+"
description: Raw packet to send
example: '01 02 03 04 05 06 07 08 09'
num_repeats:
type: integer
minimum: 1
description: Number of repeated packets to send
example: 50
responses:
200:
description: success
content:
applicaiton/json:
schema:
$ref: '#/components/schemas/BooleanResponse'
/transitions:
get:
tags:
- Transitions
summary: List all active transitions
responses:
200:
description: success
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/TransitionData'
post:
tags:
- Transitions
summary: Create a new transition
requestBody:
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/TransitionData'
- $ref: '#/components/schemas/BulbId'
responses:
400:
description: error
content:
application/json:
schema:
$ref: '#/components/schemas/BooleanResponse'
200:
description: success
content:
application/json:
schema:
$ref: '#/components/schemas/BooleanResponse'
/transitions/{id}:
parameters:
- name: id
in: path
description: ID of transition. This will be an auto-incrementing number reset after a restart.
schema:
type: integer
required: true
get:
tags:
- Transitions
summary: Get properties for a transition
responses:
404:
description: Provided transition ID not found
200:
description: success
content:
application/json:
schema:
$ref: '#/components/schemas/TransitionData'
delete:
tags:
- Transitions
summary: Delete a transition
responses:
404:
description: Provided transition ID not found
content:
application/json:
schema:
$ref: '#/components/schemas/BooleanResponse'
200:
description: success
content:
application/json:
schema:
$ref: '#/components/schemas/BooleanResponse'
/firmware:
post:
tags:
- System
summary:
Update firmware
requestBody:
description: Firmware file
content:
multipart/form-data:
schema:
type: object
properties:
fileName:
type: string
format: binary
responses:
200:
description: success
500:
description: server error
components:
parameters:
DeviceAlias:
name: device-alias
in: path
description: Device alias saved in settings
schema:
type: string
required: true
BlockOnQueue:
name: blockOnQueue
in: query
description: If true, response will block on update packets being sent before returning
schema:
type: boolean
required: false
GroupId:
name: group-id
in: path
description: >
Group ID. Should be 0-8, depending on remote type. Group 0 is a "wildcard" group. All bulbs paired with the same device ID will respond to commands sent to Group 0.
schema:
type: integer
minimum: 0
maximum: 8
required: true
DeviceId:
name: device-id
in: path
description: 2-byte device ID. Can be decimal or hexadecimal.
schema:
oneOf:
- type: integer
minimum: 0
maximum: 65535
- type: string
pattern: '0x[a-fA-F0-9]+'
example: '0x1234'
required: true
RemoteType:
name: remote-type
in: path
description: Type of remote to read a packet from. If unspecified, will read packets from all remote types.
schema:
$ref: '#/components/schemas/RemoteType'
required: true
schemas:
State:
description: "On/Off state"
type: string
enum:
- On
- Off
example: On
GroupStateCommand:
type: string
enum:
- unpair
- pair
- set_white
- night_mode
- level_up
- level_down
- temperature_up
- temperature_down
- next_mode
- previous_mode
- mode_speed_down
- mode_speed_up
- toggle
example: pair
description: >
Commands that affect a given group. Descriptiosn follow:
* `pair`. Emulates the pairing process. Send this command right as you connect an unpaired bulb and it will pair with the device ID being used.
* `unpair`. Emulates the unpairing process. Send as you connect a paired bulb to have it disassociate with the device ID being used.
* `set_white`. Turns off RGB and enters WW/CW mode.
* `night_mode`. Most devices support a "night mode," which has LEDs turned to a very dim setting -- lower than brightness 0.
* `level_up`. Turns down the brightness. Not all dimmable bulbs support this command.
* `level_down`. Turns down the brightness. Not all dimmable bulbs support this command.
* `temperature_up`. Turns up the white temperature. Not all bulbs with adjustable white temperature support this command.
* `temperature_down`. Turns down the white temperature. Not all bulbs with adjustable white temperature support this command.
* `next_mode`. Cycles to the next "disco mode".
* `previous_mode`. Cycles to the previous disco mode.
* `mode_speed_up`. Turn transition speed for current mode up.
* `mode_speed_down`. Turn transition speed for current mode down.
* `toggle`. Toggle on/off state.
TransitionField:
type: string
enum:
- hue
- saturation
- brightness
- level
- kelvin
- color_temp
- color
- status
example: brightness
description: >
If transitioning `status`:
* If transitioning to `OFF`, will fade to 0 brightness and then turn off.
* If transitioning to `ON`, will turn on, set brightness to 0, and fade to brightness 100.
TransitionValue:
oneOf:
- type: integer
- type: string
pattern: '[0-9]{1,3},[0-9]{1,3},[0-9]{1,3}'
description: Either an int value or a color
TransitionArgs:
type: object
properties:
field:
$ref: '#/components/schemas/TransitionField'
start_value:
$ref: '#/components/schemas/TransitionValue'
end_value:
$ref: '#/components/schemas/TransitionValue'
duration:
type: number
format: float
description: Duration of transition, measured in seconds
period:
type: integer
description: Length of time between updates in a transition, measured in milliseconds
TransitionData:
allOf:
- $ref: '#/components/schemas/TransitionArgs'
- type: object
properties:
id:
readOnly: true
type: integer
last_sent:
readOnly: true
type: integer
description: Timestamp since last update was sent.
bulb:
readOnly: true
allOf:
- $ref: '#/components/schemas/BulbId'
type:
readOnly: true
description: >
Specifies whether this is a simple field transition, or a color transition.
type: string
enum:
- field
- color
current_value:
readOnly: true
allOf:
- $ref: '#/components/schemas/TransitionValue'
end_value:
readOnly: true
allOf:
- $ref: '#/components/schemas/TransitionValue'
BulbId:
type: object
properties:
device_id:
type: integer
minimum: 0
maximum: 65536
example: 1234
group_id:
type: integer
minimum: 0
maximum: 8
example: 1
device_type:
$ref: '#/components/schemas/RemoteType'
GroupStateCommands:
type: object
properties:
command:
oneOf:
- $ref: '#/components/schemas/GroupStateCommand'
- type: object
properties:
command:
type: string
enum:
- transition
args:
$ref: '#/components/schemas/TransitionArgs'
commands:
type: array
items:
$ref: '#/components/schemas/GroupStateCommand'
example:
- level_up
- temperature_up
GroupState:
type: object
description: Group state
properties:
state:
$ref: '#/components/schemas/State'
status:
$ref: '#/components/schemas/State'
hue:
type: integer
minimum: 0
maximum: 359
description: Color hue. Will change bulb to color mode.
saturation:
type: integer
minimum: 0
maximum: 100
description: Color saturation. Will normally change bulb to color mode.
kelvin:
type: integer
minimum: 0
maximum: 100
description: White temperature. 0 is coolest, 100 is warmest.
temperature:
type: integer
minimum: 0
maximum: 100
description: Alias for `kelvin`.
color_temp:
type: integer
minimum: 153
maximum: 370
description: White temperature measured in mireds. Lower values are cooler.
mode:
type: integer
description: Party mode ID. Actual effect depends on the bulb.
color:
oneOf:
- type: string
pattern: '[0-9]{1,3},[0-9]{1,3},[0-9]{1,3}'
example: '255,255,0'
- type: object
properties:
r:
type: integer
g:
type: integer
b:
type: integer
example:
r: 255
g: 255
b: 0
example:
'255,0,255'
level:
type: integer
minimum: 0
maximum: 100
description: Brightness on a 0-100 scale.
example: 50
brightness:
type: integer
minimum: 0
maximum: 255
description: Brightness on a 0-255 scale.
example: 170
effect:
type: string
enum:
- night_mode
- white_mode
transition:
type: number
description: >
Enables a transition from current state to the provided state.
example: 2.0
RemoteType:
type: string
enum:
- "rgbw"
- "cct"
- "rgb_cct"
- "rgb"
- "fut089"
- "fut091"
- "fut020"
example: rgb_cct
RF24Channel:
type: string
enum:
- LOW
- MID
- HIGH
LedMode:
type: string
enum:
- Off
- Slow toggle
- Fast toggle
- Slow blip
- Fast blip
- Flicker
- On
GroupStateField:
type: string
enum:
- state
- status
- brightness
- level
- hue
- saturation
- color
- mode
- kelvin
- color_temp
- bulb_mode
- computed_color
- effect
- device_id
- group_id
- device_type
- oh_color
- hex_color
description: >
Defines a field which is a part of state for a particular light device. Most fields are self-explanatory, but documentation for each follows:
* `state` / `status` - same value with different keys (useful if your platform expects one or the other).
* `brightness` / `level` - [0, 255] and [0, 100] scales of the same value.
* `kelvin / color_temp` - [0, 100] and [153, 370] scales for the same value. The later's unit is mireds.
* `bulb_mode` - what mode the bulb is in: white, rgb, etc.
* `color` / `computed_color` - behaves the same when bulb is in rgb mode. `computed_color` will send RGB = 255,255,255 when in white mode. This is useful for HomeAssistant where it always expects the color to be set.
* `oh_color` - same as `color` with a format compatible with [OpenHAB's colorRGB channel type](https://www.openhab.org/addons/bindings/mqtt.generic/#channel-type-colorrgb-colorhsb).
* `hex_color` - same as `color` except in hex color (e.g., `#FF0000` for red).
* `device_id` / `device_type` / `group_id` - this information is in the MQTT topic or REST route, but can be included in the payload in the case that processing the topic or route is more difficult.
DeviceId:
type: array
items: {}
example:
- 1234
- "rgb_cct"
- 1
Settings:
type: object
properties:
admin_username:
type: string
description: If spcified along with `admin_password`, HTTP basic auth will be enabled to access all REST endpoints.
default: ""
admin_password:
type: string
description: If spcified along with `admin_username`, HTTP basic auth will be enabled to access all REST endpoints.
default: ""
ce_pin:
type: integer
description: CE pin to use for SPI radio (nRF24, LT8900)
default: 4
csn_pin:
type: integer
description: CSN pin to use with nRF24
default: 15
reset_pin:
type: integer
description: Reset pin to use with LT8900
default: 0
led_pin:
type: integer
description: Pin to control for status LED. Set to a negative value to invert on/off status.
default: -2
packet_repeats:
type: integer
description: Number of times to resend the same 2.4 GHz milight packet when a command is sent.
default: 50
http_repeat_factor:
type: integer
description: Packet repeats resulting from REST commands will be multiplied by this number.
default: 1
auto_restart_period:
type: integer
description: Automatically restart the device after the number of specified minutes. Use 0 to disable.
default: 0
mqtt_server:
type: string
description: MQTT server to connect to.
format: hostname
mqtt_username:
type: string
description: If specified, use this username to authenticate with the MQTT server.
mqtt_password:
type: string
description: If specified, use this password to authenticate with the MQTT server.
mqtt_topic_pattern:
type: string
description: Topic pattern to listen on for commands. More detail on the format in README.
example: milight/commands/:device_id/:device_type/:group_id
mqtt_update_topic_pattern:
type: string
description: Topic pattern individual intercepted commands will be sent to. More detail on the format in README.
example: milight/updates/:device_id/:device_type/:group_id
mqtt_update_state_pattern:
type: string
description: Topic pattern device state will be sent to. More detail on the format in README.
example: milight/state/:device_id/:device_type/:group_id
mqtt_client_status_topic:
type: string
description: Topic client status will be sent to.
example: milight/status
simple_mqtt_client_status:
type: boolean
description: If true, will use a simple enum flag (`connected` or `disconnected`) to indicate status. If false, will send a rich JSON message including IP address, version, etc.
default: true
discovery_port:
type: integer
description: UDP discovery port
default: 48899
listen_repeats:
type: integer
description: Controls how many cycles are spent listening for packets. Set to 0 to disable passive listening.
default: 3
state_flush_interval:
type: integer
description: Controls how many miliseconds must pass between states being flushed to persistent storage. Set to 0 to disable throttling.
default: 10000
mqtt_state_rate_limit:
type: integer
description: Controls how many miliseconds must pass between MQTT state updates. Set to 0 to disable throttling.
default: 500
mqtt_debounce_delay:
type: integer
description: Controls how much time has to pass after the last status update was queued.
default: 500
packet_repeat_throttle_threshold:
type: integer
description:
Controls how packet repeats are throttled. Packets sent with less time (measured in milliseconds) between them than this value (in milliseconds) will cause packet repeats to be throttled down. More than this value will unthrottle up.
default: 200
packet_repeat_throttle_sensitivity:
type: integer
description:
Controls how packet repeats are throttled. Higher values cause packets to be throttled up and down faster. Set to 0 to disable throttling.
default: 0
minimum: 0
maximum: 1000
packet_repeat_minimum:
type: integer
description:
Controls how far throttling can decrease the number of repeated packets
default: 3
enable_automatic_mode_switching:
type: boolean
description:
When making updates to hue or white temperature in a different bulb mode, switch back to the original bulb mode after applying the setting change.
default: false
led_mode_wifi_config:
$ref: '#/components/schemas/LedMode'
led_mode_wifi_failed:
$ref: '#/components/schemas/LedMode'
led_mode_operating:
$ref: '#/components/schemas/LedMode'
led_mode_packet:
$ref: '#/components/schemas/LedMode'
led_mode_packet_count:
type: integer
description: Number of times the LED will flash when packets are changing
default: 3
hostname:
type: string
description: Hostname that will be advertized on a DHCP request
pattern: "[a-zA-Z0-9-]+"
default: milight-hub
rf24_power_level:
type: string
enum:
- MIN
- LOW
- HIGH
- MAX
description: Power level used when packets are sent. See nRF24 documentation for further detail.
default: MAX
rf24_listen_channel:
$ref: '#/components/schemas/RF24Channel'
wifi_static_ip:
type: string
format: ipv4
description: If specified, the static IP address to use
wifi_static_ip_gateway:
type: string
format: ipv4
description: If specified along with static IP, the gateway address to use
wifi_static_ip_netmask:
type: string
format: ipv4
description: If specified along with static IP, the netmask to use
packet_repeats_per_loop:
type: integer
default: 10
description: Packets are sent asynchronously. This number controls the number of repeats sent during each iteration. Increase this number to improve packet throughput. Decrease to improve system multi-tasking.
home_assistant_discovery_prefix:
type: string
description: If specified along with MQTT settings, will enable HomeAssistant MQTT discovery using the specified discovery prefix. HomeAssistant's default is `homeassistant/`.
wifi_mode:
type: string
enum:
- B
- G
- N
description: Forces WiFi into the spcified mode. Try using B or G mode if you are having stability issues.
default: N
rf24_channels:
type: array
items:
$ref: '#/components/schemas/RF24Channel'
description: Defines which channels we send on. Each remote type has three channels. We can send on any subset of these.
device_ids:
type: array
items:
$ref: '#/components/schemas/DeviceId'
description:
"List of saved device IDs, stored as 3-long arrays. Elements are: 1) remote ID, 2) remote type, 3) group ID"
example:
- [1234, 'rgb_cct', 1]
- [5678, 'fut089', 5]
gateway_configs:
type: array
items:
type: integer
description: "List of UDP servers, stored as 3-long arrays. Elements are 1) remote ID to bind to, 2) UDP port to listen on, 3) protocol version (5 or 6)"
example:
- [1234, 5555, 6]
group_state_fields:
type: array
items:
$ref: '#/components/schemas/GroupStateField'
group_id_aliases:
type: object
description: Keys are aliases, values are 3-long arrays with same schema as items in `device_ids`.
example:
alias1: [1234, 'rgb_cct', 1]
alias2: [1234, 'rgb_cct', 2]
default_transition_period:
type: integer
description: |
Default number of milliseconds between transition packets. Set this value lower for more granular transitions, or higher if
you are having performance issues during transitions.
BooleanResponse:
type: object
required:
- success
properties:
success:
type: boolean
error:
type: string
description: If an error occurred, message specifying what went wrong
About:
type: object
properties:
firmware:
type: string
description: Always set to "milight-hub"
version:
type: string
description: Semver version string
ip_address:
type: string
reset_reason:
type: string
description: Reason the system was last rebooted
variant:
type: string
description: Firmware variant (e.g., d1_mini, nodemcuv2)
free_heap:
type: integer
format: int64
description: Amount of free heap remaining (measured in bytes)
arduino_version:
type: string
description: Version of Arduino SDK firmware was built with
queue_stats:
type: object
properties:
length:
type: integer
description: Number of enqueued packets to be sent
dropped_packets:
type: integer
description: Number of packets that have been dropped since last reboot
ReadPacket:
type: object
properties:
packet_info:
type: string