Documentation Powered by ReDoc

ESP8266 MiLight Hub (1.0.0)

Download OpenAPI specification:Download

E-mail: chris@sidoh.org License: MIT

Official documention for MiLight Hub's REST API.

System

Routes that return system information and allow you to control the device.

Get system information

Responses

200

success

get /about
http://milight-hub/about

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "firmware": "string",
  • "version": "string",
  • "ip_address": "string",
  • "reset_reason": "string",
  • "variant": "string",
  • "free_heap": 0,
  • "arduino_version": "string",
  • "queue_stats":
    {
    }
}

List supported remote types

Responses

200

success

get /remote_configs
http://milight-hub/remote_configs

Response samples

Content type
applicaiton/json
Copy
 Expand all Collapse all
{
  • "$ref": "#/components/schemas/RemoteType/enum"
}

Send a system command

Send commands to the system. Supported commands:

  1. restart. Restart the ESP8266.
  2. clear_wifi_config. Clears on-board wifi information. ESP8266 will reboot and enter wifi config mode.
Request Body schema: application/json
command
required
string
Enum: "restart" "clear_wifi_config"

Responses

200

command handled successfully

400

error

post /system
http://milight-hub/system

Request samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "command": "restart"
}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "success": true,
  • "error": "string"
}

Update firmware

Request Body schema: multipart/form-data

Firmware file

fileName
string <binary>

Responses

200

success

500

server error

post /firmware
http://milight-hub/firmware

Settings

Read and write settings

Get existing settings

Responses

200

success

get /settings
http://milight-hub/settings

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "admin_username": "",
  • "admin_password": "",
  • "ce_pin": 4,
  • "csn_pin": 15,
  • "reset_pin": 0,
  • "led_pin": -2,
  • "packet_repeats": 50,
  • "http_repeat_factor": 1,
  • "auto_restart_period": 0,
  • "mqtt_server": "example.com",
  • "mqtt_username": "string",
  • "mqtt_password": "string",
  • "mqtt_topic_pattern": "milight/commands/:device_id/:device_type/:group_id",
  • "mqtt_update_topic_pattern": "milight/updates/:device_id/:device_type/:group_id",
  • "mqtt_update_state_pattern": "milight/state/:device_id/:device_type/:group_id",
  • "mqtt_client_status_topic": "milight/status",
  • "simple_mqtt_client_status": true,
  • "discovery_port": 48899,
  • "listen_repeats": 3,
  • "state_flush_interval": 10000,
  • "mqtt_state_rate_limit": 500,
  • "mqtt_debounce_delay": 500,
  • "packet_repeat_throttle_threshold": 200,
  • "packet_repeat_throttle_sensitivity": 0,
  • "packet_repeat_minimum": 3,
  • "enable_automatic_mode_switching": false,
  • "led_mode_wifi_config": "Off",
  • "led_mode_wifi_failed": "Off",
  • "led_mode_operating": "Off",
  • "led_mode_packet": "Off",
  • "led_mode_packet_count": 3,
  • "hostname": "milight-hub",
  • "rf24_power_level": "MAX",
  • "rf24_listen_channel": "LOW",
  • "wifi_static_ip": "192.168.0.1",
  • "wifi_static_ip_gateway": "192.168.0.1",
  • "wifi_static_ip_netmask": "192.168.0.1",
  • "packet_repeats_per_loop": 10,
  • "home_assistant_discovery_prefix": "string",
  • "wifi_mode": "N",
  • "rf24_channels":
    [
    ],
  • "device_ids":
    [
    ],
  • "gateway_configs":
    [
    ],
  • "group_state_fields":
    [
    ],
  • "group_id_aliases":
    {
    },
  • "default_transition_period": 0
}

Patch existing settings

Request Body schema: application/json
admin_username
string
Default: ""

If spcified along with admin_password, HTTP basic auth will be enabled to access all REST endpoints.

admin_password
string
Default: ""

If spcified along with admin_username, HTTP basic auth will be enabled to access all REST endpoints.

ce_pin
integer
Default: 4

CE pin to use for SPI radio (nRF24, LT8900)

csn_pin
integer
Default: 15

