Api definition "SingingCat Automation Api"
Api calls overview
listMyModules
Returns a list of modules, using a basic filter system
setDeviceOnOrOff
Trigger a switch. The equivalent of pressing a button to turn a device on or off. Returns previous state of switch
getDeviceState
reads the state of a module
setModuleName
give a module a name
setDeviceName
give a module of a module a name
Api calls
API Call: listMyModules
Prototype: listMyModules(STRING "authtoken", BOOLEAN "activeonly")
Description: Returns a list of modules, using a basic filter system
Max Runtime: 1000ms
Return value: module[]
Parameters:
| Name | Type | Mandatory | Minimum | Maximum | Description |
| "authtoken" | STRING | Mandatory | | | Authentication token |
| "activeonly" | BOOLEAN | Optional | | | If set to true, then only modules, which are currently reachable will be returned |
API Call: setDeviceOnOrOff
Prototype: setDeviceOnOrOff(STRING "authtoken", STRING "moduleId", INTEGER "device", STRING "desiredState")
Description: Trigger a switch. The equivalent of pressing a button to turn a device on or off. Returns previous state of switch
Max Runtime: 1000ms
Return value: BOOLEAN
Parameters:
| Name | Type | Mandatory | Minimum | Maximum | Description |
| "authtoken" | STRING | Mandatory | | | Authentication token |
| "moduleId" | STRING | Mandatory | | | |
| "device" | INTEGER | Mandatory | 0 | 256 | specifies the device on this module |
| "desiredState" | STRING | Mandatory | | | specifies the module to trigger |
API Call: getDeviceState
Prototype: getDeviceState(STRING "authtoken", STRING "moduleId", INTEGER "device")
Description: reads the state of a module
Max Runtime: 1000ms
Return value: modulestate
Parameters:
| Name | Type | Mandatory | Minimum | Maximum | Description |
| "authtoken" | STRING | Mandatory | | | Authentication token |
| "moduleId" | STRING | Mandatory | | | |
| "device" | INTEGER | Mandatory | 0 | 256 | specifies the device on this module |
API Call: setModuleName
Prototype: setModuleName(STRING "authtoken", STRING "moduleId", STRING "name")
Description: give a module a name
Max Runtime: 1000ms
Parameters:
| Name | Type | Mandatory | Minimum | Maximum | Description |
| "authtoken" | STRING | Mandatory | | | Authentication token |
| "moduleId" | STRING | Mandatory | | | |
| "name" | STRING | Mandatory | | | |
API Call: setDeviceName
Prototype: setDeviceName(STRING "authtoken", STRING "moduleId", STRING "name", INTEGER "device")
Description: give a module of a module a name
Max Runtime: 1000ms
Parameters:
| Name | Type | Mandatory | Minimum | Maximum | Description |
| "authtoken" | STRING | Mandatory | | | Authentication token |
| "moduleId" | STRING | Mandatory | | | |
| "name" | STRING | Mandatory | | | |
| "device" | INTEGER | Mandatory | 0 | 256 | specifies the device on this module |
Api Datatypes
DATETIME format follows ISO norm, e.g.: 2015-06-12T09:17:37+00:00
BOOLEAN is 0 or 1 or true or false
INTEGER is 64 bit signed
STRING is upto 64k, 8-byte coded, text (e.g. ascii/UTF-8 but NOT UTF-16)
URL is typically http://stuff ;)
Authentication is done via an API key (which one may generate on the website)
Datatype: moduleswitch
| Name | Type | Description |
| "name" | STRING | the user-supplied name of this module |
| "state" | BOOLEAN | state of the switch |
Datatype: module
| Name | Type | Description |
| "moduleId" | STRING | an opaque string representing this module. |
| "name" | STRING | the user-supplied name of this module |
Datatype: dac
| Name | Type | Description |
| "name" | STRING | the user-supplied name of this module |
| "value" | INTEGER | current output (0..1000) |
Datatype: modulestate
| Name | Type | Description |
| "switches" | moduleswitch[] | list of all switches of a module |
| "dacs" | dac[] | list of all digital-analog converters (e.g. dimmers) of a module |
