The Bridge-App API

This section contains a description of the messages that communicate between the bridge manager, apps and adaptors. Several of these are dealt with entirely by the app and adaptor super-classes and do not need to be used when writing an app, but their description is included here as they are visible to an app.

App – Bridge Manager

Message name	Message initiator	Message purpose
Configuration	Bridge Manager	Provides configuration to the app. The message contains fields, not listed here, that are processed in the CbApp super-class. There is no need for the app to do anything with this information.

Message representation:

{
    "id": “text”,
    "adts": []
}

*Message parameters:

Name	Required/Type	Description
id	Yes/string	The id of the app.
adts	No/array	An array of information about the adaptors that the app is connected to, as defined below. If the array is empty, then the app has been installed on the bridge, but no adaptors are connected to it. This message may be sent multiple times as devices are connected or disconnected from the app. It is the responsibility of the app to manage these connections and disconnections.

Each element of the array is defined as follows:

{
    “id”: “text”,
    “name”: “text”,
    “friendly_name”: “text”
}

Adts parameters:

Name	Required/Type	Description
id	Yes/text	The id of the adaptor. This is used in all communications with the adaptor.
name	Yes/text	The name of the device, as supplied by the writer of the adaptor.
friendly_name	Yes/text	The friendly name of the device, as supplied by the user when it was connected to the bridge.

Message name	Message initiator	Message purpose
State	App	Sent to the bridge manager to indicate the state of the app.

Message representation:

{
    "id": “text”,
    "status": "state", 
    "state": “text”
}

Message parameters:

Name	Required/Type	Description
id	Yes/string	The id of the app.
status	Yes/string	The string “state”.
state	Yes/string	Indicates the state of the app. The must be one of: “starting”, “running”, “stopping”, “error”.

App-Adaptor

Message Name	Message Initiator	Message Purpose
Services	Adaptor	Indicates the services that an adaptor can provide.

Message representation:

{
    “name”: “text”,
    “id”: “text”,
    “status”: “text”,
    “content”: “service”,
    “services”: “array”
}

Message parameters:

Name	Required/Type	Description
name	Yes/string	The name of the adaptor.
id	Yes/string	The adaptor id.
status	No/string	The adaptor status. Currently not used.
content	Yes/string	The string "service"
services	Yes/array	The services provided by the adaptor. See below.

Each element of the services array takes the following form:

{
    “characteristic”: “text”,
    “interval”: “integer”,
    “type”: “text”
}

Message parameters:

Name	Required/Type	Description
characteristic	Yes/text	The characteristic name.
interval	Yes/integer	The shortest interval in seconds at which the parameter can be updated.
type	Ye/text	May be used to qualify the characteristic.

Message name	Message initiator	Message purpose
Characteristic	Adaptor	Provides characteristic data

Message representation:

{
    “id”: “text”,
    “content”: “characteristic”,
    “timestamp”: “float”,
    “characteristic”: “text”,
    “data”: “text”
}

Message parameters:

Name	Required/Type	Description
id	Yes/string	The adaptor id.
content	Yes/"characteristic"
timestamp	Yes/float	The epoch time associated with the data.
characteristic	Yes/string	Indicates what is contained in the data. This will be the same as a parameter name in the services message that was provided by the adaptor.
data	Yes/?	The type depends on the form of the data. Eg: if the content is “temperature”, the data will be a float; if the content is “switch”, the data will be a string that can take the values “off” or “on”. This is defined later.

Message name	Message initiator	Message purpose
Service Request	App	Used to request a service from an adaptor.

Message representation:

{
    “id”: “text”,
    “request”: “service”,
    “services”: []
}

Message parameters:
Name Required Type Description
id Yes string The id of the app.
request Yes string Indicates that this is a services request message.
services Yes array An array of dictionaries. See below.

Name	Required/Type	Description
id	Yes/string	The app id.
request	Yes/"service"	Indicates that this is a services request message.
services	Yes/array	An array of dictionaries. See below.

Each element of the services array must have the following form:

{
    “characteristic”: “text”,
    “interval”: “integer”
}

Services parameters:

Name	Type/Required	Description
characteristic	Yes/string	A characteristic, which must be identical to one of the characteristics in the services message that was sent by the adaptor.
interval	Yes/integer	The app can request the characteristic at a particular interval. If this is greater than the corresponding minimum interval contained in the services message from the adaptor then the adaptor will provide updates at least this often. If it is less than the minimum interval then it will updated at the minimum interval. The timestamp parameter in the Data message should always be used for actual times.

Services request messages may be sent to adaptors at any time, not just at initiation. Note, however, that each service request must specify the complete set of characteristic that the app requires. In other words, if a characteristic is not mentioned in the most recent message it will be turned off by the adaptor.

App – Concentrator

This API is not currently implemented. Please contact ContinuumBridge for details.

Next ...