Butler API

Version: 1.0.0

Status:

Butler interface for Thunder framework.

Introduction

Scope

This document describes purpose and functionality of the Butler interface (version 1.0.0). It includes detailed specification about its methods and properties as well as sent notifications.

Case Sensitivity

All identifiers of the interfaces described in this document are case-sensitive. Thus, unless stated otherwise, all keywords, entities, properties, relations and actions should be treated as such.

Acronyms, Abbreviations and Terms

The table below provides and overview of acronyms used in this document and their definitions.

Acronym	Description
API	Application Programming Interface
HTTP	Hypertext Transfer Protocol
JSON	JavaScript Object Notation; a data interchange format
JSON-RPC	A remote procedure call protocol encoded in JSON

The table below provides and overview of terms and abbreviations used in this document and their definitions.

Term	Description
callsign	The name given to an instance of a plugin. One plugin can be instantiated multiple times, but each instance the instance name, callsign, must be unique.

References

Ref ID	Description
HTTP	HTTP specification
JSON-RPC	JSON-RPC 2.0 specification
JSON	JSON specification
Thunder	Thunder API Reference

Description

Butler JSON-RPC interface.

Methods

The following methods are provided by the Butler interface:

Butler interface methods:

Method	Description
persist	Make sure the current information is persisted, so it survives a reboot

persist ^method

Make sure the current information is persisted, so it survives a reboot.

Parameters

This method takes no parameters.

Errors

Message	Description
`ERROR_BAD_REQUEST`	Storage failed

Example

Request

{
  "jsonrpc": "2.0",
  "id": 42,
  "method": "<callsign>.1.persist"
}

Response

{
  "jsonrpc": "2.0",
  "id": 42,
  "result": null
}

Properties

The following properties are provided by the Butler interface:

Butler interface properties:

Property	R/W	Description
orphans	read-only	List of devices not attached to any nodes
bundle	read-only	List of devices not attached to any nodes
device	read-only	Device specific information
value	read/write	Set or Get the value of the device
group	read/write	Get the names part of a group
link	read/write	Link an external ID to a node
move	read/write	Move a node to another location
branch	read/write	Create a new group
delete	read/write	Destroy an existing, empty group

orphans ^property

Provides access to the list of devices not attached to any nodes.

This property is read-only.

The module index parameter shall be passed as the index to the property, i.e. orphans@<module-index>.

Index

Name	Type	M/O	Description
module-index	string	mandatory	0 = any module, >0 orphans from the requested module

Value

Name	Type	M/O	Description
(property)	array	mandatory	List of devices not attached to any nodes
(property)[#]	object	mandatory	...
(property)[#].id	integer	mandatory	Identifier of the device
(property)[#]?.bundle	integer	optional	If this value point belongs to a bundle of more value points
(property)[#].name	string	mandatory	Name given to this device
(property)[#]?.callsign	string	optional	The callsign that owns this external
(property)[#].basic	string	mandatory	Basic description of the device (measure or control) (must be one of the following: control, group, identification, measure)
(property)[#].specific	string	mandatory	More eleborated description of the device (must be one of the following: accessControl, air, burglar, carbonDioxide, carbonMonoxide, clock, electricity, emergency, gas, general, light, powerManagement, smoke, system, temperature, water)
(property)[#].dimension	string	mandatory	What is the dimension of the value that is returned by the device (must be one of the following: degrees, kvah, kwh, logic, percentage, pulses, units)
(property)[#].decimals	integer	mandatory	Number of digits that should be considered fractional
(property)[#].minimum	integer	mandatory	Minimum value that the device can reach
(property)[#].maximum	integer	mandatory	Maximum value that the device can reach
(property)[#]?.value	integer	optional	Value of the device

Example

Get Request

{
  "jsonrpc": "2.0",
  "id": 42,
  "method": "<callsign>.1.orphans@[ {}, {}, {} ]"
}

Get Response

{
  "jsonrpc": "2.0",
  "id": 42,
  "result": [
    {
      "id": 123456,
      "bundle": 342,
      "name": "/kitchen/ceiling/dimmer",
      "callsign": "VirtualControl",
      "basic": "measure",
      "specific": "electricity",
      "dimension": "logic",
      "decimals": 0,
      "minimum": -80,
      "maximum": 200,
      "value": 1
    }
  ]
}

bundle ^property

Provides access to the list of devices not attached to any nodes.

This property is read-only.

The bundle id parameter shall be passed as the index to the property, i.e. bundle@<bundle-id>.

Index

Name	Type	M/O	Description
bundle-id	string	mandatory	The id of the bundle for which you would like to have the value points

Value

Name	Type	M/O	Description
(property)	array	mandatory	List of devices not attached to any nodes
(property)[#]	object	mandatory	...
(property)[#].id	integer	mandatory	Identifier of the device
(property)[#]?.bundle	integer	optional	If this value point belongs to a bundle of more value points
(property)[#].name	string	mandatory	Name given to this device
(property)[#]?.callsign	string	optional	The callsign that owns this external
(property)[#].basic	string	mandatory	Basic description of the device (measure or control) (must be one of the following: control, group, identification, measure)
(property)[#].specific	string	mandatory	More eleborated description of the device (must be one of the following: accessControl, air, burglar, carbonDioxide, carbonMonoxide, clock, electricity, emergency, gas, general, light, powerManagement, smoke, system, temperature, water)
(property)[#].dimension	string	mandatory	What is the dimension of the value that is returned by the device (must be one of the following: degrees, kvah, kwh, logic, percentage, pulses, units)
(property)[#].decimals	integer	mandatory	Number of digits that should be considered fractional
(property)[#].minimum	integer	mandatory	Minimum value that the device can reach
(property)[#].maximum	integer	mandatory	Maximum value that the device can reach
(property)[#]?.value	integer	optional	Value of the device

Example

Get Request

{
  "jsonrpc": "2.0",
  "id": 42,
  "method": "<callsign>.1.bundle@[ {}, {}, {} ]"
}

Get Response

{
  "jsonrpc": "2.0",
  "id": 42,
  "result": [
    {
      "id": 123456,
      "bundle": 342,
      "name": "/kitchen/ceiling/dimmer",
      "callsign": "VirtualControl",
      "basic": "measure",
      "specific": "electricity",
      "dimension": "logic",
      "decimals": 0,
      "minimum": -80,
      "maximum": 200,
      "value": 1
    }
  ]
}

device ^property

Provides access to the device specific information.

This property is read-only.

The device name parameter shall be passed as the index to the property, i.e. device@<device-name>.

Index

Name	Type	M/O	Description
device-name	string	mandatory	...

Value

Name	Type	M/O	Description
(property)	object	mandatory	Device specific information
(property).id	integer	mandatory	Identifier of the device
(property)?.bundle	integer	optional	If this value point belongs to a bundle of more value points
(property).name	string	mandatory	Name given to this device
(property)?.callsign	string	optional	The callsign that owns this external
(property).basic	string	mandatory	Basic description of the device (measure or control) (must be one of the following: control, group, identification, measure)
(property).specific	string	mandatory	More eleborated description of the device (must be one of the following: accessControl, air, burglar, carbonDioxide, carbonMonoxide, clock, electricity, emergency, gas, general, light, powerManagement, smoke, system, temperature, water)
(property).dimension	string	mandatory	What is the dimension of the value that is returned by the device (must be one of the following: degrees, kvah, kwh, logic, percentage, pulses, units)
(property).decimals	integer	mandatory	Number of digits that should be considered fractional
(property).minimum	integer	mandatory	Minimum value that the device can reach
(property).maximum	integer	mandatory	Maximum value that the device can reach
(property)?.value	integer	optional	Value of the device

Errors

Message	Description
`ERROR_UNKNOWN_KEY`	Unknown device

Example

Get Request

{
  "jsonrpc": "2.0",
  "id": 42,
  "method": "<callsign>.1.device@The name of the device or the Id of the device"
}

Get Response

{
  "jsonrpc": "2.0",
  "id": 42,
  "result": {
    "id": 123456,
    "bundle": 342,
    "name": "/kitchen/ceiling/dimmer",
    "callsign": "VirtualControl",
    "basic": "measure",
    "specific": "electricity",
    "dimension": "logic",
    "decimals": 0,
    "minimum": -80,
    "maximum": 200,
    "value": 1
  }
}

value ^property

Provides access to the set or Get the value of the device.

The device name parameter shall be passed as the index to the property, i.e. value@<device-name>.

Index

Name	Type	M/O	Description
device-name	string	mandatory	...

Value

Name	Type	M/O	Description
(property)	integer	mandatory	Value of the device

Name	Type	M/O	Description
(property)	integer	mandatory	Value of the device

Errors

Message	Description
`ERROR_UNKNOWN_KEY`	Unknown device

Example

Get Request

{
  "jsonrpc": "2.0",
  "id": 42,
  "method": "<callsign>.1.value@The name of the device (name) or the numerical identifier of the device"
}

Get Response

{
  "jsonrpc": "2.0",
  "id": 42,
  "result": 1
}

Set Request

{
  "jsonrpc": "2.0",
  "id": 42,
  "method": "<callsign>.1.value@The name of the device (name) or the numerical identifier of the device",
  "params": 1
}

Set Response

{
    "jsonrpc": "2.0",
    "id": 42,
    "result": "null"
}

group ^property

Provides access to the get the names part of a group.

Butler API

Table of Contents

Introduction

Scope

Case Sensitivity

Acronyms, Abbreviations and Terms

References

Description

Methods

persist method

Parameters

Errors

Example

Request

Response

Properties

orphans property

Index

Value

Example

Get Request

Get Response

bundle property

Index

Value

Example

Get Request

Get Response

device property

Index

Value

Errors

Example

Get Request

Get Response

value property

Index

Value

Errors

Example

Get Request

Get Response

Set Request

Set Response

group property

persist ^method

orphans ^property

bundle ^property

device ^property

value ^property

group ^property