Qingping IoT Cloud for Home Assistant

Custom Home Assistant integration that reads Wi-Fi enabled Qingping devices through the Qingping IoT Cloud. It complements the official Qingping integration, which is Bluetooth-only — so it also works with devices that have no Bluetooth at all (e.g. 2nd generation Qingping Air Monitor).

What you get:

• one Home Assistant device per Qingping device in your account;
• one sensor per value the device reports (temperature, humidity, CO₂, PM2.5, PM10, TVOC, noise, pressure, battery, Wi-Fi RSSI, …);
• cloud polling with a configurable interval;
• optional incoming webhooks for near real-time pushes;
• entities marked unavailable when readings go stale or the device stops reporting.

The API client is bundled with the integration and rewritten on top of aiohttp (Home Assistant's own HTTP client), so the integration installs no extra Python packages and cannot break Home Assistant's dependency pins.

Status: work in progress, beta quality. See TODO.md.

Requirements

• Home Assistant 2024.11 or newer.
• Shell access to the machine running Home Assistant (for the installer below).
• A Qingping account with devices bound in the Qingping IoT or Qingping+ mobile app.
• An App Key / App Secret pair for that account (see below).

Installation

This repository is not hosted on GitHub, so GitHub-only installers cannot be used. Installation is a single command instead. Run it in a shell on the machine that runs Home Assistant:

curl -fsSL https://git.kosyrev.name/zoo/ha-qingping-iot-cloud/raw/branch/main/install.sh | sh

That is all. The installer downloads the latest version, replaces custom_components/qingping_iot_cloud in your configuration directory, and restarts Home Assistant (it backs up the previous installation, so it is safe to run repeatedly).

Afterwards go to Settings → Devices & Services → Add Integration and pick Qingping IoT Cloud.

To update or reinstall later, run the very same command again.

Installer options

Option	Description
-d, --config-dir DIR	Configuration directory. Defaults to /config, otherwise to common locations such as ~/.homeassistant.
-r, --ref REF	Branch or tag to install. Defaults to main.
--no-restart	Install without restarting Home Assistant.
-h, --help	Show help.

Examples:

# Pin a specific version.
curl -fsSL https://git.kosyrev.name/zoo/ha-qingping-iot-cloud/raw/branch/main/install.sh | sh -s -- --ref v0.4.0

# Unusual configuration directory.
curl -fsSL https://git.kosyrev.name/zoo/ha-qingping-iot-cloud/raw/branch/main/install.sh | sh -s -- --config-dir /srv/homeassistant

Manual installation

If you prefer to inspect the script first, or want to install it by hand:

# Download, read, then run.
curl -fsSLO https://git.kosyrev.name/zoo/ha-qingping-iot-cloud/raw/branch/main/install.sh
less install.sh
sh install.sh

To do it fully manually, copy the custom_components/qingping_iot_cloud folder from the repository archive into <config>/custom_components/. The result must look like this, after which Home Assistant needs a restart:

<config>/custom_components/qingping_iot_cloud/manifest.json

Getting credentials

1. Install the Qingping IoT app from qingpingiot.com or the Qingping+ app from qingping.co/plus and create an account.
2. Pair your devices following the in-app instructions and make sure they show up there.
3. Log in to developer.qingping.co with the same account.
4. Open Access Management and copy the App Key and App Secret.
   • You get one credential pair per account.
   • The credentials cannot be revoked, so keep them safe.

Configuration

Add the integration and paste the App Key into App Key and the App Secret into App Secret. The account's App Key is appended to the hub name, so you can add several accounts side by side.

After setup, sensors appear under the created hub device. Per hub you can also adjust:

• Scan Interval (seconds) — how often the cloud is polled. Minimum 60, default 300.

Webhooks (optional)

Qingping can push updates to Home Assistant instead of relying on polling:

1. After adding the integration, Home Assistant shows a persistent notification containing the public webhook URL for this hub.
2. Paste that URL into Data Push Settings on the developer portal.

If you don't have a public URL (no Home Assistant Cloud / reverse proxy), just ignore the notification and rely on polling.

Qingping IoT vs Qingping+

These are two different apps with separate accounts. For this integration they are mostly interchangeable:

• both offer mobile apps with local binding and cloud access;
• both account sets authenticate against developer.qingping.co, so data from either is reachable through the same API;
• a device can be bound to both apps at the same time.

Differences:

• Qingping IoT targets "professional" deployments and supports some devices that are not sold to consumers (e.g. via AliExpress). Some of those use LoRaWAN or NB-IoT instead of Wi-Fi and will not work here. It also offers a web dashboard with live and historical data.
• Qingping+ targets households and supports some Bluetooth-only devices that are not compatible with the Qingping Bluetooth gateway (e.g. the alarm clock); those do not work with Qingping IoT and therefore not with this integration.

Acknowledgements

• Based on Example Home Assistant Integration - Integration 101 Template by Mark Parker, originally distributed under the MIT license.
• Bundles an adapted copy of qingping-iot-cloud by Daniel Skowroński (BSD-2-Clause), rewritten on top of aiohttp.

See the LICENSE file for the full statement.