CSN pin to use with nRF24

reset_pin
integer
Default: 0

Reset pin to use with LT8900

led_pin
integer
Default: -2

Pin to control for status LED. Set to a negative value to invert on/off status.

packet_repeats
integer
Default: 50

Number of times to resend the same 2.4 GHz milight packet when a command is sent.

http_repeat_factor
integer
Default: 1

Packet repeats resulting from REST commands will be multiplied by this number.

auto_restart_period
integer
Default: 0

Automatically restart the device after the number of specified minutes. Use 0 to disable.

mqtt_server
string <hostname>

MQTT server to connect to.

mqtt_username
string

If specified, use this username to authenticate with the MQTT server.

mqtt_password
string

If specified, use this password to authenticate with the MQTT server.

mqtt_topic_pattern
string

Topic pattern to listen on for commands. More detail on the format in README.

mqtt_update_topic_pattern
string

Topic pattern individual intercepted commands will be sent to. More detail on the format in README.

mqtt_update_state_pattern
string

Topic pattern device state will be sent to. More detail on the format in README.

mqtt_client_status_topic
string

Topic client status will be sent to.

simple_mqtt_client_status
boolean
Default: true

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.

discovery_port
integer
Default: 48899

UDP discovery port

listen_repeats
integer
Default: 3

Controls how many cycles are spent listening for packets. Set to 0 to disable passive listening.

state_flush_interval
integer
Default: 10000

Controls how many miliseconds must pass between states being flushed to persistent storage. Set to 0 to disable throttling.

mqtt_state_rate_limit
integer
Default: 500

Controls how many miliseconds must pass between MQTT state updates. Set to 0 to disable throttling.

mqtt_debounce_delay
integer
Default: 500

Controls how much time has to pass after the last status update was queued.

packet_repeat_throttle_threshold
integer
Default: 200

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.

packet_repeat_throttle_sensitivity
integer [ 0 .. 1000 ]
Default: 0

Controls how packet repeats are throttled. Higher values cause packets to be throttled up and down faster. Set to 0 to disable throttling.

packet_repeat_minimum
integer
Default: 3

Controls how far throttling can decrease the number of repeated packets

enable_automatic_mode_switching
boolean
Default: false

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.

led_mode_wifi_config
string (LedMode)
Enum: "Off" "Slow toggle" "Fast toggle" "Slow blip" "Fast blip" "Flicker" "On"
led_mode_wifi_failed
string (LedMode)
Enum: "Off" "Slow toggle" "Fast toggle" "Slow blip" "Fast blip" "Flicker" "On"
led_mode_operating
string (LedMode)
Enum: "Off" "Slow toggle" "Fast toggle" "Slow blip" "Fast blip" "Flicker" "On"
led_mode_packet
string (LedMode)
Enum: "Off" "Slow toggle" "Fast toggle" "Slow blip" "Fast blip" "Flicker" "On"
led_mode_packet_count
integer
Default: 3

Number of times the LED will flash when packets are changing

hostname
string [a-zA-Z0-9-]+
Default: "milight-hub"

Hostname that will be advertized on a DHCP request

rf24_power_level
string
Default: "MAX"
Enum: "MIN" "LOW" "HIGH" "MAX"

Power level used when packets are sent. See nRF24 documentation for further detail.

rf24_listen_channel
string (RF24Channel)
Enum: "LOW" "MID" "HIGH"
wifi_static_ip
string <ipv4>

If specified, the static IP address to use

wifi_static_ip_gateway
string <ipv4>

If specified along with static IP, the gateway address to use

wifi_static_ip_netmask
string <ipv4>

If specified along with static IP, the netmask to use

packet_repeats_per_loop
integer
Default: 10

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
string

If specified along with MQTT settings, will enable HomeAssistant MQTT discovery using the specified discovery prefix. HomeAssistant's default is homeassistant/.

wifi_mode
string
Default: "N"
Enum: "B" "G" "N"

Forces WiFi into the spcified mode. Try using B or G mode if you are having stability issues.

rf24_channels
Array of strings (RF24Channel)
Items Enum: "LOW" "MID" "HIGH"

Defines which channels we send on. Each remote type has three channels. We can send on any subset of these.

