Your vehicles, batteries and ride history — together in Home Assistant.
English · 简体中文
Install · Features · Ride history · Architecture · Documentation
Monitor your Ninebot's battery, charging and vehicle status. Keep ride records and detailed GPS tracks in your own Home Assistant storage, query them from automations, and use native calendars and statistics alongside everyday vehicle entities.
Stable release: v2.0.0. Live updates need internet access; saved rides are available locally. Map visualization and custom cards are early alpha.
| Area | Available information and features |
|---|---|
| Vehicle | Power, ACC, charging, main-battery presence/type/count, smart-service status and device location. |
| Range | Separate precise, estimated and AI range values; AI range appears in diagnostics. |
| Main battery | SOC, measured voltage, temperature, cycle count/support, charging power, health score and Find My support where reported. |
| Communication battery | Separate emergency communication battery SOC; main battery SOC remains the device's battery indicator. |
| Ride summaries | Today/yesterday/month distance, count, duration and energy; Last Ride times, distance, duration, maximum/average speed and energy intensity. |
| Historical archive | Resumable discovery, incremental updates, detailed ride/GPS preservation, local query Actions and per-vehicle progress. |
| Native HA features | Ride calendar, vehicle/trip events, GPS tracker, vehicle image, response Actions and explicit day/month statistics imports. |
| Controls | Vehicle lock, seat unlock, bell and retained remote-start/stop buttons, with fresh status checks after commands. |
Available fields vary by vehicle and cloud reports. Battery health score is a score, not SOH; configured rated energy is a specification, not measured capacity. Entities, units and availability →
Version 2.0 brings together 107 betas and four release candidates: isolated accounts, adaptive live updates, native controls and a portable account-owned ride archive. Incremental acquisition, source verification and quality-aware track retention support long-term local history. The stable release carries forward the entity identities, control timing and schema 7 archive validated in rc4. Development history →
- Home Assistant 2026.1.0+ and a compatible 64-bit host/container for the runtime dependency.
- A Ninebot account with vehicles visible in the official app.
- Internet access for login, live updates and cloud history acquisition.
- HACS for the recommended installation; manual installation is also supported.
ARMv7/32-bit platforms are unsupported. Requirements and platform details →
- Open HACS → ⋮ → Custom repositories.
- Add
https://github.com/Wuty-zju/ha_ninebotwith category Integration. - Open Ninebot, select v2.0.0, and download it.
- Restart Home Assistant when prompted.
- Go to Settings → Devices & services → Add integration → Ninebot.
This repository currently uses HACS custom-repository installation. HACS must already be installed.
Download ninebot.zip from the chosen packaged release, create <config>/custom_components/ninebot, and extract the ZIP contents there. Restart Home Assistant and add Ninebot from Devices & services. For older releases or GitHub source archives, copy the contained custom_components/ninebot directory instead.
Runtime code, translations and bundled resources live in that directory. HA installs the declared dependencies; no separate daemon or dashboard repository is required.
The Downloads badge counts ninebot.zip downloads across releases, including updates and repeat downloads. It does not represent unique installations or historical source-archive downloads.
HACS may display the download count for its selected release asset; that figure differs from the badge's cumulative package count.
2.0 rebuilds authentication, entity management and history storage. Back up your HA configuration, storage and database, then follow the migration guide. Entity-ID and Lock-platform migrations can require automation/dashboard updates. Storage rollback requires the matching pre-upgrade backup.
Sign in with your account and password; vehicle features are configured after authentication. Ninebot discovers the account's vehicles and creates supported entities. Review account options, then add another integration entry for each additional account.
Each account owns its session, credentials directory and archive. Entry titles use the reported username and account, omitting missing components. Reauthentication and reconfiguration update the established account. Passwords are not stored in ConfigEntry or passed as process arguments; local session tokens and backups should be protected.
| Option | Default | Purpose |
|---|---|---|
| Update speed | Balanced | Five adaptive profiles with per-vehicle activity boosts. |
| Precise location | On | Current position and authorized track responses; no separate precision request. |
| Ride calendar (Beta) | Off for new accounts | Local rides on a native HA calendar. |
| Background detail preservation (Beta) | Off for new accounts | Save detailed rides/tracks within the request budget. |
| Automatic history sync (Beta) | Off for new accounts | Initial discovery and subsequent incremental work. |
| Controls and vehicle allowlist | New accounts: on / sign-in-verified vehicles | Adjust command access for selected vehicles; existing choices are retained. |
| Keep local history database (Beta) | On | Retain history after account removal and reconnect it on same-account sign-in. |
| Vehicle events (Beta) | On | Trip reports, revisions, completions and concrete vehicle transitions. |
| Debug mode | Off | Bounded parsed current information for investigation. |
Existing explicit choices are retained on upgrade. Further options include adaptive update profiles, nominal battery parameters, request budget and archive quota. Defaults and ranges →
The private account archive keeps normalized facts alongside retained business-source evidence:
- Ride identity, source month, start/end times, distance, duration and energy.
- Server maximum speed and the separate overall average calculated from distance/duration.
- Detailed GPS trails and associated point/sample fields when returned by the cloud.
- Monthly summaries, page receipts, capture times, source precision and field availability.
- Synchronization checkpoints, retries, coverage and local integrity results.
Scalar values and track quality have separate lifecycles. A corrected total can update while a more complete route is retained; later empty or simplified responses do not erase a better saved track.
Enable Automatically sync trip details (Beta) and Automatically scan trip history (Beta) in account options. Both default off for new accounts; enable them when you want background acquisition. Existing choices are retained.
| Stage | Work performed |
|---|---|
| Initial discovery | Walk month/page plans, validate counts and identities, deduplicate rides and persist checkpoints. |
| Detail preservation | Fetch missing or unsettled details, reuse stable records and prioritize older rides near the preservation risk window. |
| Incremental updates | Revisit recent activity, reconcile changed lists and retry gaps without repeatedly downloading settled history. |
| Local verification | Check retained objects and page relationships in bounded work; surface actionable storage problems through Repairs. |
History scan and saved-detail progress are device diagnostics. The sync button starts or resumes work; pause stops background acquisition. Debug mode adds synchronization state and last-success diagnostics. Saved-detail percentage covers discovered records; month coverage reports list gaps separately.
The default history budget is 60 logical requests per account/hour, configurable from 1–120 in a numeric input. 0 removes the hourly quota (not recommended); request serialization, retries and upstream backoff still apply. Archive quota defaults to 100 MiB per account, configurable from 32–2048 MiB. Reaching the quota pauses writes and retains existing data. Local records have no age-based expiry; capacity and backups govern long-term retention. Save details while the cloud still returns them: removed or simplified upstream tracks cannot be recreated locally.
| Goal | Home Assistant feature |
|---|---|
| Current position | Device location tracker and native Map card. |
| Rides by date | Native ride Calendar backed by the local archive. |
| New-ride automation | Vehicle trip and state Event entities, after their startup baselines. |
| Saved rides/tracks | ninebot.get_recorded_trips and ninebot.get_trip_detail. |
| Day/month aggregates | ninebot.get_statistics. |
| Historical trend charts | Explicit ninebot.import_statistics, then native statistics charts. |
| Acquisition management | ninebot.sync_history and history entities/buttons. |
Local-only query modes read the archive without cloud acquisition. Large lists and trails use bounded pages/chunks, rather than entity attributes or one entity per ride.
History guide and Action examples → · Coverage and statistics →
Visualization status: the bundled map and cards are early alpha, with ongoing work on navigation, linked views and route comparison. Setup instructions are in the history guide.
| Layer | Refactor and resulting behavior |
|---|---|
| Accounts | Separate entries, sessions and archives; password setup, reauth and reconfigure. |
| Data model | Reviewed normalization, source metadata, distinct range fields, explicit missing values and original precision. |
| Realtime updates | Per-vehicle/group freshness, demand scheduling, shared in-flight reads, partial failures and backoff. |
| History lifecycle | Resumable discovery, incremental detail preservation, transactional SQLite storage and quality-aware track retention. |
| HA integration | Native sensors, locks, tracker, images, calendars and events; response Actions and aggregate statistics. |
| Maintenance | Diagnostics, Repairs, migration journals, backup coordination and bounded local verification/reconstruction. |
The refactor also adds prompt discovery recovery, immediate status updates, stable day-boundary statistics and account-owned history that survives removing and re-adding an account. Configured battery specifications remain separate from measured values. Migration details → · 2.0 development overview → · Release history →
Each authenticated account has one private SQLite database, shared by its vehicles and independent of the integration entry. The archive combines structured records for efficient queries with compressed source evidence for verification and future parsing.
| Capability | How it works |
|---|---|
| Long-term ownership | No age-based deletion. Removing an account retains history by default; signing into the same account reconnects it. |
| Incremental acquisition | Month/page checkpoints, ride-ID deduplication and reusable details reduce repeat requests. Background tasks resume after restart. |
| Track protection | Latest scalar facts and best saved geometry are selected independently. A newer simplified route keeps the earlier detailed track available. |
| Responsive access | Serialized database work runs outside HA's event loop. Local queries use bounded pages and track chunks; live polling has its own schedule. |
| Integrity and recovery | Transactions, payload hashes, reference checks, bounded audits and supported reconstruction protect retained records. |
| Portable backups | Export selected vehicles or accounts as a versioned ZIP. Import validates ownership, schema and payloads, then deduplicates and merges. |
| Upgrade cleanup | Verified legacy databases are consolidated; successfully merged copies are removed. Distinct source evidence stays in the main archive. |
| Capacity control | The account quota pauses writes when full. Existing records remain available, and the user can raise the limit. |
The default Keep local trip history database (Beta) option controls removal behavior. Export/import is available from account Configure and requires an administrator. Download links expire after ten minutes; filenames identify UTC time, account/vehicle counts and the selected scope.
Back up Home Assistant before a major upgrade. A first upgrade with several older databases can take a few minutes while they are checked and merged. Preserve exported archives as private location records. Export/import instructions → · Upgrade and rollback →
Each account owns its session/resources. A shared scheduler coordinates cloud reads across vehicles: current state refreshes by data group, while history advances in background steps. Source evidence and normalized values remain distinguishable.
The Balanced profile targets status/BMS at 60/60 seconds while parked, 15/30 seconds while charging and 10/30 seconds with ACC active. Current-month ride summaries use 600/120 seconds while parked/active; vehicle profiles refresh hourly. Each vehicle and group has independent deadlines and shared reads. Five update-speed profiles →
Month discovery, identity, detail download and local verification have independent checkpoints. Stable details are reused; newer scalar values and the best known geometry are kept separately. An account-owned serialized worker performs SQLite operations outside HA's event loop.
Current summaries use HA's state machine. Full trails and business evidence stay private. Native long-term statistics receive selected day/month aggregates through an explicit import; they are not a second GPS database.
Locks and buttons share the executor. Vehicle lock/unlock maps to remote stop/start; vehicle/cloud operating rules apply. HA follows with short-term status reads rather than assuming the target state. Seat unlock is remote; seat locking is manual.
The integration manages its authenticated local connection automatically. Paginated history uses a dedicated adapter with the same account session. Technical architecture, lifecycle and dependencies →
- Location and archives: location defaults on. Details and HA backups can contain precise routes; requested GPS responses may appear in automation traces.
- Reported versus calculated: range fields stay separate; maximum and overall average speed differ. Unknown point units/coordinate systems are not silently converted.
- Map resources: experimental cards bundle JavaScript and the map library. Optional external basemap tiles default off and contact the tile provider when enabled.
- Access and diagnostics: archives are account-isolated, history responses check vehicle access, and diagnostics expose reviewed metadata instead of credentials or full trails.
Privacy and troubleshooting → · Backup and recovery →
| Area | Direction |
|---|---|
| History visualization | Develop the early-alpha map/UI/card foundation into clearer date/vehicle navigation, route comparison and linked detail/chart views. |
| HA dashboards | Improve calendar/statistics workflows and reusable dashboard examples. |
| Data coverage | Add useful entities and vehicle/battery models as field semantics are confirmed. |
| Storage and synchronization | Refine reads, incremental acquisition, progress and recovery using measured workloads. |
| Protocol research | Verify point metrics and keep protocol replacement possible behind the backend abstraction. |
These are development directions rather than release-date commitments. Detailed roadmap →
| You need | Start here |
|---|---|
| Install, connect an account or change options | Setup and everyday use |
| Query history, use statistics or explore experimental maps | History, maps and statistics |
| Upgrade or restore a backup | Migration guide |
| Understand the implementation | Architecture |
| Contribute code or work with coding agents | Contributing, development map, AGENTS |
Use Issues for reproducible bugs and Discussions for usage/design questions. Include integration/HA versions and relevant diagnostics after reviewing privacy. Sensitive concerns follow the security policy.
MIT licensed. Ninebot/Segway names and vehicle images belong to their owners; this project is independently maintained. Community protocol/library contributions and bundled licenses are recorded in NOTICE and dependency attribution.
Earlier README links
- Installation and account
- Current data and options
- History, events and controls
- Upgrade and development
- Missing local detail originals
- Recent ride follow-up
- History progress and local rate limiting
- Reusing verified history months
- Current-month source checks
- Support and contribute
- Privacy and limitations