A custom integration to connect Ninebot cloud devices into Home Assistant.
Maintainer: Wuty-zju
This repository is available via HACS Custom Repository.
It is not listed in HACS Default yet.
This integration provides vehicle-focused entities for Ninebot cloud devices, including:
- Main battery level and remaining range
- Vehicle lock state (read-only lock + binary lock state)
- Charging status and main power status
- GSM signal metrics (CSQ and converted RSSI)
- Vehicle location, report timestamp/time, SN, name, and vehicle image
- Home Assistant Core >= 2024.4.0
One-click install:
Or add manually in HACS:
- Open Home Assistant -> HACS -> Integrations
- Open menu (three dots) -> Custom repositories
- Repository URL: https://github.com/Wuty-zju/ha_ninebot
- Category: Integration
- Search Ninebot and click Download
- Restart Home Assistant
- Go to Settings -> Devices & Services -> Add Integration -> Ninebot
- Copy custom_components/ninebot into your Home Assistant config/custom_components directory
- Restart Home Assistant
- Add integration from UI
- Add integration: Settings -> Devices & Services -> Add Integration -> Ninebot
- Enter account and password
- Choose language and polling options
- Save and wait for first sync
Multiple accounts are supported. Each account creates one config entry and one coordinator instance.
All options are available in initial setup and in options flow later.
- default_scan_interval (seconds, default 60): normal polling interval per vehicle
- unlocked_scan_interval (seconds, default 3): polling interval when one vehicle is unlocked
- charging_scan_interval (seconds, default 30): polling interval when one vehicle is charging
- token_refresh_interval_hours (hours, default 24): forced token check/refresh cycle
- device_list_refresh_interval_hours (hours, default 24): device list refresh cycle
- max_device_info_concurrency (default 3): max concurrent device dynamic info requests
- device_info_failure_tolerance (default 3): allowed consecutive failures before marking one vehicle unavailable
- debug (default off): enables extra diagnostics in memory only
Recommended entity identifier format:
<domain>.ninebot_<vehicle_sn_lower>_<english_entity_name>
Example:
sensor.ninebot_2pde42522j0242_batterybinary_sensor.ninebot_2pde42522j0242_vehicle_lock
Status semantic rules:
- Raw status=0 means locked, status=1 means unlocked
- In binary locked sensor, use inverted boolean for locked semantics
- Read-only lock entity mirrors status and must not send lock/unlock commands
Implementation mapping:
- custom_components/ninebot/api.py: auth cache, device list cache, async multi-device fetch
- custom_components/ninebot/coordinator.py: per-vehicle scheduler, boost policy, failure fallback orchestration
- custom_components/ninebot/storage.py: persistent account/runtime data and migration-safe Store layer
- custom_components/ninebot/config_flow.py: setup/options for polling, cache, concurrency, tolerance
- custom_components/ninebot/const.py: option keys/defaults and polling constants
Key mechanisms:
- Token cache with periodic refresh and re-login fallback
- Device list cache with periodic refresh and error-triggered force refresh
- Persistent Store for account/runtime data, while debug payload stays memory-only
- Async concurrent per-vehicle requests with semaphore limit
- Per-vehicle scheduler with unlocked/charging/default interval priority
- Failure tolerance with cache fallback before availability degradation
Current release target: v1.0.1.
Recommended flow:
- Bump version in custom_components/ninebot/manifest.json
- Commit and push to main
- Create and push matching tag, for example:
git tag v1.0.1
git push origin v1.0.1- Create GitHub Release notes for that tag
HACS detects updates from tags/releases.
- Integration code: custom_components/ninebot
- HACS metadata: hacs.json
- Chinese README: README_zh.md
- Issues: https://github.com/Wuty-zju/ha_ninebot/issues