device_ids
Array of Array of any (DeviceId)

List of saved device IDs, stored as 3-long arrays. Elements are: 1) remote ID, 2) remote type, 3) group ID

gateway_configs
Array of integers

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)

group_state_fields
Array of strings (GroupStateField)
Items 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"
group_id_aliases
object

Keys are aliases, values are 3-long arrays with same schema as items in device_ids.

default_transition_period
integer

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.

Responses

200

success

put /settings
http://milight-hub/settings

Request samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "admin_username": "",
  • "admin_password": "",
  • "ce_pin": 4,
  • "csn_pin": 15,
  • "reset_pin": 0,
  • "led_pin": -2,
  • "packet_repeats": 50,
  • "http_repeat_factor": 1,
  • "auto_restart_period": 0,
  • "mqtt_server": "example.com",
  • "mqtt_username": "string",
  • "mqtt_password": "string",
  • "mqtt_topic_pattern": "milight/commands/:device_id/:device_type/:group_id",
  • "mqtt_update_topic_pattern": "milight/updates/:device_id/:device_type/:group_id",
  • "mqtt_update_state_pattern": "milight/state/:device_id/:device_type/:group_id",
  • "mqtt_client_status_topic": "milight/status",
  • "simple_mqtt_client_status": true,
  • "discovery_port": 48899,
  • "listen_repeats": 3,
  • "state_flush_interval": 10000,
  • "mqtt_state_rate_limit": 500,
  • "mqtt_debounce_delay": 500,
  • "packet_repeat_throttle_threshold": 200,
  • "packet_repeat_throttle_sensitivity": 0,
  • "packet_repeat_minimum": 3,
  • "enable_automatic_mode_switching": false,
  • "led_mode_wifi_config": "Off",
  • "led_mode_wifi_failed": "Off",
  • "led_mode_operating": "Off",
  • "led_mode_packet": "Off",
  • "led_mode_packet_count": 3,
  • "hostname": "milight-hub",
  • "rf24_power_level": "MAX",
  • "rf24_listen_channel": "LOW",
  • "wifi_static_ip": "192.168.0.1",
  • "wifi_static_ip_gateway": "192.168.0.1",
  • "wifi_static_ip_netmask": "192.168.0.1",
  • "packet_repeats_per_loop": 10,
  • "home_assistant_discovery_prefix": "string",
  • "wifi_mode": "N",
  • "rf24_channels":
    [
    ],
  • "device_ids":
    [
    ],
  • "gateway_configs":
    [
    ],
  • "group_state_fields":
    [
    ],
  • "group_id_aliases":
    {
    },
  • "default_transition_period": 0
}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "success": true,
  • "error": "string"
}

Overwrite existing settings with a file

Request Body schema: application/json
admin_username
string
Default: ""

If spcified along with admin_password, HTTP basic auth will be enabled to access all REST endpoints.

admin_password
string
Default: ""

If spcified along with admin_username, HTTP basic auth will be enabled to access all REST endpoints.

ce_pin
integer
Default: 4

CE pin to use for SPI radio (nRF24, LT8900)

csn_pin
integer
Default: 15

CSN pin to use with nRF24

reset_pin
integer
Default: 0

Reset pin to use with LT8900

led_pin
integer
Default: -2

Pin to control for status LED. Set to a negative value to invert on/off status.

packet_repeats
integer
Default: 50

Number of times to resend the same 2.4 GHz milight packet when a command is sent.

http_repeat_factor
integer
Default: 1

Packet repeats resulting from REST commands will be multiplied by this number.

auto_restart_period
integer
Default: 0

Automatically restart the device after the number of specified minutes. Use 0 to disable.

mqtt_server
string <hostname>

MQTT server to connect to.

mqtt_username
string

If specified, use this username to authenticate with the MQTT server.

mqtt_password
string

If specified, use this password to authenticate with the MQTT server.

mqtt_topic_pattern
string

Topic pattern to listen on for commands. More detail on the format in README.

mqtt_update_topic_pattern
string

Topic pattern individual intercepted commands will be sent to. More detail on the format in README.

mqtt_update_state_pattern
string

