philips-hue.lua

Contents

• Functions
• Fields

Modules

• philips-hue

Topics

• 1. Dealing with events and state
• CHANGELOG
• LICENSE

Examples

• dump.lua

Module philips-hue

Module to interact with the Philips Hue api.

This module will connect and stream events to enable real-time updates. See dealing with events and state.

This requires the Copas scheduler.

Info:

• Copyright: Copyright (c) 2022-2022 Thijs Schreijer
• License: MIT, see LICENSE.
• Author: Thijs Schreijer

Functions

Hue.new (opts)	Creates a new Hue client instance.
Hue:request (rel_path[, method="GET"[, headers[, query[, body]]]])	Performs a HTTP request on the Hue API.
Hue:start ()	Starts the client.
Hue:stop ()	Stops the client.

Fields

Hue.log	Logger is set on the module table, to be able to override it.
Hue.state	Current connection state of the client (read-only).
Hue.states	Constants to match hue.state (read-only).

Functions

Hue.new (opts)

Creates a new Hue client instance.

Parameters:

• opts options table supporting the following fields:
  • apikey string The api-key to use for access (previously Hue called this 'username')
  • address string IP address of the bridge, if omitted will be discovered automatically (discovery will only work if there is exactly 1 bridge) (optional)
  • callback function callback receiving events
  • sse_event_timout numer or nil timeout (seconds idle) for reconnecting to SSE stream. Default 90 seconds; Home Assistant assures events every 60 seconds)
  • log logger LuaLogging compatible logger, defaults to the one on the module table if omitted. (optional)

Returns:

Hue client object

Hue:request (rel_path[, method="GET"[, headers[, query[, body]]]])

Performs a HTTP request on the Hue API. Low level method to interact with the Hue bridge.
NOTE: if the response_body is json, then it will be decoded and returned as a Lua table.

Parameters:

• rel_path string the relative path within the API base path (starts with '/')
• method string HTTP method to use (default "GET")
• headers table header table (optional)
• query table query parameters (will be escaped) (optional)
• body table or string if set the "Content-Length" will be added to the headers. If a table, it will be send as JSON, and the "Content-Type" header will be set to "application/json". (optional)

Returns:

ok, response_body, response_code, response_headers, response_status_line

Hue:start ()

Starts the client. Collects resource data and starts listening to the event-stream for updates.

Hue:stop ()

Stops the client. Closes the open connections.

Fields

Hue.log

Logger is set on the module table, to be able to override it. Default is the LuaLogging default logger (if loaded), or a no-op function. Per client overrides can be given in Hue.new.

Hue.state

Current connection state of the client (read-only). See Hue.states.

Hue.states

Constants to match hue.state (read-only). Eg:

if hue.state == Hue.states.CONNECTING then ...

Values are; INITIALIZING, CONNECTING, OPEN, CLOSED.