zipato.lua

Contents

• Generic functions
• API specific functions
• Session tracked attributes

Modules

• zipato

Topics

• readme

Examples

• mqtt.lua
• test.lua

Module zipato

Zipato API library for Zipabox/Zipatile home controllers for the V2 api which has been deprecated.

The V2 devices are no longer available through the zipato cloud, only the local API remians.

This library implements the session management and makes it easy to access individual endpoints of the API.

Info:

• Copyright: 2019-2020 Thijs Schreijer
• Release: Version x.x, Library to acces the Zipato API
• License: zipato.lua is free software under the MIT/X11 license.
• Author: Thijs Schreijer, http://www.thijsschreijer.nl

Generic functions

API specific functions

Session tracked attributes

Generic functions

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 zipato = require "zipato"
local zsession = zipato.new("myself@nothere.com", "secret_password")
local ok, err = zsession:login()
if not ok then
  print("failed to login: ", err)
end

logout ()

Logs out of the current session.

Returns:

true or nil+err

Usage:

local zipato = require "zipato"
local zsession = zipato.new("myself@nothere.com", "secret_password")
local ok, err = zsession:login()
if not ok then
  print("failed to login: ", err)
else
  zsession:logout()
end

new (username, password, opts)

Creates a new Zipato session instance.

Parameters:

• username (string) required, the username to use for login
• password (string) required, the password to use for login
• opts (table, optional) additional options
  • base_url string (string) the base url of the API, defaults to "http://192.168.2.6:8080".

Returns:

zipato session object

Usage:

local zipato = require "zipato"
local zsession = zipato.new("myself@nothere.com", "secret_password", {
  attribute_update_config = {
    update_interval = 1,   -- max age in seconds before refreshing
    callback = function(session, uuid, value)
      -- callback called for each attribute value update
    end,
  }
})
local ok, err = zsession:login()
if not ok then
  print("failed to login: ", err)
end

request (path, method, headers, query, body)

Performs a HTTP request on the Zipato 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.

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, eg. "/v2/..."
• method (string) HTTP method to use
• headers (table) optional header table
• query (table) optional query parameters (will be escaped)
• body (table/string) optional body. 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".

Returns:

ok, responsebody, responsecode, responseheaders, responsestatus_line

Usage:

local zipato = require "zipato"
local zsession = zipato.new("myself@nothere.com", "secret_password")

local headers = { ["My-Header"] = "myvalue" }
local query = { ["param1"] = "value1" }

-- the following line will automatically log in
local ok, response_body, status, headers, statusline = zsession:request("/v2/attributes", "GET", headers, query, nil)

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) optional expected status code, if nil, it will be ignored
• ... same parameters as the request method

Returns:

nil+err or the input arguments

Usage:

local zipato = require "zipato"
local zsession = zipato.new("myself@nothere.com", "secret_password")

-- Make a request where we expect a 200 result
local ok, response_body, status, headers, statusline = zsession:rewrite_error(200, zsession:request("/v2/attributes", "GET"))
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

find_device (uuid_or_name)

Returns a device by name or uuid. Retreives the list through get_devices but only returns the requested one.

Parameters:

• uuid_or_name

Returns:

device, or nil+err

get_attribute_values (handle, update, raw)

Returns all attribute values; "/attributes/values" GET.

Parameters:

• handle (string, optional) handle of last call for updates
• update (boolean, optional) request only updated values or all, defaults to true if handle is given, or false if not
• raw (boolean, optional) if true, raw results, otherwise a table keyed by uuid, with the value as value

Returns:

raw values array + handle, or nil+err

get_device_attributes (device_uuid)

Returns device attributes by device. Gets all attributes from the device endpoints; "/endpoints/{uuid}", and combines them into a single attribute table.

Parameters:

• device_uuid (string) uuid of device to get

Returns:

attribute array, or nil+err

get_device_details (device_uuid, query)

Returns device details by device_uuid; "/devices/{uuid} GET".

Parameters:

• device_uuid (string) uuid of device to get
• query (table, optional) query parameters, default: { full=true }

Returns:

device, or nil+err

get_devices ()

Returns list of all devices; "/devices GET".

Returns:

list, or nil+err

get_mqtt_config ()

Returns the mqtt configuration of the box if available.

Returns:

table with brokerip, brokerport and box_topic, or nil+err

set_attribute_value (attribute_uuid, value, timestamp, pendingValue, pendingTimestamp)

Sets an attribute value; "/attributes/{uuid}/value PUT".

Parameters:

• attribute_uuid (string) the uuid of the attribute to set the value of.
• value (optional) the value to set
• timestamp (Date, optional) timestamp for the value to set
• pendingValue (optional) pendingValue to set
• pendingTimestamp (Date, optional) timestamp for the pendingValue to set

Returns:

true, or nil+err

Session tracked attributes

fetch_attribute_values ()

Fetches attribute values tracked by the session. This will force an update, even if the values haven't expired yet. This could for example be called on a recurring timer. With a configured callback to handle the updates.

Returns:

true, or nil+err

get_attribute_value (uuid)

Gets a single attribute value, as tracked by the session. If the current values are to old, it will update them in the process by calling fetch_attribute_values first.

Parameters:

• uuid (string) the uuid of the attribute to return the value of

Returns:

value, or nil+err

See also:

fetch_attribute_values