Topic pattern device state will be sent to. More detail on the format in README.

mqtt_client_status_topic
string

Topic client status will be sent to.

simple_mqtt_client_status
boolean
Default: true

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.

discovery_port
integer
Default: 48899

UDP discovery port

listen_repeats
integer
Default: 3

Controls how many cycles are spent listening for packets. Set to 0 to disable passive listening.

state_flush_interval
integer
Default: 10000

Controls how many miliseconds must pass between states being flushed to persistent storage. Set to 0 to disable throttling.

mqtt_state_rate_limit
integer
Default: 500

Controls how many miliseconds must pass between MQTT state updates. Set to 0 to disable throttling.

mqtt_debounce_delay
integer
Default: 500

Controls how much time has to pass after the last status update was queued.

packet_repeat_throttle_threshold
integer
Default: 200

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.

packet_repeat_throttle_sensitivity
integer [ 0 .. 1000 ]
Default: 0

Controls how packet repeats are throttled. Higher values cause packets to be throttled up and down faster. Set to 0 to disable throttling.

packet_repeat_minimum
integer
Default: 3

Controls how far throttling can decrease the number of repeated packets

enable_automatic_mode_switching
boolean
Default: false

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.

led_mode_wifi_config
string (LedMode)
Enum: "Off" "Slow toggle" "Fast toggle" "Slow blip" "Fast blip" "Flicker" "On"
led_mode_wifi_failed
string (LedMode)
Enum: "Off" "Slow toggle" "Fast toggle" "Slow blip" "Fast blip" "Flicker" "On"
led_mode_operating
string (LedMode)
Enum: "Off" "Slow toggle" "Fast toggle" "Slow blip" "Fast blip" "Flicker" "On"
led_mode_packet
string (LedMode)
Enum: "Off" "Slow toggle" "Fast toggle" "Slow blip" "Fast blip" "Flicker" "On"
led_mode_packet_count
integer
Default: 3

Number of times the LED will flash when packets are changing

hostname
string [a-zA-Z0-9-]+
Default: "milight-hub"

Hostname that will be advertized on a DHCP request

rf24_power_level
string
Default: "MAX"
Enum: "MIN" "LOW" "HIGH" "MAX"

Power level used when packets are sent. See nRF24 documentation for further detail.

rf24_listen_channel
string (RF24Channel)
Enum: "LOW" "MID" "HIGH"
wifi_static_ip
string <ipv4>

If specified, the static IP address to use

wifi_static_ip_gateway
string <ipv4>

If specified along with static IP, the gateway address to use

wifi_static_ip_netmask
string <ipv4>

If specified along with static IP, the netmask to use

packet_repeats_per_loop
integer
Default: 10

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
string

If specified along with MQTT settings, will enable HomeAssistant MQTT discovery using the specified discovery prefix. HomeAssistant's default is homeassistant/.

wifi_mode
string
Default: "N"
Enum: "B" "G" "N"

Forces WiFi into the spcified mode. Try using B or G mode if you are having stability issues.

rf24_channels
Array of strings (RF24Channel)
Items Enum: "LOW" "MID" "HIGH"

Defines which channels we send on. Each remote type has three channels. We can send on any subset of these.

device_ids
Array of Array of any (DeviceId)

List of saved device IDs, stored as 3-long arrays. Elements are: 1) remote ID, 2) remote type, 3) group ID

gateway_configs
Array of integers

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)

group_state_fields
Array of strings (GroupStateField)
Items 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"
group_id_aliases
object

Keys are aliases, values are 3-long arrays with same schema as items in device_ids.

default_transition_period
integer

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.

Responses

200

success

post /settings
http://milight-hub/settings

