BleBox Python UniAPI

Python API for accessing BleBox smart home devices

• Free software: Apache Software License 2.0
• Documentation: https://blebox-uniapi.readthedocs.io.

Features

• supports 11 BleBox smart home devices

• contains functional/integration tests

• every device supports at least minimum functionality for most common automation needs

• insight of integration level are accesible from file box_types.py

  (devices with apiLevel lower than defined in BOX_TYPE_CONF will not be supported but higher will)

Contributions are welcome!

Credits

Changelog

2.5.9 (2026-10-18)

Bug Fixes

• tankSensor liquidHeight and volume are reported in mm and ml (#206) (7512f43)

2.5.8 (2026-10-01)

Features

• support tankSensor (#204) (2f93dac)

Bug Fixes

• query both info endpoints in OTA check (#203) (a6683c4)

2.5.7 (2026-08-12)

Bug Fixes

• handle sensor state and thermoBox safety off (#202) (1321ce5)

2.5.6 (2026-08-06)

Features

• expose gateBox extra button output as a button entity (#201) (eb72cb4)
• expose product on Box for HASS device model display (#200) (7ff36de)

Bug Fixes

• log caught API-call exceptions at debug instead of error (#198) (f25183e)

2.5.5 (2026-06-09)

Features

• add support for CO2Sensor (#195) (ac05dfc)
• add voltage measurement support for switchBox (#194) (964adf6)
• add is_calibrated property to Shutter and is_slider guard (#193) (5f0be49)
• add reactive energy sensors for energyMeter (#192) (19de0f5)

2.5.4 (2026-05-25)

Features

• add OTA firmware update support via Update feature (#191) (b3bfbf6)
• add new ShutterBox control types and tilt properties (#190) (a977239)
• add temperature sensors to thermoBox (#189) (775510e)

Bug Fixes

• RGBWW brightness and channel ordering (#188) (02251d9)
• color mode logic to restore last color value correctly (#187) (dfbf3bd)
• add sensor_id and name parameters to Open and Input binary sensor classes (#186) (1c308d9)

2.5.3 (2026-05-08)

Features

• add support for openSensor as both generic and binary sensor (#184) (a4e0a64)
• add index and name properties to sensors, switches and lights (#185) (20faf7a)
• add support for inputSensor (#183) (cb08d4a)

Bug Fixes

• ensure sensible_on_value returns list for MONO mode (#182) (bc3a78c)

2.5.2 (2026-04-24)

Features

• add is_position_inverted to expose position convention per device type (#181) (be63c03)

2.5.1 (2026-04-21)

• fix: multisensor current and energy sensor scales

2.5.0 (2024-08-20)

• feature: expose sensor_id in sensors and alias in all features by @swistakm in https://github.com/blebox/blebox_uniapi/pull/176

2.4.2 (2024-06-04)

• fix: add missing support for active power sensors on switchbox/switchboxd devices by @swistakm in https://github.com/blebox/blebox_uniapi/pull/175

2.4.1 (2024-06-04)

• fix: rectify ambiguity around powerConsumption and wind sensor types

2.4.0 (2024-06-03)

• Fix: Refactor sensor_factory by @Pastucha in https://github.com/blebox/blebox_uniapi/pull/163
• Order in BOX_TYPES by @Pastucha in https://github.com/blebox/blebox_uniapi/pull/164
• Feature: smart meter by @swistakm in https://github.com/blebox/blebox_uniapi/pull/168
• Smartmeter by @pvsti in https://github.com/blebox/blebox_uniapi/pull/170
• fix: resolve regressions in cover and climate due to jmespath introduction by @swistakm in https://github.com/blebox/blebox_uniapi/pull/173

2.3.0 (2024-03-13)

• feat: add new methods to cover feature enabling handling of tilt open/close actions by @swistakm in https://github.com/blebox/blebox_uniapi/pull/154
• add support for flood sensing for multisensors as binary moisture sensor by @swistakm in https://github.com/blebox/blebox_uniapi/pull/153
• feat/fix: Add Ruff and Pre-commit Configuration, Resolve Undefined Name by @Pastucha in https://github.com/blebox/blebox_uniapi/pull/158
• gatebox and shutterbox improvements: by @swistakm in https://github.com/blebox/blebox_uniapi/pull/156
• BleBox Multisensor Illuminance Integration by @Pastucha in https://github.com/blebox/blebox_uniapi/pull/161

2.2.2 (2024-02-07)

• fixed wind reading units to get proper raw m/s value (division by 10, see PR #150)

2.2.1 (2024-01-26)

• fixed support for power measurement capabilities of switchBox and switchBoxD devices

2.2.0 (2023-08-29)

• added last_reset to energy sensor class
• added BasicAuth support to http client

2.1.4 (2023-01-03)

• added tilt position support for cover.Shutter
• added Wind for wind sensor of multisensors
• added Energy sensor class for power consumption tracking
• implementing default_api_level for
  • dimmerBox
  • wLightBox
  • wLightBoxS

2.1.3 (2022-10-27)

• thermoBox boost mode doesn't corrupt state

2.1.2 (2022-10-17)

• fixed CCT, CCTx2 modes for wLightBox v1 & v2

2.1.1 (2022-10-11)

• added support for thermoBox devices:
  • added thermoBox config to BOX_TYPE_CONFIG
  • Climate uses factory method implementation
  • added test coverage

2.1.0 (2022-08-05)

• added support for multiSensor API:
  • airQuality moved to sensor module
  • new binary_sensor module, introducing Rain class

2.0.2 (2022-07-06)

• added query_string property in Button class
• fixed test assertions after changes in error raised ValueError

2.0.1 (2022-06-01)

• used ValueError type instead of BadOnValueError in methods:
  • evaluate_brightness_from_rgb
  • apply_brightness
  • normalise_elements_of_rgb
  • _set_last_on_value
  • async_on

2.0.0 (2022-06-21)

• extended support for color modes in wLightBox devices
• initial support for tvLiftBox device
• major backward-incompatible architectural changes to enable dynamic configuration of devices
• removed products.py module and replaced with factory method on Box class
• general overhaul of public interfaces

1.3.3 (2021-05-12)

• fix support for wLightBoxS with wLightBox API
• fix state detection in gateBox

1.3.2 (2020-04-2)

• use proper module-level logger by default
• fix formatting

1.3.1 (2020-04-2)

• never skip command requests
• improve error messages

1.2.0 (2020-03-30)

• expose device info
• always add ip/port in connection errors
• fixed gateController support
• support for sauna min/max temp

1.1.0 (2020-03-24)

• fix bad wLightBox API path
• wrap api calls in semaphore (to serialize reqests to each box)
• throttle updates to 2/second (to avoid unnecessary requests)
• rework error handling and hierarchy (for cleaner usage)
• use actual device name (to help recognize the device)
• handle asyncio.TimeoutError (to handle timeout-related errors nicely)
• properly re-raise exceptions (to avoid lengthy call stacktraces)
• rename wLightBoxS feature to "brightness"

1.1.0 (2020-03-24)

• fix switchBox support
• fix minimum position handling
• drop Python 3.6 support (still may work)
• misc fixes, cleanup and increased test coverage

1.0.0 (2020-03-24)

• Fixed wLightBox issues
• Fixed wLightBoxS issues
• Fixed shutterBox issues
• Handle unknown shutterBox position
• Improved error handling + lots of new diagnostics
• Increased tests and test coverage (almost 100%)
• Lots of rework

0.1.1 (2020-03-15)

• Fixed switchBox support (newer API versions)

0.1.0 (2020-03-10)

• First release on PyPI.