Hue (Hue v0.2.0)

Copy Markdown View Source

A client for the local CLIP v2 API on Philips Hue bridges.

Getting an application key

Press the round link button on the bridge, then call Hue.Pairing.pair/2 within thirty seconds. Without a key every request fails with %Hue.Error{reason: :unauthorized} — and note the bridge answers that case with an HTML page rather than JSON.

Scope

This module and everything under it is a stateless protocol client. It starts no processes and holds no state between calls.

Summary

Functions

from_bridge(bridge, options \\ [])

Builds a client from a bridge found by Hue.Discovery.discover/1, carrying its id, port, and pinned fingerprint across automatically.

new(host, options \\ [])

Builds a client for the bridge at host.

Functions

from_bridge(bridge, options \\ [])

@spec from_bridge(
  Hue.Bridge.Info.t(),
  keyword()
) :: {:ok, Hue.Client.t()}

Builds a client from a bridge found by Hue.Discovery.discover/1, carrying its id, port, and pinned fingerprint across automatically.

The bridge's fingerprint is the pinned, trusted one, so a :fingerprint option that disagrees with it raises rather than quietly winning. Re-pin by updating the Hue.Bridge.Info. Disagreement is judged on the normalised fingerprints, so restating the pin in a different letter case or with : separators is not a disagreement.

new(host, options \\ [])

@spec new(
  String.t(),
  keyword()
) :: {:ok, Hue.Client.t()}

Builds a client for the bridge at host.

Options

  • :application_key — required for every request except /api/config.
  • :fingerprint — the bridge's pinned certificate fingerprint, in any form Hue.Transport.normalize_fingerprint/1 accepts, including the colon-separated uppercase one openssl prints. Without it, TLS verification is disabled; see Hue.Transport.
  • :verify — :none to disable verification explicitly.
  • :port — a positive integer, defaults to 443.

Any other option goes to Req.new/1, including :connect_options — with the exception of its :transport_opts, which this library owns and which :fingerprint and :verify are the way to configure.

Raises ArgumentError rather than returning an error for a TLS configuration it cannot honour: in a library whose job is to verify, a rejected option must not be mistakable for one that was applied.