Request samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "admin_username": "",
  • "admin_password": "",
  • "ce_pin": 4,
  • "csn_pin": 15,
  • "reset_pin": 0,
  • "led_pin": -2,
  • "packet_repeats": 50,
  • "http_repeat_factor": 1,
  • "auto_restart_period": 0,
  • "mqtt_server": "example.com",
  • "mqtt_username": "string",
  • "mqtt_password": "string",
  • "mqtt_topic_pattern": "milight/commands/:device_id/:device_type/:group_id",
  • "mqtt_update_topic_pattern": "milight/updates/:device_id/:device_type/:group_id",
  • "mqtt_update_state_pattern": "milight/state/:device_id/:device_type/:group_id",
  • "mqtt_client_status_topic": "milight/status",
  • "simple_mqtt_client_status": true,
  • "discovery_port": 48899,
  • "listen_repeats": 3,
  • "state_flush_interval": 10000,
  • "mqtt_state_rate_limit": 500,
  • "mqtt_debounce_delay": 500,
  • "packet_repeat_throttle_threshold": 200,
  • "packet_repeat_throttle_sensitivity": 0,
  • "packet_repeat_minimum": 3,
  • "enable_automatic_mode_switching": false,
  • "led_mode_wifi_config": "Off",
  • "led_mode_wifi_failed": "Off",
  • "led_mode_operating": "Off",
  • "led_mode_packet": "Off",
  • "led_mode_packet_count": 3,
  • "hostname": "milight-hub",
  • "rf24_power_level": "MAX",
  • "rf24_listen_channel": "LOW",
  • "wifi_static_ip": "192.168.0.1",
  • "wifi_static_ip_gateway": "192.168.0.1",
  • "wifi_static_ip_netmask": "192.168.0.1",
  • "packet_repeats_per_loop": 10,
  • "home_assistant_discovery_prefix": "string",
  • "wifi_mode": "N",
  • "rf24_channels":
    [
    ],
  • "device_ids":
    [
    ],
  • "gateway_configs":
    [
    ],
  • "group_state_fields":
    [
    ],
  • "group_id_aliases":
    {
    },
  • "default_transition_period": 0
}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "success": true,
  • "error": "string"
}

Device Control

Control lighting devices

Get device state

If blockOnQueue is provided, a response will not be returned until any unprocessed packets in the command queue are finished sending.

path Parameters
device-id
required
integer or string
Example: 0x1234

2-byte device ID. Can be decimal or hexadecimal.

remote-type
required
string (RemoteType)
Enum: "rgbw" "cct" "rgb_cct" "rgb" "fut089" "fut091" "fut020"
Example: rgb_cct

Type of remote to read a packet from. If unspecified, will read packets from all remote types.

group-id
required
integer [ 0 .. 8 ]

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.

query Parameters
blockOnQueue
boolean

If true, response will block on update packets being sent before returning

Responses

200

success

get /gateways/{device-id}/{remote-type}/{group-id}
http://milight-hub/gateways/{device-id}/{remote-type}/{group-id}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "state": "On",
  • "status": "On",
  • "hue": 0,
  • "saturation": 0,
  • "kelvin": 0,
  • "temperature": 0,
  • "color_temp": 153,
  • "mode": 0,
  • "color": "255,0,255",
  • "level": 50,
  • "brightness": 170,
  • "effect": "night_mode",
  • "transition": 2
}

Patch device state

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.

path Parameters
device-id
required
integer or string
Example: 0x1234

2-byte device ID. Can be decimal or hexadecimal.

remote-type
required
string (RemoteType)
Enum: "rgbw" "cct" "rgb_cct" "rgb" "fut089" "fut091" "fut020"
Example: rgb_cct

Type of remote to read a packet from. If unspecified, will read packets from all remote types.

group-id
required
integer [ 0 .. 8 ]

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.

query Parameters
blockOnQueue
boolean

If true, response will block on update packets being sent before returning

Request Body schema: application/json
state
string (State)
Enum: "On" "Off"

On/Off state

status
string (State)
Enum: "On" "Off"

On/Off state

hue
integer [ 0 .. 359 ]

Color hue. Will change bulb to color mode.

saturation
integer [ 0 .. 100 ]

Color saturation. Will normally change bulb to color mode.

kelvin
integer [ 0 .. 100 ]

White temperature. 0 is coolest, 100 is warmest.

temperature
integer [ 0 .. 100 ]

Alias for kelvin.

color_temp
integer [ 153 .. 370 ]

White temperature measured in mireds. Lower values are cooler.

mode
integer

Party mode ID. Actual effect depends on the bulb.

