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 or nil+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
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 arguments

Usage:

    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 a switch 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
generated by LDoc 1.4.6 Last updated 2022-08-10 09:30:44