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

Response samples

Content type
application/json
{
  • "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

Response samples

Content type
applicaiton/json
{
  • "$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

Request samples

Content type
application/json
{
  • "command": "restart"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "error": "string"
}

Update firmware

Request Body schema: multipart/form-data

Firmware file

fileName
string <binary>

Responses

Settings

Read and write settings

Get existing settings

Responses

Response samples

Content type
application/json
{
  • "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