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:
NameTypeMandatoryMinimumMaximumDescription
"authtoken"STRINGMandatoryAuthentication token
"activeonly"BOOLEANOptionalIf 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:
NameTypeMandatoryMinimumMaximumDescription
"authtoken"STRINGMandatoryAuthentication token
"moduleId"STRINGMandatory
"device"INTEGERMandatory0256specifies the device on this module
"desiredState"STRINGMandatoryspecifies 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:
NameTypeMandatoryMinimumMaximumDescription
"authtoken"STRINGMandatoryAuthentication token
"moduleId"STRINGMandatory
"device"INTEGERMandatory0256specifies 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:
NameTypeMandatoryMinimumMaximumDescription
"authtoken"STRINGMandatoryAuthentication token
"moduleId"STRINGMandatory
"name"STRINGMandatory

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:
NameTypeMandatoryMinimumMaximumDescription
"authtoken"STRINGMandatoryAuthentication token
"moduleId"STRINGMandatory
"name"STRINGMandatory
"device"INTEGERMandatory0256specifies 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
NameTypeDescription
"name"STRINGthe user-supplied name of this module
"state"BOOLEANstate of the switch
Datatype: module
NameTypeDescription
"moduleId"STRINGan opaque string representing this module.
"name"STRINGthe user-supplied name of this module
Datatype: dac
NameTypeDescription
"name"STRINGthe user-supplied name of this module
"value"INTEGERcurrent output (0..1000)
Datatype: modulestate
NameTypeDescription
"switches"moduleswitch[]list of all switches of a module
"dacs"dac[]list of all digital-analog converters (e.g. dimmers) of a module