# Bosch Smart Home Controller API Python Library
This library implements the local communication REST API for the Bosch Smart Home Controller system. It supports both long and short polling. The API documentation is available [here](https://github.com/BoschSmartHome/bosch-shc-api-docs).
The following device services are implemented:
* ```TemperatureLevel```
* ```HumidityLevel```
* ```RoomClimateControl```
* ```ShutterContact```
* ```ValveTappet```
* ```PowerSwitch```
* ```PowerMeter```
* ```Routing```
* ```PowerSwitchProgram```
* ```PresenceSimulationConfiguration```
* ```BinarySwitch```
* ```SmokeDetectorCheck```
* ```Alarm```
* ```ShutterControl```
* ```CameraLight```
* ```PrivacyMode```
* ```CameraNotification```
* ```IntrusionDetectionControl```
* ```Keypad```
* ```LatestMotion```
* ```AirQualityLevel```
* ```SurveillanceAlarm```
* ```BatteryLevel```
* ```Thermostat```
* ```WaterLeakageSensor```
* ```WaterLeakageSensorTilt```
* and more
The following device models are implemented, using the above services:
* ```ShutterContact```, ```ShutterContact2```
* ```ShutterControl```, ```Micromodule Shutter```
* ```SmartPlug```
* ```SmartPlugCompact```
* ```LightControl```, ```Micromodule Light Control```, ```Micromodule Light Attached```, ```Micromodule Relay```
* ```SmokeDetector```
* ```CameraEyes```, ```Camera360```
* ```IntrusionDetectionSystem```
* ```RoomClimateControl```
* ```Thermostat```, ```Thermostat2```
* ```WallThermostat```
* ```UniversalSwitch```
* ```MotionDetector```
* ```PresenceSimulationSystem```
* ```Twinguard```
* ```WaterLeakageSensor```
## Command line access to SHC
1. Install a `python` (>=3.10) environment on your computer.
2. Install latest version of `boschshcpy`, you should have at least `version>=0.2.45`.
```bash
pip install boschshcpy
```
### Registering a new client
To register a new client, use the script `boschshc_registerclient`:
```bash
boschshc_registerclient -ip _your_shc_ip_ -pw _your_shc_password_
```
This will register your client and will write the associated certificate/key pair into your working directory. See also [Usage Guide](#usage-guide)
### Rawscans
To make a rawscan of your devices, use the script `boschshc_rawscan`
#### Make a rawscan of the public information
```bash
boschshc_rawscan -ip _your_shc_ip_ -cert _your_shc_cert_file_ -key _your_shc_key_file_ public_information
```
#### Make a rawscan of all devices
```bash
boschshc_rawscan -ip _your_shc_ip_ -cert _your_shc_cert_file_ -key _your_shc_key_file_ devices
```
#### Make a rawscan of a single device with a known `device_id`
```bash
boschshc_rawscan -ip _your_shc_ip_ -cert _your_shc_cert_file_ -key _your_shc_key_file_ device _your_device_id_
```
An exemplary output looks as follows:
```bash
{
"@type": "device",
"rootDeviceId": "xx-xx-xx-xx-xx-xx",
"id": "hdm:HomeMaticIP:30xxx",
"deviceServiceIds": [
"Thermostat",
"BatteryLevel",
"ValveTappet",
"SilentMode",
"TemperatureLevel",
"Linking",
"TemperatureOffset"
],
"manufacturer": "BOSCH",
"roomId": "hz_8",
"deviceModel": "TRV",
"serial": "30xxx",
"profile": "GENERIC",
"name": "Test Thermostat",
"status": "AVAILABLE",
"parentDeviceId": "roomClimateControl_hz_8",
"childDeviceIds": []
},
```
#### Make a rawscan of the associated services of a device
```bash
boschshc_rawscan -ip _your_shc_ip_ -cert _your_shc_cert_file_ -key _your_shc_key_file_ device_services _your_device_id_
```
The exemplary output will look as follows:
```bash
[
{
"@type": "DeviceServiceData",
"id": "BatteryLevel",
"deviceId": "hdm:HomeMaticIP:30xxx",
"path": "/devices/hdm:HomeMaticIP:30xxx/services/BatteryLevel"
},
{
"@type": "DeviceServiceData",
"id": "Thermostat",
"deviceId": "hdm:HomeMaticIP:30xxx",
"state": {
"@type": "childLockState",
"childLock": "OFF"
},
"path": "/devices/hdm:HomeMaticIP:30xxx/services/Thermostat"
},
...
]
```
#### Make a rawscan of the a service of a device, where the `device_id` as well as the `service_id` are known
```bash
boschshc_rawscan -ip _your_shc_ip_ -cert _your_shc_cert_file_ -key _your_shc_key_file_ device_service _your_device_id_ _your_service_id
```
#### Make a rawscan of the all scenarios
```bash
boschshc_rawscan -ip _your_shc_ip_ -cert _your_shc_cert_file_ -key _your_shc_key_file_ scenarios
```
#### Make a rawscan of the all rooms
```bash
boschshc_rawscan -ip _your_shc_ip_ -cert _your_shc_cert_file_ -key _your_shc_key_file_ rooms
```
## Example code to use the `boschshcpy` library
```python
import boschshcpy
# Create session
session = boschshcpy.SHCSession(controller_ip="192.168.25.51", certificate='cert.pem', key='key.pem')
session.information.summary()
device = session.device('roomClimateControl_hz_5')
service = device.device_service('TemperatureLevel')
print(service.temperature)
# Update this service's state
service.short_poll()
# Start long polling thread in background
session.start_polling()
# Do work here
...
# Stop polling
session.stop_polling()
# Trigger intrusion detection system
intrusion_control = session.intrusion_system
intrusion_control.arm()
# Get rawscan of devices
scan_result = session.rawscan(command="devices")
```
## Usage guide
Before accessing the Bosch Smart Home Controller, a client must be registered on the controller. For this a valid cert/key pair must be provided to the controller. To start the client registration, press and hold the button on the controller until the led starts flashing. More information [here](https://github.com/BoschSmartHome/bosch-shc-api-docs/tree/master/postman#register-a-new-client-to-the-bosch-smart-home-controller).
Raw data
{
"_id": null,
"home_page": "https://github.com/tschamm/boschshcpy",
"name": "boschshcpy",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.10, <4",
"maintainer_email": "",
"keywords": "boschshcpy",
"author": "Clemens-Alexander Brust, Thomas Schamm",
"author_email": "cabrust@pm.me, thomas@tschamm.de",
"download_url": "https://files.pythonhosted.org/packages/59/bc/60e0edb41baff9166df33bfd48238f2c5b44ef36d355abba8051584956bc/boschshcpy-0.2.91.tar.gz",
"platform": null,
"description": "# Bosch Smart Home Controller API Python Library\n\nThis library implements the local communication REST API for the Bosch Smart Home Controller system. It supports both long and short polling. The API documentation is available [here](https://github.com/BoschSmartHome/bosch-shc-api-docs).\n\nThe following device services are implemented:\n\n* ```TemperatureLevel```\n* ```HumidityLevel```\n* ```RoomClimateControl```\n* ```ShutterContact```\n* ```ValveTappet```\n* ```PowerSwitch```\n* ```PowerMeter```\n* ```Routing```\n* ```PowerSwitchProgram```\n* ```PresenceSimulationConfiguration```\n* ```BinarySwitch```\n* ```SmokeDetectorCheck```\n* ```Alarm```\n* ```ShutterControl```\n* ```CameraLight```\n* ```PrivacyMode```\n* ```CameraNotification```\n* ```IntrusionDetectionControl```\n* ```Keypad```\n* ```LatestMotion```\n* ```AirQualityLevel```\n* ```SurveillanceAlarm```\n* ```BatteryLevel```\n* ```Thermostat```\n* ```WaterLeakageSensor```\n* ```WaterLeakageSensorTilt```\n* and more\n\nThe following device models are implemented, using the above services:\n\n* ```ShutterContact```, ```ShutterContact2```\n* ```ShutterControl```, ```Micromodule Shutter```\n* ```SmartPlug```\n* ```SmartPlugCompact```\n* ```LightControl```, ```Micromodule Light Control```, ```Micromodule Light Attached```, ```Micromodule Relay```\n* ```SmokeDetector```\n* ```CameraEyes```, ```Camera360```\n* ```IntrusionDetectionSystem```\n* ```RoomClimateControl```\n* ```Thermostat```, ```Thermostat2```\n* ```WallThermostat```\n* ```UniversalSwitch```\n* ```MotionDetector```\n* ```PresenceSimulationSystem```\n* ```Twinguard```\n* ```WaterLeakageSensor```\n\n## Command line access to SHC\n1. Install a `python` (>=3.10) environment on your computer.\n2. Install latest version of `boschshcpy`, you should have at least `version>=0.2.45`.\n```bash\npip install boschshcpy\n```\n\n### Registering a new client\n\nTo register a new client, use the script `boschshc_registerclient`:\n```bash\nboschshc_registerclient -ip _your_shc_ip_ -pw _your_shc_password_\n```\n\nThis will register your client and will write the associated certificate/key pair into your working directory. See also [Usage Guide](#usage-guide)\n\n### Rawscans\n\nTo make a rawscan of your devices, use the script `boschshc_rawscan`\n\n#### Make a rawscan of the public information\n```bash\nboschshc_rawscan -ip _your_shc_ip_ -cert _your_shc_cert_file_ -key _your_shc_key_file_ public_information\n```\n\n#### Make a rawscan of all devices\n```bash\nboschshc_rawscan -ip _your_shc_ip_ -cert _your_shc_cert_file_ -key _your_shc_key_file_ devices\n```\n\n#### Make a rawscan of a single device with a known `device_id`\n```bash\nboschshc_rawscan -ip _your_shc_ip_ -cert _your_shc_cert_file_ -key _your_shc_key_file_ device _your_device_id_\n```\n\nAn exemplary output looks as follows:\n```bash\n {\n \"@type\": \"device\",\n \"rootDeviceId\": \"xx-xx-xx-xx-xx-xx\",\n \"id\": \"hdm:HomeMaticIP:30xxx\",\n \"deviceServiceIds\": [\n \"Thermostat\",\n \"BatteryLevel\",\n \"ValveTappet\",\n \"SilentMode\",\n \"TemperatureLevel\",\n \"Linking\",\n \"TemperatureOffset\"\n ],\n \"manufacturer\": \"BOSCH\",\n \"roomId\": \"hz_8\",\n \"deviceModel\": \"TRV\",\n \"serial\": \"30xxx\",\n \"profile\": \"GENERIC\",\n \"name\": \"Test Thermostat\",\n \"status\": \"AVAILABLE\",\n \"parentDeviceId\": \"roomClimateControl_hz_8\",\n \"childDeviceIds\": []\n },\n```\n\n#### Make a rawscan of the associated services of a device\n```bash\nboschshc_rawscan -ip _your_shc_ip_ -cert _your_shc_cert_file_ -key _your_shc_key_file_ device_services _your_device_id_\n```\n\nThe exemplary output will look as follows:\n```bash\n[\n {\n \"@type\": \"DeviceServiceData\",\n \"id\": \"BatteryLevel\",\n \"deviceId\": \"hdm:HomeMaticIP:30xxx\",\n \"path\": \"/devices/hdm:HomeMaticIP:30xxx/services/BatteryLevel\"\n },\n {\n \"@type\": \"DeviceServiceData\",\n \"id\": \"Thermostat\",\n \"deviceId\": \"hdm:HomeMaticIP:30xxx\",\n \"state\": {\n \"@type\": \"childLockState\",\n \"childLock\": \"OFF\"\n },\n \"path\": \"/devices/hdm:HomeMaticIP:30xxx/services/Thermostat\"\n },\n...\n]\n```\n\n#### Make a rawscan of the a service of a device, where the `device_id` as well as the `service_id` are known\n```bash\nboschshc_rawscan -ip _your_shc_ip_ -cert _your_shc_cert_file_ -key _your_shc_key_file_ device_service _your_device_id_ _your_service_id\n```\n\n#### Make a rawscan of the all scenarios\n```bash\nboschshc_rawscan -ip _your_shc_ip_ -cert _your_shc_cert_file_ -key _your_shc_key_file_ scenarios\n```\n\n#### Make a rawscan of the all rooms\n```bash\nboschshc_rawscan -ip _your_shc_ip_ -cert _your_shc_cert_file_ -key _your_shc_key_file_ rooms\n```\n\n## Example code to use the `boschshcpy` library\n\n```python\nimport boschshcpy\n\n# Create session\nsession = boschshcpy.SHCSession(controller_ip=\"192.168.25.51\", certificate='cert.pem', key='key.pem')\nsession.information.summary()\n\ndevice = session.device('roomClimateControl_hz_5')\nservice = device.device_service('TemperatureLevel')\nprint(service.temperature)\n\n# Update this service's state\nservice.short_poll()\n\n# Start long polling thread in background\nsession.start_polling()\n\n# Do work here\n...\n\n# Stop polling\nsession.stop_polling()\n\n# Trigger intrusion detection system\nintrusion_control = session.intrusion_system\nintrusion_control.arm()\n\n# Get rawscan of devices\nscan_result = session.rawscan(command=\"devices\")\n```\n\n## Usage guide\n\nBefore accessing the Bosch Smart Home Controller, a client must be registered on the controller. For this a valid cert/key pair must be provided to the controller. To start the client registration, press and hold the button on the controller until the led starts flashing. More information [here](https://github.com/BoschSmartHome/bosch-shc-api-docs/tree/master/postman#register-a-new-client-to-the-bosch-smart-home-controller).\n",
"bugtrack_url": null,
"license": "bsd-3-clause",
"summary": "Bosch Smart Home Controller API Python Library",
"version": "0.2.91",
"project_urls": {
"Bug Reports": "https://github.com/tschamm/boschshcpy/issues",
"Homepage": "https://github.com/tschamm/boschshcpy",
"Source": "https://github.com/tschamm/boschshcpy"
},
"split_keywords": [
"boschshcpy"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "6af0b77cdf2deeac7689f162271bfb43b577368407261d9108d226d0c5943a6f",
"md5": "44e559d1dbe6c7531dfa4dc8ef29c8a0",
"sha256": "c88f278586324bee3a21702febbe73699b998ea544e781174c889d91265dbfe1"
},
"downloads": -1,
"filename": "boschshcpy-0.2.91-py3-none-any.whl",
"has_sig": false,
"md5_digest": "44e559d1dbe6c7531dfa4dc8ef29c8a0",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10, <4",
"size": 35429,
"upload_time": "2024-02-15T17:24:36",
"upload_time_iso_8601": "2024-02-15T17:24:36.788631Z",
"url": "https://files.pythonhosted.org/packages/6a/f0/b77cdf2deeac7689f162271bfb43b577368407261d9108d226d0c5943a6f/boschshcpy-0.2.91-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "59bc60e0edb41baff9166df33bfd48238f2c5b44ef36d355abba8051584956bc",
"md5": "72c729116ed05b6d9351e1156fbed377",
"sha256": "9a8d65152ba5f396d2c11520f9bdfd2a831471d6f4f2d10107e6a5c3990b6752"
},
"downloads": -1,
"filename": "boschshcpy-0.2.91.tar.gz",
"has_sig": false,
"md5_digest": "72c729116ed05b6d9351e1156fbed377",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10, <4",
"size": 32741,
"upload_time": "2024-02-15T17:24:40",
"upload_time_iso_8601": "2024-02-15T17:24:40.168980Z",
"url": "https://files.pythonhosted.org/packages/59/bc/60e0edb41baff9166df33bfd48238f2c5b44ef36d355abba8051584956bc/boschshcpy-0.2.91.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-02-15 17:24:40",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "tschamm",
"github_project": "boschshcpy",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "boschshcpy"
}
JSON
