Module millheat
Millheat API library for Millheat electrical heaters.
This library implements the session management and makes it easy to access individual endpoints of the API.
API documentation: https://api.millheat.com/share/apidocument.
Usage:
local millheat = require "millheat" local mhsession = millheat.new("abcdef", "xyz", "myself@nothere.com", "secret_password") local home_list, err = mhsession:get_homes() -- or using the Copas scheduler local copas = require "copas" copas.addthread(function() local millheat = require "millheat" local mhsession = millheat.new("abcdef", "xyz", "myself@nothere.com", "secret_password") local home_list, err = mhsession:get_homes() end) copas.loop()
Info:
- Copyright: 2020-2022 Thijs Schreijer
- Release: Version 0.1, Library to access the Millheat API
- License: millheat.lua is free software under the MIT/X11 license.
- Author: Thijs Schreijer
Generic functions
login () | Logs in the current session. |
logout (clear) | Logs out of the current session. |
new (access_key, secret_token, username, password) | Creates a new Millheat session instance. |
request (path[, query]) | Performs a HTTP request on the Millheat API. |
rewrite_error ([expected], ...) | Rewrite errors to Lua format (nil+error). |
API specific functions
control_device (device_id, operation, status, temperature) | Controls a specific device. |
get_device (device_id) | Gets the device data. |
get_devices_by_room (room_id) | Gets the list of devices associated with a room. |
get_homes () | Gets the list of homes. |
get_independent_devices_by_home (home_id) | Gets the list of independent devices not associated with a room. |
get_rooms_by_home (home_id) | Gets the list of rooms associated with a home. |
Generic functions
Functions for session management and instantiation
- login ()
-
Logs in the current session.
This will automatically be called by the request method, if not logged in
already.
Returns:
true
ornil+err
Usage:
local millheat = require "millheat" local mhsession = millheat.new("abcdef", "xyz", "myself@nothere.com", "secret_password") local ok, err = mhsession:login() if not ok then print("failed to login: ", err) end
- logout (clear)
-
Logs out of the current session.
There is no real logout option with this API. Hence this only deletes
the locally stored tokens.
Parameters:
- clear bool if truthy, the current session is removed from the session cache, and the next call to millheat.new will create a new session instead of reusing the cached one.
Returns:
true
Usage:
local millheat = require "millheat" local mhsession = millheat.new("abcdef", "xyz", "myself@nothere.com", "secret_password") local ok, err = mhsession:login() if not ok then print("failed to login: ", err) else mhsession:logout() end
- new (access_key, secret_token, username, password)
-
Creates a new Millheat session instance.
If a session for the credentials already exists, the existing session is
returned. See millheat.logout for destroying sessions.
Parameters:
- access_key
string
the
access_key
to use for login - secret_token
string
the
secret_token
to use for login - username
string
the
username
to use for login - password
string
the
password
to use for login
Returns:
-
Millheat session object
Usage:
local millheat = require "millheat" local mhsession = millheat.new("abcdef", "xyz", "myself@nothere.com", "secret_password") local ok, err = mhsession:login() if not ok then print("failed to login: ", err) end
- access_key
string
the
- request (path[, query])
-
Performs a HTTP request on the Millheat API.
It will automatically inject authentication/session data. Or if not logged
logged in yet, it will log in. If the session has expired it will be renewed.
NOTE: if the response_body is json, then it will be decoded and returned as a Lua table.
Parameters:
- path string the relative path within the API base path
- query table query parameters (will be escaped) (optional)
Returns:
ok
,response_body
,response_code
,response_headers
,response_status_line
Usage:
local millheat = require "millheat" local mhsession = millheat.new("abcdef", "xyz", "myself@nothere.com", "secret_password") local query = { ["param1"] = "value1" } -- the following line will automatically log in local ok, response_body, status, headers, statusline = mhsession:request("/some/path", query)
- rewrite_error ([expected], ...)
-
Rewrite errors to Lua format (nil+error).
Takes the output of the request function and validates it for errors;
- nil+err
- body with "success = false" (some API calls return a 200 with success=false for example)
- mismatch in expected status code (a 200 expected, but a 404 received)
This reduces the error handling to standard Lua errors, instead of having to validate each of the situations above individually.
Parameters:
- expected
number
expected status code, if
nil
, it will be ignored (optional) - ... same parameters as the request method
Returns:
nil+err
or the input argumentsUsage:
local millheat = require "millheat" local mhsession = millheat.new("myself@nothere.com", "secret_password") -- Make a request where we expect a 200 result local ok, response_body, status, headers, statusline = mhsession:rewrite_error(200, mhsession:request("/some/path")) if not ok then return nil, response_body -- a 404 will also follow this path now, since we only want 200's end
API specific functions
This section contains functions that directly interact with the Millheat API.
- control_device (device_id, operation, status, temperature)
-
Controls a specific device.
Invokes the
/uds/deviceControlForOpenApi
endpoint.Parameters:
- device_id string or number the device to control
- operation "temperature" or "switch" the operation to perform
- status
"room", "single", "on", "off", true or false
either "room" or single" (for a
temperature
operation), or "on"/true or "off"/false (for aswitch
operation). - temperature number the temperature (integer) to set, only has an effect with "temperature"+"single" operation and status.
Returns:
-
true or nil+err
Usage:
local millheat = require "millheat" local mhsession = millheat.new("abcdef", "xyz", "myself@nothere.com", "secret_password") local ok, err = mhsession:control_device(123, "temperature", "single", 19) if not ok then print("failed to control the device: ", err) end
- get_device (device_id)
-
Gets the device data.
Invokes the
/uds/selectDevice2020
endpoint.Parameters:
- device_id string or number the device for which to get the data
Returns:
-
list, or nil+err
- get_devices_by_room (room_id)
-
Gets the list of devices associated with a room.
Invokes the
/uds/selectDevicebyRoom2020
endpoint.Parameters:
- room_id string or number the room for which to get the list of devices
Returns:
-
list, or nil+err
- get_homes ()
-
Gets the list of homes.
Invokes the
/uds/selectHomeList
endpoint.Returns:
-
list, or nil+err
Usage:
local millheat = require "millheat" local mhsession = millheat.new("abcdef", "xyz", "myself@nothere.com", "secret_password") local home_list = mhsession:get_homes()
- get_independent_devices_by_home (home_id)
-
Gets the list of independent devices not associated with a room.
Invokes the
/uds/getIndependentDevices2020
endpoint.Parameters:
- home_id string or number the home for which to get the list of independent devices
Returns:
-
list, or nil+err
- get_rooms_by_home (home_id)
-
Gets the list of rooms associated with a home.
Invokes the
/uds/selectRoombyHome2020
endpoint.Parameters:
- home_id string or number the home for which to get the list of rooms
Returns:
-
list, or nil+err