Skip to main content

Bosch Smart Home Controller API Python Library

Project description

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.

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.
pip install boschshcpy

Registering a new client

To register a new client, use the script boschshc_registerclient:

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

Rawscans

To make a rawscan of your devices, use the script boschshc_rawscan

Make a rawscan of the public information

boschshc_rawscan -ip _your_shc_ip_ -cert _your_shc_cert_file_ -key _your_shc_key_file_ public_information

Make a rawscan of all devices

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

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:

    {
        "@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

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:

[
    {
        "@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

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

boschshc_rawscan -ip _your_shc_ip_ -cert _your_shc_cert_file_ -key _your_shc_key_file_ scenarios

Make a rawscan of the all rooms

boschshc_rawscan -ip _your_shc_ip_ -cert _your_shc_cert_file_ -key _your_shc_key_file_ rooms

Example code to use the boschshcpy library

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.

Project details


Release history Release notifications | RSS feed

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

boschshcpy-0.2.83.tar.gz (33.1 kB view details)

Uploaded Source

Built Distribution

boschshcpy-0.2.83-py3-none-any.whl (35.6 kB view details)

Uploaded Python 3

File details

Details for the file boschshcpy-0.2.83.tar.gz.

File metadata

  • Download URL: boschshcpy-0.2.83.tar.gz
  • Upload date:
  • Size: 33.1 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/4.0.2 CPython/3.11.6

File hashes

Hashes for boschshcpy-0.2.83.tar.gz
Algorithm Hash digest
SHA256 0ee157c8eefe1229ef798c0cfd5e6998a6e6c60f617ebf3adea796fe1070f6d9
MD5 1672412c526a8da384a8d4f32a14c0e4
BLAKE2b-256 56b2a51b8c8552de8a4bc5a4fcf601d0ee7e98a54d018bb60829095740fa0220

See more details on using hashes here.

File details

Details for the file boschshcpy-0.2.83-py3-none-any.whl.

File metadata

  • Download URL: boschshcpy-0.2.83-py3-none-any.whl
  • Upload date:
  • Size: 35.6 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/4.0.2 CPython/3.11.6

File hashes

Hashes for boschshcpy-0.2.83-py3-none-any.whl
Algorithm Hash digest
SHA256 cec02c5ef0337625bbb70e6a6732b63f674fa7f8f28ef62450aa67df2b5834c3
MD5 c396deef1b16f4d13b60e73998a97b26
BLAKE2b-256 b35e97f087b097bdfdc5e976b22be891f31e073cb461c189dd30e2425277db00

See more details on using hashes here.

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page