Merge pull request #68 from sebastianharder/master

API: Update Postman collection to API version 3.2

CHANGELOG.md

@@ -5,6 +5,20 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](http://keepachangelog.com/)
 and this project adheres to [Semantic Versioning](http://semver.org/).
 
+## [3.2.0] - 2022-12-09
+### Changed
+- Updated HTTP request header to use "api-version : 3.2" instead of "api-version : 2.1"
+- Synced Postman collection version with API version 3.2
+- Updated Postman environment variables
+- Removed deprecated requests for Intrusion Detection from Postman collection
+- New: Door/Window Contact II Bypass and Vibration states
+- New: Motion Detector Illuminance state (in Lux)
+- New: Shutter Control II BlindsControl state for controlling the angle of blinds
+- New: Shutter Control II BlindsSceneControl state for controlling the angle and level of blinds at the same time
+- Hint: Light / Shutter Control II works with child devices using "#" in the device IDs; make sure to escape "#" in URLs with "%23"
+- Hint: Light Control II can control two lamps (two child devices); PowerSwitch state must be PUT/GET on child devices
+- Hint: PowerMeter state also works with Light / Shutter Control II now
+
 ## [2.1.0] - 2021-01-22
 ### Changed
 - Updated HTTP request header to use "api-version : 2.1" instead of "api-version : 1.0"

best_practice/README.md

@@ -8,7 +8,6 @@ First of all, watch this repository to get notified when we change or update our
 In order to get notified as soon as a value changes, it is recommended to use the [Long Polling mechanism to receive events](https://github.com/BoschSmartHome/bosch-shc-api-docs/tree/master/postman#get-events-from-the-bosch-smart-home-controller-long-polling) (see Postman collection 'Long Polling Subscribe'). Long Polling is a mechanism in which the client makes a request, and the server keeps the connection open until there is new information available. Once available, the server responds by sending the new information to the client and closes the connection afterwards. As soon as the client receives the new information, it immediately sends another request and the process is repeated. This mechanism also ensures that you do not miss any events, because the Bosch Smart Home Controller keeps all information for the client until the client starts another Long Polling request.
 Please be aware that every subscription has a maximum age of 24 hours and an inactivity timeout of 5 minutes, i.e. a new subscription has to be requested if a subscription ID is either used for 24 hours or no long-poll request was sent for 5 minutes. A long-poll request will fail after the corresponding subscription ID has expired. Re-subscribing and then using the new subscription ID solves this.
 
-
 ### Limit the number of requests in a given time period
 In addition to the use of the Long Polling mechanism, it is also advisable to keep the number of requests in a given time period low. The number of requests the Bosch Smart Home Controller can process depends heavily on how many edge devices and clients are paired with it. 
 

postman/Bosch Smart Home Controller.postman_collection.json

@@ -1,9 +1,8 @@
 {
 	"info": {
-		"_postman_id": "9b248bc3-c5b9-41e5-b21c-82f225bb9c3c",
+		"_postman_id": "e9ef2cd5-d80f-45f5-a2bd-47cb327fff19",
 		"name": "Bosch Smart Home Controller",
 		"description": "This API enables you to locally access the state of and control your Bosch Smart Home system. Configuring the system is not supported.",
-		"version": "2.1",
 		"schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json"
 	},
 	"item": [
@@ -934,7 +933,18 @@
 					"response": []
 				},
 				{
-					"name": "DEPRECATED: Intrusion Detection System state",
+					"name": "Door/Window Contact II Bypass state",
+					"event": [
+						{
+							"listen": "prerequest",
+							"script": {
+								"exec": [
+									""
+								],
+								"type": "text/javascript"
+							}
+						}
+					],
 					"request": {
 						"method": "GET",
 						"header": [
@@ -950,96 +960,109 @@
 							}
 						],
 						"url": {
-							"raw": "{{shc_api}}/devices/intrusionDetectionSystem/services/IntrusionDetectionControl/state",
+							"raw": "{{shc_api}}/devices/{{device_id}}/services/Bypass/state",
 							"host": [
 								"{{shc_api}}"
 							],
 							"path": [
 								"devices",
-								"intrusionDetectionSystem",
+								"{{device_id}}",
 								"services",
-								"IntrusionDetectionControl",
+								"Bypass",
 								"state"
 							]
-						},
-						"description": "This will be removed in the future. Use 'Domains/Intrusion Detection/System state' request instead."
+						}
 					},
 					"response": []
 				},
 				{
-					"name": "DEPRECATED: Intrusion Detection System SYSTEM_ARMED",
+					"name": "Door/Window Contact II Plus Vibration state",
+					"event": [
+						{
+							"listen": "prerequest",
+							"script": {
+								"exec": [
+									""
+								],
+								"type": "text/javascript"
+							}
+						}
+					],
 					"request": {
-						"method": "PUT",
+						"method": "GET",
 						"header": [
 							{
 								"key": "Content-Type",
-								"value": "application/json"
+								"value": "application/json",
+								"type": "text"
 							},
 							{
 								"key": "api-version",
 								"value": "{{api_version}}",
 								"type": "text"
 							}
 						],
-						"body": {
-							"mode": "raw",
-							"raw": "{\r\n    \"@type\": \"intrusionDetectionControlState\",\r\n    \"value\": \"SYSTEM_ARMED\"\r\n}"
-						},
 						"url": {
-							"raw": "{{shc_api}}/devices/intrusionDetectionSystem/services/IntrusionDetectionControl/state",
+							"raw": "{{shc_api}}/devices/{{device_id}}/services/VibrationSensor/state",
 							"host": [
 								"{{shc_api}}"
 							],
 							"path": [
 								"devices",
-								"intrusionDetectionSystem",
+								"{{device_id}}",
 								"services",
-								"IntrusionDetectionControl",
+								"VibrationSensor",
 								"state"
 							]
-						},
-						"description": "This will be removed in the future. Use 'Domains/Intrusion Detection/Arm with ...' requests instead."
+						}
 					},
 					"response": []
 				},
 				{
-					"name": "DEPRECATED: Intrusion Detection System SYSTEM_DISARMED",
+					"name": "Motion Detector state",
+					"event": [
+						{
+							"listen": "prerequest",
+							"script": {
+								"exec": [
+									""
+								],
+								"type": "text/javascript"
+							}
+						}
+					],
 					"request": {
-						"method": "PUT",
+						"method": "GET",
 						"header": [
 							{
 								"key": "Content-Type",
-								"value": "application/json"
+								"value": "application/json",
+								"type": "text"
 							},
 							{
 								"key": "api-version",
 								"value": "{{api_version}}",
 								"type": "text"
 							}
 						],
-						"body": {
-							"mode": "raw",
-							"raw": "{\r\n    \"@type\": \"intrusionDetectionControlState\",\r\n    \"value\": \"SYSTEM_DISARMED\"\r\n}"
-						},
 						"url": {
-							"raw": "{{shc_api}}/devices/intrusionDetectionSystem/services/IntrusionDetectionControl/state",
+							"raw": "{{shc_api}}/devices/{{device_id}}/services/LatestMotion/state",
 							"host": [
 								"{{shc_api}}"
 							],
 							"path": [
 								"devices",
-								"intrusionDetectionSystem",
+								"{{device_id}}",
 								"services",
-								"IntrusionDetectionControl",
+								"LatestMotion",
 								"state"
 							]
-						},
-						"description": "This will be removed in the future. Use 'Domains/Intrusion Detection/Disarm' request instead."
+						}
 					},
 					"response": []
 				},
 				{
-					"name": "Motion Detector state",
+					"name": "Motion Detector Illuminance state",
 					"event": [
 						{
 							"listen": "prerequest",
@@ -1066,23 +1089,23 @@
 							}
 						],
 						"url": {
-							"raw": "{{shc_api}}/devices/{{device_id}}/services/LatestMotion/state",
+							"raw": "{{shc_api}}/devices/{{device_id}}/services/MultiLevelSensor/state",
 							"host": [
 								"{{shc_api}}"
 							],
 							"path": [
 								"devices",
 								"{{device_id}}",
 								"services",
-								"LatestMotion",
+								"MultiLevelSensor",
 								"state"
 							]
 						}
 					},
 					"response": []
 				},
 				{
-					"name": "PowerMeter state (Smart Plug / Light Control)",
+					"name": "PowerMeter state (Smart Plug / Light Control / Shutter Control II)",
 					"event": [
 						{
 							"listen": "prerequest",
@@ -1644,6 +1667,143 @@
 					},
 					"response": []
 				},
+				{
+					"name": "Shutter Control II BlindsControl state",
+					"event": [
+						{
+							"listen": "prerequest",
+							"script": {
+								"exec": [
+									""
+								],
+								"type": "text/javascript"
+							}
+						}
+					],
+					"request": {
+						"method": "GET",
+						"header": [
+							{
+								"key": "Content-Type",
+								"value": "application/json",
+								"type": "text"
+							},
+							{
+								"key": "api-version",
+								"value": "{{api_version}}",
+								"type": "text"
+							}
+						],
+						"url": {
+							"raw": "{{shc_api}}/devices/{{device_id}}/services/BlindsControl/state",
+							"host": [
+								"{{shc_api}}"
+							],
+							"path": [
+								"devices",
+								"{{device_id}}",
+								"services",
+								"BlindsControl",
+								"state"
+							]
+						}
+					},
+					"response": []
+				},
+				{
+					"name": "Shutter Control II BlindsControl state",
+					"event": [
+						{
+							"listen": "prerequest",
+							"script": {
+								"exec": [
+									""
+								],
+								"type": "text/javascript"
+							}
+						}
+					],
+					"request": {
+						"method": "PUT",
+						"header": [
+							{
+								"key": "Content-Type",
+								"value": "application/json",
+								"type": "text"
+							},
+							{
+								"key": "api-version",
+								"value": "{{api_version}}",
+								"type": "text"
+							}
+						],
+						"body": {
+							"mode": "raw",
+							"raw": "{\r\n    \"@type\": \"blindsControlState\",\r\n    \"targetAngle\": 1.0\r\n}"
+						},
+						"url": {
+							"raw": "{{shc_api}}/devices/{{device_id}}/services/BlindsControl/state",
+							"host": [
+								"{{shc_api}}"
+							],
+							"path": [
+								"devices",
+								"{{device_id}}",
+								"services",
+								"BlindsControl",
+								"state"
+							]
+						}
+					},
+					"response": []
+				},
+				{
+					"name": "Shutter Control II BlindsSceneControl state",
+					"event": [
+						{
+							"listen": "prerequest",
+							"script": {
+								"exec": [
+									""
+								],
+								"type": "text/javascript"
+							}
+						}
+					],
+					"request": {
+						"method": "PUT",
+						"header": [
+							{
+								"key": "Content-Type",
+								"value": "application/json",
+								"type": "text"
+							},
+							{
+								"key": "api-version",
+								"value": "{{api_version}}",
+								"type": "text"
+							}
+						],
+						"body": {
+							"mode": "raw",
+							"raw": "{\r\n    \"@type\": \"blindsSceneControlState\",\r\n    \"level\": 1.0,\r\n    \"angle\": 1.0\r\n}"
+						},
+						"url": {
+							"raw": "{{shc_api}}/devices/{{device_id}}/services/BlindsSceneControl/state",
+							"host": [
+								"{{shc_api}}"
+							],
+							"path": [
+								"devices",
+								"{{device_id}}",
+								"services",
+								"BlindsSceneControl",
+								"state"
+							]
+						}
+					},
+					"response": []
+				},
 				{
 					"name": "Twinguard state",
 					"event": [