color
string or object
level
integer [ 0 .. 100 ]

Brightness on a 0-100 scale.

brightness
integer [ 0 .. 255 ]

Brightness on a 0-255 scale.

effect
string
Enum: "night_mode" "white_mode"
transition
number

Enables a transition from current state to the provided state.

command
GroupStateCommand (string) or object
commands
Array of strings (GroupStateCommand)
Items 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"

Responses

200

Success.

400

error with request

put /gateways/{device-id}/{remote-type}/{group-id}
http://milight-hub/gateways/{device-id}/{remote-type}/{group-id}

Request samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "state": "On",
  • "status": "On",
  • "hue": 0,
  • "saturation": 0,
  • "kelvin": 0,
  • "temperature": 0,
  • "color_temp": 153,
  • "mode": 0,
  • "color": "255,0,255",
  • "level": 50,
  • "brightness": 170,
  • "effect": "night_mode",
  • "transition": 2,
  • "command": "pair",
  • "commands":
    [
    ]
}

Response samples

Content type
application/json
Example
BooleanResponse
Copy
 Expand all Collapse all
{
  • "success": true,
  • "error": "string"
}

Delete kept state

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.

path Parameters
device-id
required
integer or string
Example: 0x1234

2-byte device ID. Can be decimal or hexadecimal.

remote-type
required
string (RemoteType)
Enum: "rgbw" "cct" "rgb_cct" "rgb" "fut089" "fut091" "fut020"
Example: rgb_cct

Type of remote to read a packet from. If unspecified, will read packets from all remote types.

group-id
required
integer [ 0 .. 8 ]

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.

Responses

200

success

delete /gateways/{device-id}/{remote-type}/{group-id}
http://milight-hub/gateways/{device-id}/{remote-type}/{group-id}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "success": true,
  • "error": "string"
}

Device Control by Alias

Control lighting devices using aliases rather than raw IDs

Get device state by alias

path Parameters
device-alias
required
string

Device alias saved in settings

Responses

200

success

404

provided device alias does not exist

get /gateways/{device-alias}
http://milight-hub/gateways/{device-alias}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "state": "On",
  • "status": "On",
  • "hue": 0,
  • "saturation": 0,
  • "kelvin": 0,
  • "temperature": 0,
  • "color_temp": 153,
  • "mode": 0,
  • "color": "255,0,255",
  • "level": 50,
  • "brightness": 170,
  • "effect": "night_mode",
  • "transition": 2
}

Patch device state by alias

path Parameters
device-alias
required
string

Device alias saved in settings

query Parameters
blockOnQueue
boolean

If true, response will block on update packets being sent before returning

Request Body schema: application/json
state
string (State)
Enum: "On" "Off"

On/Off state

status
string (State)
Enum: "On" "Off"

On/Off state

hue
integer [ 0 .. 359 ]

Color hue. Will change bulb to color mode.

saturation
integer [ 0 .. 100 ]

Color saturation. Will normally change bulb to color mode.

kelvin
integer [ 0 .. 100 ]

White temperature. 0 is coolest, 100 is warmest.

temperature
integer [ 0 .. 100 ]

Alias for kelvin.

color_temp
integer [ 153 .. 370 ]

White temperature measured in mireds. Lower values are cooler.

mode
integer

Party mode ID. Actual effect depends on the bulb.

color
string or object
level
integer [ 0 .. 100 ]

Brightness on a 0-100 scale.

brightness
integer [ 0 .. 255 ]

Brightness on a 0-255 scale.

effect
string
Enum: "night_mode" "white_mode"
transition
number

Enables a transition from current state to the provided state.

command
GroupStateCommand (string) or object
commands
Array of strings (GroupStateCommand)
Items 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"

Responses

200

success

400

error with request

put /gateways/{device-alias}
http://milight-hub/gateways/{device-alias}

