Bosch Smart Home Controller API Python Library
Python client library for the Bosch Smart Home Controller (SHC) local REST API. Communicates directly with the controller over mutual-TLS on the local network — no cloud, no Bosch account required. The official API documentation is available at github.com/BoschSmartHome/bosch-shc-api-docs.
Contents
- Quick start
- Architecture
- Install
- Supported device services
- Supported device models
- Usage
- Rawscans
- Maintainers & support
Quick start
1 — Install
pip install boschshcpy
2 — Register a client certificate
Press and hold the SHC front button until the LED flashes (registration mode, ~10 s), then:
boschshc_registerclient -ip 192.168.x.x -pw YOUR_SHC_PASSWORD
This writes cert.pem and key.pem to the working directory.
3 — Use the session
import boschshcpy
session = boschshcpy.SHCSession("192.168.x.x", "cert.pem", "key.pem")
session.information.summary()
session.start_polling() # starts long-poll thread; callbacks fire on state change
# ... your code ...
session.stop_polling()
For asyncio / Home Assistant usage see the async example below.
Architecture
graph TD
APP("Your code\nSHCSession / SHCSessionAsync")
DH("SHCDeviceHelper\ntyped device accessors")
DS("SHCDeviceService\nstate + event callbacks")
RA("SHCAPI / SHCAPIAsync\nHTTP + mTLS client")
SHC("Bosch SHC II")
APP --> DH
DH --> DS
DS --> RA
RA -->|"REST port 8444"| SHC
SHC -->|"long-poll port 8446"| RA
Sync path (SHCSession + SHCAPI): blocking requests/urllib3 calls. Uses a dedicated SHCPollingThread for the long-poll subscription — callbacks fire from that thread. Suitable for scripts and simple consumers.
Async path (SHCSessionAsync + SHCAPIAsync): fully asyncio-native with aiohttp. Used by the boschshc-hass Home Assistant integration. All write methods are async def async_* coroutines.
Install
Requires Python ≥ 3.10.
pip install boschshcpy
Current PyPI version: 0.3.20
Supported device services
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, HeatingCircuit, PirSensorConfiguration,
SmartSensitivityControl, DetectionTest, WalkTest, LatestTamper, PollControl,
PetImmunity, OccupancyDetection, MultiLevelSwitch, and more
Supported device models
| Model key | Description |
|---|---|
SWD / SWD2 / SWD2_PLUS / SWD2_DUAL |
Shutter Contact Gen 1 + Gen 2 (incl. 2 Plus, Dual) |
BBL |
Shutter Control |
MICROMODULE_SHUTTER / MICROMODULE_AWNING |
Micromodule Shutter / Awning |
MICROMODULE_BLINDS |
Micromodule Blinds (with tilt) |
PSM |
Smart Plug |
PLUG_COMPACT / PLUG_COMPACT_DUAL |
Smart Plug Compact |
BSM |
Light Switch BSM |
MICROMODULE_LIGHT_CONTROL / MICROMODULE_LIGHT_ATTACHED |
Micromodule Light Control / Attached |
MICROMODULE_RELAY |
Micromodule Relay (switch and impulse types) |
MICROMODULE_DIMMER |
Micromodule Dimmer |
SD / SMOKE_DETECTOR2 |
Smoke Detector Gen 1 + Gen 2 |
SMOKE_DETECTION_SYSTEM |
Smoke Detection System |
CAMERA_EYES |
Camera Eyes |
CAMERA_360 |
Camera 360 |
CAMERA_OUTDOOR_GEN2 |
Camera Outdoor Gen 2 |
ROOM_CLIMATE_CONTROL |
Room Climate Control (thermostat group) |
HEATING_CIRCUIT |
Heating Circuit |
TRV / TRV_GEN2 / TRV_GEN2_DUAL |
Thermostat (Radiator Valve) Gen 1 + Gen 2 |
THB / BWTH / BWTH24 |
Wall Thermostat |
RTH2_BAT / RTH2_230 |
Room Thermostat 2 |
WRC2 / SWITCH2 |
Universal Switch |
MD / MD2 |
Motion Detector Gen 1 + Gen 2 [+M] |
PRESENCE_SIMULATION_SERVICE |
Presence Simulation System |
TWINGUARD |
Twinguard (smoke + air quality) |
WLS |
Water Leakage Sensor |
LEDVANCE_LIGHT / HUE_LIGHT |
LEDVANCE / Hue lights (via SHC) |
Usage
Register a new client
Press and hold the button on the SHC controller until the LED starts flashing (registration mode). Then run:
boschshc_registerclient -ip YOUR_SHC_IP -pw YOUR_SHC_PASSWORD
This writes a certificate/key pair (cert.pem / key.pem) to the working directory.
More details: Bosch API docs — register a client
Python API (sync)
import boschshcpy
# Create session (lazy=False enumerates all devices on connect)
session = boschshcpy.SHCSession(
controller_ip="192.168.25.51",
certificate="cert.pem",
key="key.pem",
)
session.information.summary()
# Access a device and service
device = session.device("roomClimateControl_hz_5")
service = device.device_service("TemperatureLevel")
print(service.temperature)
# Short-poll a single service
service.short_poll()
# Writing to a service — every writable service field has a setter.
# Sync property setter, or an async_set_* coroutine for the event loop:
device.multi_level_switch = 50 # sync write (PUT to the service)
await device.async_set_multi_level_switch(50)
# Motion Detector II examples (services the SHC exposes for the MD2 [+M]):
from boschshcpy.services_impl import DetectionTestService, PollControlService
md2 = session.device_helper.motion_detectors2[0]
md2.set_detection_state_request( # start a walk/detection test
DetectionTestService.DetectionStateRequest.DETECTION_STATE_START)
md2.tamper_protection_enabled = True # toggle tamper protection
md2.reset_tampered_state() # POST resetTamperedState
md2.long_poll_interval = PollControlService.PollControlState.SHORT # orientation-light response
print(md2.profile, md2.supported_profiles) # installation profile (read-only)
# Start long-poll thread (non-blocking)
session.start_polling()
# ... do work, handle callbacks ...
# Stop polling
session.stop_polling()
# Arm the intrusion detection system
session.intrusion_system.arm()
# Raw API dump
scan_result = session.rawscan(command="devices")
Python API (async / aiohttp)
import asyncio
import boschshcpy
async def main():
session = boschshcpy.SHCSessionAsync(
controller_ip="192.168.25.51",
certificate="cert.pem",
key="key.pem",
)
async with session:
for device in session.device_helper.smart_plugs:
await device.async_set_state(True) # turn on
asyncio.run(main())
Device helper accessors (SHCSession.device_helper)
SHCDeviceHelper exposes typed properties for each device category:
shutter_contacts, shutter_contacts2, shutter_controls,
micromodule_shutter_controls, micromodule_blinds, micromodule_relays,
micromodule_impulse_relays, micromodule_light_controls,
micromodule_light_attached, micromodule_dimmers, light_switches_bsm,
smart_plugs, smart_plugs_compact, smoke_detectors, smoke_detection_system,
climate_controls, heating_circuits, thermostats, wallthermostats,
roomthermostats, motion_detectors, motion_detectors2, twinguards,
universal_switches, camera_eyes, camera_360, camera_outdoor_gen2,
ledvance_lights, hue_lights, water_leakage_detectors,
presence_simulation_system
Other session attributes: session.scenarios, session.rooms, session.intrusion_system,
session.emma (EMMA grid power).
Rawscans (command-line)
Public information
boschshc_rawscan -ip YOUR_SHC_IP -cert cert.pem -key key.pem public_information
All devices
boschshc_rawscan -ip YOUR_SHC_IP -cert cert.pem -key key.pem devices
Single device
boschshc_rawscan -ip YOUR_SHC_IP -cert cert.pem -key key.pem device YOUR_DEVICE_ID
Services of a device
boschshc_rawscan -ip YOUR_SHC_IP -cert cert.pem -key key.pem device_services YOUR_DEVICE_ID
Single service of a device
boschshc_rawscan -ip YOUR_SHC_IP -cert cert.pem -key key.pem device_service YOUR_DEVICE_ID YOUR_SERVICE_ID
All scenarios
boschshc_rawscan -ip YOUR_SHC_IP -cert cert.pem -key key.pem scenarios
All rooms
boschshc_rawscan -ip YOUR_SHC_IP -cert cert.pem -key key.pem rooms
Example device output:
{
"@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",
"name": "Test Thermostat",
"status": "AVAILABLE"
}
Maintainers / support
| Role | |
|---|---|
| Original authors | Clemens-Alexander Brust (@cabrust), Thomas Schamm (@tschamm) |
| Co-maintainer | Thomas Mosandl (@mosandlt) |
Bug reports and feature requests: github.com/tschamm/boschshcpy/issues
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.4.4.tar.gz
(221.7 kB
view details)
Built Distribution
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
File details
Details for the file boschshcpy-0.4.4.tar.gz.
File metadata
- Download URL: boschshcpy-0.4.4.tar.gz
- Upload date:
- Size: 221.7 kB
- Tags: Source
- Uploaded using Trusted Publishing? Yes
- Uploaded via:
twine/6.1.0 CPython/3.13.12
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
76d64909dd4ca4c5c957daecb4e110fe44500f6b9207c1204c645733997651cd
|
|
| MD5 |
00a002ebe2821582d0e3f829ce57e68f
|
|
| BLAKE2b-256 |
c4aa04090d224711cbddcf4c4dc941a724817fc85ebcd6bc4481520d9fd906d0
|
Provenance
The following attestation bundles were made for boschshcpy-0.4.4.tar.gz:
Publisher:
publish.yml on tschamm/boschshcpy
-
Statement:
-
Statement type:
https://in-toto.io/Statement/v1 -
Predicate type:
https://docs.pypi.org/attestations/publish/v1 -
Subject name:
boschshcpy-0.4.4.tar.gz -
Subject digest:
76d64909dd4ca4c5c957daecb4e110fe44500f6b9207c1204c645733997651cd - Sigstore transparency entry: 2032176442
- Sigstore integration time:
-
Permalink:
tschamm/boschshcpy@1ba20a7d6124099ab424e43f1c60ab55caeacd6f -
Branch / Tag:
refs/tags/v0.4.4 - Owner: https://github.com/tschamm
-
Access:
public
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
publish.yml@1ba20a7d6124099ab424e43f1c60ab55caeacd6f -
Trigger Event:
push
-
Statement type:
File details
Details for the file boschshcpy-0.4.4-py3-none-any.whl.
File metadata
- Download URL: boschshcpy-0.4.4-py3-none-any.whl
- Upload date:
- Size: 82.6 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? Yes
- Uploaded via:
twine/6.1.0 CPython/3.13.12
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
f6eac7cb3e7e09400982768861c7de277d81973bc81cfb38d5a5bbdf33161180
|
|
| MD5 |
2d71d9aeb27f75172574ca9a34a5536c
|
|
| BLAKE2b-256 |
80de245a0b28c490bfcf1473ce6d59b8213bdf71056f0bb77e9e69d158863ba6
|
Provenance
The following attestation bundles were made for boschshcpy-0.4.4-py3-none-any.whl:
Publisher:
publish.yml on tschamm/boschshcpy
-
Statement:
-
Statement type:
https://in-toto.io/Statement/v1 -
Predicate type:
https://docs.pypi.org/attestations/publish/v1 -
Subject name:
boschshcpy-0.4.4-py3-none-any.whl -
Subject digest:
f6eac7cb3e7e09400982768861c7de277d81973bc81cfb38d5a5bbdf33161180 - Sigstore transparency entry: 2032176527
- Sigstore integration time:
-
Permalink:
tschamm/boschshcpy@1ba20a7d6124099ab424e43f1c60ab55caeacd6f -
Branch / Tag:
refs/tags/v0.4.4 - Owner: https://github.com/tschamm
-
Access:
public
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
publish.yml@1ba20a7d6124099ab424e43f1c60ab55caeacd6f -
Trigger Event:
push
-
Statement type:
