{"_id":"543ea6ac3f50eb1a00ed205e","__v":12,"project":"543b943865bf840e00b473b3","category":{"_id":"543b943865bf840e00b473b7","version":"543b943865bf840e00b473b6","project":"543b943865bf840e00b473b3","__v":15,"pages":["543ffb2c22a3b30e001bdc37","543b965fb1479b1400c42f3a","543d1cbb5276641a00a593c3","543d3ff2a10ab32000b3aa9e","543d1fa83a300f20000d3206","543f8f8a051bdc0e00dfbf02","543d4a17a10ab32000b3aace","543ea21f3f50eb1a00ed2050","543ea6ac3f50eb1a00ed205e","543ebaedcc182e08005d0cc4","543f8cb422a3b30e001bdb48","543f838422a3b30e001bdb36","544184629c7623200053c8e7","5541356a69a03a2d00ce0b3b"],"sync":{"url":"","isSync":false},"reference":false,"createdAt":"2014-10-13T08:58:32.718Z","from_sync":false,"order":9999,"slug":"documentation","title":"Documentation"},"is_link":false,"user":"543b93f865bf840e00b473b2","version":{"_id":"543b943865bf840e00b473b6","__v":5,"project":"543b943865bf840e00b473b3","createdAt":"2014-10-13T08:58:32.703Z","releaseDate":"2014-10-13T08:58:32.703Z","categories":["543b943865bf840e00b473b7","543b96e1b1479b1400c42f3d","543d1cdc3a300f20000d31ee","553e061924ec240d00b1f897","553e06431a946a0d00ad6f78"],"is_deprecated":false,"is_hidden":false,"is_beta":true,"is_stable":true,"codename":"","version_clean":"1.0.0","version":"1.0"},"updates":[],"next":{"pages":[],"description":""},"createdAt":"2014-10-15T16:54:04.840Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"basic_auth":false,"results":{"codes":[]},"try":true,"auth":"never","params":[],"url":""},"isReference":false,"order":7,"body":"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.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"App – Bridge Manager\"\n}\n[/block]\n\n[block:parameters]\n{\n  \"data\": {\n    \"0-0\": \"Configuration\",\n    \"0-1\": \"Bridge Manager\",\n    \"1-0\": \"\",\n    \"1-1\": \"\",\n    \"0-2\": \"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.\",\n    \"1-2\": \"\",\n    \"h-0\": \"Message name\",\n    \"h-1\": \"Message initiator\",\n    \"h-2\": \"Message purpose\"\n  },\n  \"cols\": 3,\n  \"rows\": 1\n}\n[/block]\n**Message representation:** \n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n    \\\"id\\\": “text”,\\n    \\\"adts\\\": []\\n}\",\n      \"language\": \"json\",\n      \"name\": \"Message Representation\"\n    }\n  ]\n}\n[/block]\n**Message parameters: * \n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Name\",\n    \"h-1\": \"Required/Type\",\n    \"h-2\": \"Description\",\n    \"0-0\": \"id\",\n    \"0-1\": \"Yes/string\",\n    \"0-2\": \"The id of the app.\",\n    \"1-0\": \"adts\",\n    \"1-1\": \"No/array\",\n    \"1-2\": \"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.\"\n  },\n  \"cols\": 3,\n  \"rows\": 2\n}\n[/block]\nEach element of the array is defined as follows:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n    “id”: “text”,\\n    “name”: “text”,\\n    “friendly_name”: “text”\\n}\\n\",\n      \"language\": \"json\"\n    }\n  ]\n}\n[/block]\n**Adts parameters:** \n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Name\",\n    \"h-1\": \"Required/Type\",\n    \"h-2\": \"Description\",\n    \"0-0\": \"id\",\n    \"0-1\": \"Yes/text\",\n    \"0-2\": \"The id of the adaptor. This is used in all communications with the adaptor.\",\n    \"1-0\": \"name\",\n    \"1-1\": \"Yes/text\",\n    \"1-2\": \"The name of the device, as supplied by the writer of the adaptor.\",\n    \"2-0\": \"friendly_name\",\n    \"2-1\": \"Yes/text\",\n    \"2-2\": \"The friendly name of the device, as supplied by the user when it was connected to the bridge.\"\n  },\n  \"cols\": 3,\n  \"rows\": 3\n}\n[/block]\n\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Message name\",\n    \"h-1\": \"Message initiator\",\n    \"0-0\": \"State\",\n    \"0-1\": \"App\",\n    \"h-2\": \"Message purpose\",\n    \"0-2\": \"Sent to the bridge manager to indicate the state of the app.\"\n  },\n  \"cols\": 3,\n  \"rows\": 1\n}\n[/block]\n**Message representation:** \n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n    \\\"id\\\": “text”,\\n    \\\"status\\\": \\\"state\\\", \\n    \\\"state\\\": “text”\\n}\",\n      \"language\": \"json\"\n    }\n  ]\n}\n[/block]\n**Message parameters:** \n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Name\",\n    \"h-1\": \"Required/Type\",\n    \"h-2\": \"Description\",\n    \"0-0\": \"id\",\n    \"0-1\": \"Yes/string\",\n    \"1-0\": \"status\",\n    \"1-1\": \"Yes/string\",\n    \"2-0\": \"state\",\n    \"2-1\": \"Yes/string\",\n    \"0-2\": \"The id of the app.\",\n    \"1-2\": \"The string “state”.\",\n    \"2-2\": \"Indicates the state of the app. The must be one of: “starting”, “running”, “stopping”, “error”.\"\n  },\n  \"cols\": 3,\n  \"rows\": 3\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"App-Adaptor\"\n}\n[/block]\n\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Message Name\",\n    \"h-1\": \"Message Initiator\",\n    \"0-1\": \"Adaptor\",\n    \"0-0\": \"Services\",\n    \"h-2\": \"Message Purpose\",\n    \"0-2\": \"Indicates the services that an adaptor can provide.\"\n  },\n  \"cols\": 3,\n  \"rows\": 1\n}\n[/block]\n**Message representation:** \n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n    “name”: “text”,\\n    “id”: “text”,\\n    “status”: “text”,\\n    “content”: “service”,\\n    “services”: “array”\\n}\\n\",\n      \"language\": \"json\"\n    }\n  ]\n}\n[/block]\n**Message parameters:** \n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Name\",\n    \"h-1\": \"Required/Type\",\n    \"h-2\": \"Description\",\n    \"0-0\": \"name\",\n    \"0-1\": \"Yes/string\",\n    \"1-0\": \"id\",\n    \"1-1\": \"Yes/string\",\n    \"2-0\": \"status\",\n    \"2-1\": \"No/string\",\n    \"3-0\": \"content\",\n    \"3-1\": \"Yes/string\",\n    \"4-0\": \"services\",\n    \"4-1\": \"Yes/array\",\n    \"0-2\": \"The name of the adaptor.\",\n    \"1-2\": \"The adaptor id.\",\n    \"2-2\": \"The adaptor status. Currently not used.\",\n    \"3-2\": \"The string \\\"service\\\"\",\n    \"4-2\": \"The services provided by the adaptor. See below.\"\n  },\n  \"cols\": 3,\n  \"rows\": 5\n}\n[/block]\nEach element of the services array takes the following form:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n    “characteristic”: “text”,\\n    “interval”: “integer”,\\n    “type”: “text”\\n}\\n\",\n      \"language\": \"json\"\n    }\n  ]\n}\n[/block]\n**Message parameters:** \n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Name\",\n    \"h-1\": \"Required/Type\",\n    \"h-2\": \"Description\",\n    \"0-0\": \"characteristic\",\n    \"1-0\": \"interval\",\n    \"2-0\": \"type\",\n    \"0-1\": \"Yes/text\",\n    \"1-1\": \"Yes/integer\",\n    \"2-1\": \"Ye/text\",\n    \"1-2\": \"The shortest interval in seconds at which the parameter can be updated.\",\n    \"0-2\": \"The characteristic name.\",\n    \"2-2\": \"May be used to qualify the characteristic.\"\n  },\n  \"cols\": 3,\n  \"rows\": 3\n}\n[/block]\n\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Message name\",\n    \"h-1\": \"Message initiator\",\n    \"h-2\": \"Message purpose\",\n    \"0-0\": \"Characteristic\",\n    \"0-1\": \"Adaptor\",\n    \"0-2\": \"Provides characteristic data\"\n  },\n  \"cols\": 3,\n  \"rows\": 1\n}\n[/block]\n**Message representation:**\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n    “id”: “text”,\\n    “content”: “characteristic”,\\n    “timestamp”: “float”,\\n    “characteristic”: “text”,\\n    “data”: “text”\\n}\",\n      \"language\": \"json\"\n    }\n  ]\n}\n[/block]\n**Message parameters:**\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Name\",\n    \"h-1\": \"Required/Type\",\n    \"h-2\": \"Description\",\n    \"0-0\": \"id\",\n    \"1-0\": \"content\",\n    \"2-0\": \"timestamp\",\n    \"3-0\": \"characteristic\",\n    \"4-0\": \"data\",\n    \"0-1\": \"Yes/string\",\n    \"1-1\": \"Yes/\\\"characteristic\\\"\",\n    \"2-1\": \"Yes/float\",\n    \"3-1\": \"Yes/string\",\n    \"4-1\": \"Yes/?\",\n    \"0-2\": \"The adaptor id.\",\n    \"1-2\": \"\",\n    \"2-2\": \"The epoch time associated with the data.\",\n    \"3-2\": \"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.\",\n    \"4-2\": \"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.\"\n  },\n  \"cols\": 3,\n  \"rows\": 5\n}\n[/block]\n\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Message name\",\n    \"h-1\": \"Message initiator\",\n    \"h-2\": \"Message purpose\",\n    \"0-0\": \"Service Request\",\n    \"0-1\": \"App\",\n    \"0-2\": \"Used to request a service from an adaptor.\"\n  },\n  \"cols\": 3,\n  \"rows\": 1\n}\n[/block]\n**Message representation:**\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n    “id”: “text”,\\n    “request”: “service”,\\n    “services”: []\\n}\\n\",\n      \"language\": \"json\"\n    }\n  ]\n}\n[/block]\n**Message parameters:**\nName\tRequired\tType\tDescription\nid\tYes\tstring\tThe id of the app. \nrequest \tYes\tstring\tIndicates that this is a services request message.\nservices\tYes\tarray\tAn array of dictionaries. See below.\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Name\",\n    \"h-1\": \"Required/Type\",\n    \"h-2\": \"Description\",\n    \"0-0\": \"id\",\n    \"0-1\": \"Yes/string\",\n    \"0-2\": \"The app id.\",\n    \"1-0\": \"request\",\n    \"1-1\": \"Yes/\\\"service\\\"\",\n    \"2-0\": \"services\",\n    \"2-1\": \"Yes/array\",\n    \"2-2\": \"An array of dictionaries. See below.\",\n    \"1-2\": \"Indicates that this is a services request message.\"\n  },\n  \"cols\": 3,\n  \"rows\": 3\n}\n[/block]\nEach element of the services array must have the following form:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n    “characteristic”: “text”,\\n    “interval”: “integer”\\n}\",\n      \"language\": \"json\"\n    }\n  ]\n}\n[/block]\n**Services parameters:**\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Name\",\n    \"h-1\": \"Type/Required\",\n    \"h-2\": \"Description\",\n    \"0-0\": \"characteristic\",\n    \"0-1\": \"Yes/string\",\n    \"0-2\": \"A characteristic, which must be identical to one of the characteristics in the services message that was sent by the adaptor.\",\n    \"1-0\": \"interval\",\n    \"1-1\": \"Yes/integer\",\n    \"1-2\": \"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.\"\n  },\n  \"cols\": 3,\n  \"rows\": 2\n}\n[/block]\nServices 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.\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"App – Concentrator\"\n}\n[/block]\nThis API is not currently implemented. Please contact ContinuumBridge for details.\n\n[Next ...](doc:characteristics)","excerpt":"","slug":"the-bridge-app-api","type":"basic","title":"The Bridge-App API"}

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. [block:api-header] { "type": "basic", "title": "App – Bridge Manager" } [/block] [block:parameters] { "data": { "0-0": "Configuration", "0-1": "Bridge Manager", "1-0": "", "1-1": "", "0-2": "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.", "1-2": "", "h-0": "Message name", "h-1": "Message initiator", "h-2": "Message purpose" }, "cols": 3, "rows": 1 } [/block] **Message representation:** [block:code] { "codes": [ { "code": "{\n \"id\": “text”,\n \"adts\": []\n}", "language": "json", "name": "Message Representation" } ] } [/block] **Message parameters: * [block:parameters] { "data": { "h-0": "Name", "h-1": "Required/Type", "h-2": "Description", "0-0": "id", "0-1": "Yes/string", "0-2": "The id of the app.", "1-0": "adts", "1-1": "No/array", "1-2": "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." }, "cols": 3, "rows": 2 } [/block] Each element of the array is defined as follows: [block:code] { "codes": [ { "code": "{\n “id”: “text”,\n “name”: “text”,\n “friendly_name”: “text”\n}\n", "language": "json" } ] } [/block] **Adts parameters:** [block:parameters] { "data": { "h-0": "Name", "h-1": "Required/Type", "h-2": "Description", "0-0": "id", "0-1": "Yes/text", "0-2": "The id of the adaptor. This is used in all communications with the adaptor.", "1-0": "name", "1-1": "Yes/text", "1-2": "The name of the device, as supplied by the writer of the adaptor.", "2-0": "friendly_name", "2-1": "Yes/text", "2-2": "The friendly name of the device, as supplied by the user when it was connected to the bridge." }, "cols": 3, "rows": 3 } [/block] [block:parameters] { "data": { "h-0": "Message name", "h-1": "Message initiator", "0-0": "State", "0-1": "App", "h-2": "Message purpose", "0-2": "Sent to the bridge manager to indicate the state of the app." }, "cols": 3, "rows": 1 } [/block] **Message representation:** [block:code] { "codes": [ { "code": "{\n \"id\": “text”,\n \"status\": \"state\", \n \"state\": “text”\n}", "language": "json" } ] } [/block] **Message parameters:** [block:parameters] { "data": { "h-0": "Name", "h-1": "Required/Type", "h-2": "Description", "0-0": "id", "0-1": "Yes/string", "1-0": "status", "1-1": "Yes/string", "2-0": "state", "2-1": "Yes/string", "0-2": "The id of the app.", "1-2": "The string “state”.", "2-2": "Indicates the state of the app. The must be one of: “starting”, “running”, “stopping”, “error”." }, "cols": 3, "rows": 3 } [/block] [block:api-header] { "type": "basic", "title": "App-Adaptor" } [/block] [block:parameters] { "data": { "h-0": "Message Name", "h-1": "Message Initiator", "0-1": "Adaptor", "0-0": "Services", "h-2": "Message Purpose", "0-2": "Indicates the services that an adaptor can provide." }, "cols": 3, "rows": 1 } [/block] **Message representation:** [block:code] { "codes": [ { "code": "{\n “name”: “text”,\n “id”: “text”,\n “status”: “text”,\n “content”: “service”,\n “services”: “array”\n}\n", "language": "json" } ] } [/block] **Message parameters:** [block:parameters] { "data": { "h-0": "Name", "h-1": "Required/Type", "h-2": "Description", "0-0": "name", "0-1": "Yes/string", "1-0": "id", "1-1": "Yes/string", "2-0": "status", "2-1": "No/string", "3-0": "content", "3-1": "Yes/string", "4-0": "services", "4-1": "Yes/array", "0-2": "The name of the adaptor.", "1-2": "The adaptor id.", "2-2": "The adaptor status. Currently not used.", "3-2": "The string \"service\"", "4-2": "The services provided by the adaptor. See below." }, "cols": 3, "rows": 5 } [/block] Each element of the services array takes the following form: [block:code] { "codes": [ { "code": "{\n “characteristic”: “text”,\n “interval”: “integer”,\n “type”: “text”\n}\n", "language": "json" } ] } [/block] **Message parameters:** [block:parameters] { "data": { "h-0": "Name", "h-1": "Required/Type", "h-2": "Description", "0-0": "characteristic", "1-0": "interval", "2-0": "type", "0-1": "Yes/text", "1-1": "Yes/integer", "2-1": "Ye/text", "1-2": "The shortest interval in seconds at which the parameter can be updated.", "0-2": "The characteristic name.", "2-2": "May be used to qualify the characteristic." }, "cols": 3, "rows": 3 } [/block] [block:parameters] { "data": { "h-0": "Message name", "h-1": "Message initiator", "h-2": "Message purpose", "0-0": "Characteristic", "0-1": "Adaptor", "0-2": "Provides characteristic data" }, "cols": 3, "rows": 1 } [/block] **Message representation:** [block:code] { "codes": [ { "code": "{\n “id”: “text”,\n “content”: “characteristic”,\n “timestamp”: “float”,\n “characteristic”: “text”,\n “data”: “text”\n}", "language": "json" } ] } [/block] **Message parameters:** [block:parameters] { "data": { "h-0": "Name", "h-1": "Required/Type", "h-2": "Description", "0-0": "id", "1-0": "content", "2-0": "timestamp", "3-0": "characteristic", "4-0": "data", "0-1": "Yes/string", "1-1": "Yes/\"characteristic\"", "2-1": "Yes/float", "3-1": "Yes/string", "4-1": "Yes/?", "0-2": "The adaptor id.", "1-2": "", "2-2": "The epoch time associated with the data.", "3-2": "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.", "4-2": "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." }, "cols": 3, "rows": 5 } [/block] [block:parameters] { "data": { "h-0": "Message name", "h-1": "Message initiator", "h-2": "Message purpose", "0-0": "Service Request", "0-1": "App", "0-2": "Used to request a service from an adaptor." }, "cols": 3, "rows": 1 } [/block] **Message representation:** [block:code] { "codes": [ { "code": "{\n “id”: “text”,\n “request”: “service”,\n “services”: []\n}\n", "language": "json" } ] } [/block] **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. [block:parameters] { "data": { "h-0": "Name", "h-1": "Required/Type", "h-2": "Description", "0-0": "id", "0-1": "Yes/string", "0-2": "The app id.", "1-0": "request", "1-1": "Yes/\"service\"", "2-0": "services", "2-1": "Yes/array", "2-2": "An array of dictionaries. See below.", "1-2": "Indicates that this is a services request message." }, "cols": 3, "rows": 3 } [/block] Each element of the services array must have the following form: [block:code] { "codes": [ { "code": "{\n “characteristic”: “text”,\n “interval”: “integer”\n}", "language": "json" } ] } [/block] **Services parameters:** [block:parameters] { "data": { "h-0": "Name", "h-1": "Type/Required", "h-2": "Description", "0-0": "characteristic", "0-1": "Yes/string", "0-2": "A characteristic, which must be identical to one of the characteristics in the services message that was sent by the adaptor.", "1-0": "interval", "1-1": "Yes/integer", "1-2": "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." }, "cols": 3, "rows": 2 } [/block] 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. [block:api-header] { "type": "basic", "title": "App – Concentrator" } [/block] This API is not currently implemented. Please contact ContinuumBridge for details. [Next ...](doc:characteristics)