Request samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "state": "On",
  • "status": "On",
  • "hue": 0,
  • "saturation": 0,
  • "kelvin": 0,
  • "temperature": 0,
  • "color_temp": 153,
  • "mode": 0,
  • "color": "255,0,255",
  • "level": 50,
  • "brightness": 170,
  • "effect": "night_mode",
  • "transition": 2,
  • "command": "pair",
  • "commands":
    [
    ]
}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "state": "On",
  • "status": "On",
  • "hue": 0,
  • "saturation": 0,
  • "kelvin": 0,
  • "temperature": 0,
  • "color_temp": 153,
  • "mode": 0,
  • "color": "255,0,255",
  • "level": 50,
  • "brightness": 170,
  • "effect": "night_mode",
  • "transition": 2
}

Delete kept state for alias

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.

path Parameters
device-alias
required
string

Device alias saved in settings

Responses

200

success

delete /gateways/{device-alias}
http://milight-hub/gateways/{device-alias}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "success": true,
  • "error": "string"
}

Raw Packet Handling

Read and write raw Milight packets

Read a packet from a specific remote

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.

path Parameters
remote-type
required
string (RemoteType)
Enum: "rgbw" "cct" "rgb_cct" "rgb" "fut089" "fut091" "fut020"
Example: rgb_cct

Type of remote to read a packet from. If unspecified, will read packets from all remote types.

Responses

200

success

get /gateway_traffic/{remote-type}
http://milight-hub/gateway_traffic/{remote-type}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "packet_info": "string"
}

Read a packet from any remote

Read a packet from any remote type. Does not return a response until a packet is read.

Responses

200

success

get /gateway_traffic
http://milight-hub/gateway_traffic

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "packet_info": "string"
}

Send a raw packet

path Parameters
remote-type
required
string (RemoteType)
Enum: "rgbw" "cct" "rgb_cct" "rgb" "fut089" "fut091" "fut020"
Example: rgb_cct

Type of remote to read a packet from. If unspecified, will read packets from all remote types.

Request Body schema: application/json
packet
string ([A-Fa-f0-9]{2}[ ])+

Raw packet to send

num_repeats
integer >= 1

Number of repeated packets to send

Responses

200

success

post /raw_commands/{remote-type}
http://milight-hub/raw_commands/{remote-type}

Request samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "packet": "01 02 03 04 05 06 07 08 09",
  • "num_repeats": 50
}

Response samples

Content type
applicaiton/json
Copy
 Expand all Collapse all
{
  • "success": true,
  • "error": "string"
}

Transitions

Control transitions

List all active transitions

Responses

200

success

get /transitions
http://milight-hub/transitions

Response samples

Content type
application/json
Copy
 Expand all Collapse all
[
  • {
    }
]

Create a new transition

Request Body schema: application/json
field
string (TransitionField)
Enum: "hue" "saturation" "brightness" "level" "kelvin" "color_temp" "color" "status"

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.
start_value
any (TransitionValue) Recursive

Either an int value or a color

duration
number <float>

Duration of transition, measured in seconds

period
integer

Length of time between updates in a transition, measured in milliseconds

device_id
integer [ 0 .. 65536 ]
group_id
integer [ 0 .. 8 ]
device_type
string (RemoteType)
Enum: "rgbw" "cct" "rgb_cct" "rgb" "fut089" "fut091" "fut020"

Responses

200

success

400

error

post /transitions
http://milight-hub/transitions

Request samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "field": "brightness",
  • "start_value": 0,
  • "end_value": 0,
  • "duration": 0,
  • "period": 0,
  • "device_id": 1234,
  • "group_id": 1,
  • "device_type": "rgb_cct"
}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "success": true,
  • "error": "string"
}

Get properties for a transition

path Parameters
id
required
integer

ID of transition. This will be an auto-incrementing number reset after a restart.

Responses

200

success

404

Provided transition ID not found

get /transitions/{id}
http://milight-hub/transitions/{id}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "field": "brightness",
  • "start_value": 0,
  • "end_value": 0,
  • "duration": 0,
  • "period": 0,
  • "id": 0,
  • "last_sent": 0,
  • "bulb":
    {
    },
  • "type": "field",
  • "current_value": 0
}

Delete a transition

path Parameters
id
required
integer

ID of transition. This will be an auto-incrementing number reset after a restart.

Responses

200

success

404

Provided transition ID not found

delete /transitions/{id}
http://milight-hub/transitions/{id}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "success": true,
  • "error": "string"
}