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: http://mn-be-prod-documentation.s3-website.eu-central-1.amazonaws.com/#/.

Usage:

  • local millheat = require "millheat"
    local mhsession = millheat.new {
      -- use username/password OR apikey, not both!
      username = "name@email.org",
      password = "secret_password",
      -- api_key = "xyz",
    }
    
    local ok, data = self:srequest("GET:/houses/{houseId}/rooms", { houseId = "some-id-here" })
    if not ok then
      print("failed to get rooms: ", data)
    end
    
    mhsession:logout()
    
  • -- or using the Copas scheduler
    local copas = require "copas"
    
    copas.addthread(function()
      local millheat = require "millheat"
      local mhsession = millheat.new {
        -- use username/password OR apikey, not both!
        username = "name@email.org",
        password = "secret_password",
        -- api_key = "xyz",
      }
    
      local ok, data = self:srequest("GET:/houses/{houseId}/rooms", { houseId = "some-id-here" })
      if not ok then
        print("failed to get rooms: ", data)
      end
    
      mhsession:logout()
    end)
    
    copas.loop()
    

Info:

  • Copyright: 2020-2024 Thijs Schreijer
  • Release: Version 0.4.1, Library to access the Millheat API
  • License: millheat.lua is free software under the MIT/X11 license.
  • Author: Thijs Schreijer

Tables

millheat The module table containing some global settings and constants.

Generic functions

login () Logs in the current session.
logout (clear) Logs out of the current session.
new (opts) Creates a new Millheat session instance.
request (path[, method="GET"[, query[, body]]]) Performs a HTTP request on the Millheat API.
rewrite_error ([expected], ...) Rewrite errors to Lua format (nil+error).
srequest (path[, params[, body]]) Smart HTTP request on the Millheat API.

API specific functions

get_houses () Gets the list of houses.


Tables

millheat
The module table containing some global settings and constants.

Fields:

  • https This is a function set on the module table, such that it can be overridden by another implementation. If Copas) was loaded before this module then copas.http will be used, otherwise it uses the LuaSec one (module ssl.https).
  • log Logger is set on the module table, to be able to override it. Default is the LuaLogging default logger if LuaLogging was loaded before this module. Otherwise it uses a stub logger with only no-op functions.

Generic functions

Functions for session management and instantiation
login ()
Logs in the current session. This will automatically be called by the request and srequest methods, if not logged in already. Has no effect for API key auth.

Returns:

    true or nil+err

Usage:

    local millheat = require "millheat"
    local mhsession = millheat.new {
      username = "name@email.org",
      password = "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. This only applies to user/pwd login. Does nothing for API key auth.

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

Usage:

    local millheat = require "millheat"
    local mhsession = millheat.new {
      username = "name@email.org",
      password = "secret_password",
    }
    local ok, err = mhsession:login()
    if not ok then
      print("failed to login: ", err)
    else
      mhsession:logout()
    end
new (opts)
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.

Use either username+password OR api_key, not both.

Parameters:

  • opts the options table, supporting the following options:
    • username string the username to use for login (optional)
    • password string the password to use for login (optional)
    • api_key string the api_key to use for login (optional)

Returns:

    Millheat session object

Usage:

    local millheat = require "millheat"
    local mhsession = millheat.new {
      username = "name@email.org",
      password = "secret_password",
    }
    local ok, err = mhsession:login()
    if not ok then
      print("failed to login: ", err)
    end
request (path[, method="GET"[, query[, body]]])
Performs a HTTP request on the Millheat API. It will automatically inject authentication/session data. Or if not logged in yet, it will log in. If the session has expired it will be renewed.

This method is a low-level method, and is used by the higher level srequest. The latter is recommended for use in most cases since it is easier to use and more readable.

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
  • method string the http method to use (will be capitalized) (default "GET")
  • query table query parameters (will be escaped) (optional)
  • body table or string request body, a table will be encoded as json (optional)

Returns:

    ok, response_body, response_code, response_headers, response_status_line

Usage:

    local millheat = require "millheat"
    local mhsession = millheat.new {
      username = "name@email.org",
      password = "secret_password",
    }
    
    local body = { param1 = "value1" }
    
    -- the following line will automatically log in
    local ok, response_body, status, headers, statusline = mhsession:request("/some/path", "GET", nil, body)
rewrite_error ([expected], ...)
Rewrite errors to Lua format (nil+error). Takes the output of the request function and validates it for errors;

  • nil+err
  • 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 or table expected status code, if nil, it will be ignored. If a table then the keys must be the allowed status codes. (optional)
  • ... same parameters as the request method

Returns:

    nil+err on error, or the input arguments

Usage:

    local millheat = require "millheat"
    local mhsession = millheat.new {
      username = "name@email.org",
      password = "secret_password",
    }
    
    -- Make a request where we expect a 200 or 201 result
    expected = { 200 = true, 201 = true }
    local ok, response_body, status, headers, statusline = mhsession:rewrite_error(expected, 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
srequest (path[, params[, body]])
Smart HTTP request on the Millheat API. It will automatically inject authentication/session data, and login if required. Parameters will be injected in the path, remaining ones will be added to the query. Responses in 20x range will be valid, anything else is returned as a Lua error.

Parameters:

  • path string the relative path within the API base path, format: "METHOD:/path/{param1}/to/{param2}". Method defaults to "GET".
  • params table parameters, path parameters will be injected, others will be added to the query (they will be escaped). (optional)
  • body table or string request body, a table will be encoded as json (optional)

Returns:

    ok, response_body, response_code, response_headers, response_status_line or nil+error

Usage:

    local millheat = require "millheat"
    local mhsession = millheat.new {
      username = "name@email.org",
      password = "secret_password",
    }
    
    local house_id = "xyz some id"
    
    -- the following line will automatically log in, and fetch the data
    local ok, data = mhsession:srequest("GET:/houses/{houseId}/devices", {
      houseId = house_id,
    })
    if not ok then
      print("failed to get devices: ", data)
    end

API specific functions

This section contains functions that directly interact with the Millheat API.
get_houses ()
Gets the list of houses. Invokes the GET:/houses endpoint.

Returns:

    list, or nil+err

Usage:

    local millheat = require "millheat"
    local mhsession = millheat.new {
      username = "name@email.org",
      password = "secret_password",
    }
    local home_list = mhsession:get_houses()
generated by LDoc 1.4.6 Last updated 2024-02-11 15:20:49