Experimental ESPHome external component and reusable package for monitoring and controlling
ALLPOWERS portable power stations that use the BLE protocol implemented by
madninjaskillz/allpowers-ble.
Important
Compatibility is based on the BLE protocol, not the ALLPOWERS brand name alone. This project does not claim support for every ALLPOWERS power station. See the compatibility matrix below.
Warning
This is independent community software. It is not affiliated with or endorsed by ALLPOWERS, ESPHome, Home Assistant or the upstream project author. Treat output controls as alpha software until they have been physically validated on your exact model and firmware.
The upstream Python library uses one packet layout and the same FFF1 notification and FFF2
write characteristics for every device it handles. It does not contain separate model profiles.
The upstream Home Assistant integration advertises support for the S300 and variants whose BLE name
matches AP S*.
| Device or family | Status in this project |
|---|---|
| ALLPOWERS R600 | Primary tested target for this ESPHome port |
| ALLPOWERS S300 | Supported by the upstream implementation; community validation requested |
Other AP S* devices using the same packet format |
Expected to work, but must be validated per model |
| S500 and S700 V2 | Reported incompatible with the upstream packet parser; not claimed as supported |
| Other ALLPOWERS models | Unknown until GATT layout and notification frames are confirmed |
A device is compatible only when it exposes the expected service/characteristics and sends the
same status frame format. See docs/compatibility.md.
- Battery level
- Total input power
- Total output power
- Estimated remaining runtime
- AC, DC and light state
- AC, DC and light control
- ECO mode state and control on devices that publish the command-
0x03settings notification - ECO shutdown time selection: 1, 2, 4 or 6 hours
- Work mode selection: Mute, Standard or Fast
- Power-station hardware and firmware version diagnostics
- Independent car charger/12 V automotive socket state and control, disabled by default while hardware support is validated
- Experimental Bluetooth device-name query and update using command
0x35; disabled by default, retried at most three times per connection and only evidenced by the official app for SOLIX/VOLIX P1800 - Input and output power activity indicators derived from measured power flow
- Both can be active during pass-through operation; neither entity claims the direction of battery current.
- BLE connection state:
Disabled,SearchingorConnected - Persistent connection control:
- ON searches until connected and reconnects after link loss
- OFF disconnects and stops attempting to connect
- Active connection health: requests a fresh status broadcast every 20 seconds and recycles a GATT link after 45 seconds without any valid protocol packet
- Optional settings keepalive: resends the last station-reported settings every 9 minutes to mitigate model-dependent long-session disconnects; disabled by default due to beep
- Telemetry becomes unknown after BLE disconnection or stale data
- Commands are rejected until the BLE link and telemetry are valid
- ECO mode, shutdown-time, work-mode and car-charger commands are rejected until a fresh complete settings snapshot is available; every unrelated setting is preserved verbatim
- Power-station entities appear as a separate Home Assistant subdevice
- Optional Bluetooth RSSI and protocol diagnostics
- Multiple instances are supported when each package instance uses a unique
allpowers_id; optional Home Assistant wrappers also require unique block IDs and station-specific source entity IDs
- ESP32 with BLE client support
- ESPHome
2026.7.0or newer - ESP-IDF framework recommended; both ESP-IDF and Arduino are compiled in CI
- Stable BLE MAC address for the power station
- A compatible
FFF0/FFF1/FFF2GATT layout and packet format
ESP32-S3 is the recommended general-purpose target. A classic ESP32 also works. ESP32-C6 does not provide a specific advantage for this protocol.
components/allpowers_ble/ ESPHome external component
packages/allpowers_ble.yaml Reusable entities, subdevice and connection package
examples/ Standalone, Bluetooth Proxy and local examples
tests/ Protocol regression tests and CI configuration
docs/ Compatibility, protocol, migration and capture notes
home_assistant/ Optional unavailable-state wrapper switches
external_components:
- source: github://dedalodaelus/esphome-allpowers-ble@0.2.1
components:
- allpowers_ble
packages:
allpowers_station:
url: https://github.com/dedalodaelus/esphome-allpowers-ble
ref: 0.2.1
files:
- path: packages/allpowers_ble.yaml
vars:
allpowers_id: allpowers
allpowers_name: "ALLPOWERS Power Station"
allpowers_mac: !secret allpowers_station_macAdd the MAC to your local secrets.yaml:
allpowers_station_mac: "AA:BB:CC:DD:EE:FF"The public package contains no secret lookups of its own. Passing a local secret through package variables keeps the device address outside the repository.
The default installation is pinned to release 0.2.1. Source updates are therefore deliberate instead of following the moving main branch. To upgrade, review the release notes and migration guide, change both references to the same newer release, compile, and validate telemetry and controls on the exact station model and firmware. To roll back, restore the previous release number in both references and compile again.
Complete configurations are provided in:
examples/minimal.yaml— stable releaseexamples/bluetooth-proxy.yaml— stable releaseexamples/development-main.yaml— movingmainbranch for development onlyexamples/local-development.yaml— local checkout
Release verification and publication steps are documented in docs/releasing.md.
| Variable | Default | Purpose |
|---|---|---|
allpowers_id |
allpowers |
Unique ESPHome ID prefix; use letters, numbers and underscores |
allpowers_name |
ALLPOWERS Power Station |
Home Assistant subdevice name |
allpowers_mac |
Required | Stable BLE MAC address of the power station |
allpowers_service_uuid |
FFF0 |
Configurable service UUID |
allpowers_stale_timeout |
30s |
Time before telemetry becomes unknown |
allpowers_keepalive_interval |
20s |
Interval between status-broadcast refresh requests; minimum 5s |
allpowers_watchdog_timeout |
45s |
Silence before forcing reconnection; minimum 10s and longer than keepalive |
allpowers_enable_settings_keepalive |
false |
Initial state of the Home Assistant settings-keepalive switch before a saved value exists |
allpowers_settings_keepalive_interval |
9min |
Initial settings-resend interval before a saved Home Assistant value exists |
allpowers_enable_experimental_device_name |
false |
Opt in to command-0x35 name query/update |
allpowers_connect_at_boot |
true |
Start persistent searching after boot |
allpowers_bootstrap_delay |
10s |
Delay before initial BLE search |
allpowers_advertised_name_wait_timeout |
3s |
Maximum pre-connection wait for a fresh advertised name |
allpowers_scan_interval |
320ms |
ESP32 BLE scan interval |
allpowers_scan_window |
320ms |
ESP32 BLE scan window |
allpowers_scan_active |
true |
Active BLE scanning |
allpowers_rssi_update_interval |
60s |
Optional RSSI update interval |
If the same ESP32 also acts as a Home Assistant Bluetooth Proxy, reserve one connection slot per ALLPOWERS BLE client in addition to the proxy slots:
esp32_ble:
max_connections: 4
bluetooth_proxy:
active: true
connection_slots: 3| Entity | Type |
|---|---|
| Battery Level | Sensor |
| Input Power | Sensor |
| Output Power | Sensor |
| Estimated Time Remaining | Sensor |
| AC Output | Switch |
| DC Output | Switch |
| Light | Switch |
| ECO Mode | Switch |
| ECO Shutdown Time | Select |
| Work Mode | Select |
| Car Charger | Switch |
| Settings Keepalive | Persistent configuration switch |
| Settings Keepalive Interval | Persistent number (1-9 minutes) |
| Send Settings Keepalive Now | Configuration button |
| Bluetooth Name (Experimental) | Text |
| AC Output Status | Binary sensor |
| DC Output Status | Binary sensor |
| Light Status | Binary sensor |
| ECO Mode Status | Binary sensor |
| Input Power Active | Binary sensor |
| Output Power Active | Binary sensor |
| Entity | Purpose |
|---|---|
| Keep BLE Connected | Desired persistent connection state |
| BLE Connection Status | Disabled, Searching or Connected |
| BLE Connected | Physical BLE link state |
| Telemetry Available | A recent valid status frame exists |
| Controls Available | Output commands can be sent safely |
| Settings Available | A recent settings frame permits safe settings-backed writes |
| BLE Protocol Error | Error latch for the current GATT session |
| BLE Protocol Error Count | Errors recorded since the ESP last restarted |
| Consecutive BLE Protocol Errors | Current run of errors without a valid packet |
| Last BLE Protocol Error | Last error category and reason |
| Last BLE Protocol Error Uptime | ESP uptime when the last error occurred |
The error latch and consecutive counter clear only after notification subscription succeeds for a new GATT session, not after the next valid packet. The total count, last reason and last-error uptime survive reconnects in RAM and reset on ESP reboot. Ordinary disconnections and stale telemetry do not count as protocol errors. These diagnostics use no preferences and therefore create no flash writes.
When the BLE link is disconnected or telemetry expires, numeric and binary telemetry entities are
invalidated. Native ESPHome controls cannot all publish availability independently; Settings Available
gates both ECO writes in firmware, and the component clears the select's confirmed value when its settings
snapshot expires.
The package already used ESPHome's native auto_connect behavior to reconnect after a real BLE
disconnect. The connection-health layer covers a different failure mode: a GATT link that still appears
connected but has stopped carrying notifications. It sends the observed status request immediately after
notification registration and on the configured cadence. If no structurally valid protocol packet arrives
before allpowers_watchdog_timeout, the component closes the link once; the existing ESPHome BLE client
then discovers and reconnects it. The 30-second stale-data invalidation remains independent from the
45-second connection watchdog. A failed notification subscription or asynchronous GATT write also closes
the link from the main loop so ESPHome can rebuild the complete session.
The status request and default timing are behavioral observations from
R0b0To/allpowers-companion. That project is GPL-3.0;
this MIT implementation was written independently and does not incorporate its source code. The behavior
has not yet been physically verified on every model, so retain the defaults until device logs demonstrate
a need to tune them.
The separate settings keepalive targets a different long-session behavior: some stations can close a
healthy BLE connection after several minutes even though notifications continue and the status requests
succeed. Enable it with the Settings Keepalive switch in Home Assistant. At the configured interval, the component
reuses the most recent complete settings bitmap and ECO timeout reported by the station and sends them back
unchanged as command 0x02; it skips the write if no settings snapshot was received in that connection.
An output-control or settings write restarts this interval, avoiding an immediate redundant keepalive. The
default interval is 9 minutes and can be changed from 1 to 9 whole minutes with the adjacent Home Assistant
number entity. Both values are restored from flash after an ESP restart and remain unchanged across BLE
disconnects. Changing either value restarts the timer; sending the already-current value does not create a
new preference write. This is an experimental workaround, and an accepted settings command may make some
stations beep every time it is sent. Current physical evidence is from R600-class devices; community
validation on other compatible models is requested.
On each new BLE connection, when the keepalive switch is enabled, the component
does not wait for the periodic interval: it sends one initial keepalive as soon
as the station reports the first complete command-0x03 settings snapshot.
This is the earliest safe point because command 0x02 must preserve settings
that are not all represented by Home Assistant entities. The configuration
button sends the same learned snapshot once even when periodic keepalive is
disabled; pressing it before BLE and the snapshot are ready is safely ignored.
The optional wrapper in
home_assistant/allpowers_ble_controls.yaml.example
creates AC, DC, light and ECO controls with explicit Home Assistant availability. AC, DC and light use
Controls Available; ECO uses Settings Available because its write must preserve the complete
settings bitmap and current ECO timeout. The wrapper uses confirmed binary sensors for state and calls
the original ESPHome switches to execute commands. The ECO shutdown-time select is provided directly by
ESPHome and is protected by the same Settings Available firmware gate.
Copy the example to your Home Assistant packages directory, for example:
/config/packages/allpowers_ble_controls.yaml
Enable packages in configuration.yaml if necessary:
homeassistant:
packages: !include_dir_named packagesReplace the source entity IDs in the copied file with those generated by your Home Assistant instance. Keep the original ESPHome switches enabled because the wrappers call them; they may be hidden from dashboards, but must not be disabled.
For multiple power stations, use a separate wrapper block for each station and change its block-level
unique_id, displayed names, default_entity_id values and all referenced source entity IDs. The
block-level ID is combined with each entity ID, preventing collisions between stations.
After editing the file, check the Home Assistant configuration and reload Template entities or restart Home Assistant. The wrapper is optional and does not replace the connection and command-safety checks implemented by the ESPHome component.
Charging limits, self-use mode, independent USB control, voltage, current, temperature, internal alarms and remaining energy in watt-hours are not exposed. Their settings bits are preserved when ECO mode, its shutdown time, work mode or the car charger is changed rather than being invented or reset.
ECO stays unavailable on devices that do not publish the compatible command-0x03 settings frame.
This prevents the generic package from assuming that every station with the ALLPOWERS brand uses the
R600 settings protocol.
AC frequency is experimental and disabled by default. See docs/protocol.md.
Bluetooth renaming is more narrowly supported than the telemetry protocol. The extracted official
Android app encodes command 0x35 as UTF-8 with a 96-byte maximum, but explicitly permits the BLE
rename path only for SOLIX P1800/VOLIX P1800. There is no evidence in the supplied app that an
R600 accepts the command. Consequently, both the package option
allpowers_enable_experimental_device_name and the disabled-by-default Home Assistant text entity
must be enabled deliberately. The entity is non-optimistic: it remains unknown or retains its last
confirmed value unless the station returns a valid command-0x35 name response. The component makes
three bounded queries per GATT connection (after 500 ms, then twice more at 3-second intervals) and
cancels the remaining attempts as soon as a valid response arrives.
The separate Station Name diagnostic is always read-only. It accepts a valid name from either an
advertisement matching allpowers_mac or a valid command-0x35 response, and stores the latest
value in ESPHome preferences. Empty values, placeholders such as Unknown, malformed UTF-8 and
control characters neither overwrite nor clear a previously stored name. Repeated reception of the
same name does not queue another flash write. At boot the stored value is restored only when its
associated MAC still matches allpowers_mac; changing the MAC clears a non-empty stored name before
anything is published, so a name cannot leak from one station to another.
Passive advertisement capture does not depend on command 0x35 support or send any request to the
station. Before each connection attempt, the package temporarily keeps
BLEClient auto-connect disabled while active scanning waits for a fresh name. Receipt of the name
starts the connection immediately; otherwise the connection proceeds after
allpowers_advertised_name_wait_timeout, so a device that omits its name cannot block telemetry.
Active scanning must remain enabled for a complete name carried in scan-response data.
The repository includes a development container for VS Code and GitHub Codespaces. In VS Code,
install Docker and the Dev Containers extension, open the repository, and run
Dev Containers: Reopen in Container. The container creates an isolated Python environment and
installs the pinned dependencies from requirements-lint.txt and requirements-ci.txt
automatically.
Install the pinned dependencies first:
pip install -r requirements-lint.txt
pip install -r requirements-ci.txtRun the complete validation suite used by CI:
./scripts/validate.shRun each CI cycle independently:
./scripts/validate.sh code-quality
./scripts/validate.sh buildRun a single build target (same target IDs used by the workflow matrix):
./scripts/validate.sh build-target esp32-idf
./scripts/validate.sh build-target esp32s3-idf
./scripts/validate.sh build-target esp32-arduino
./scripts/validate.sh build-target esp32-multi-idfThe script runs every lint and test, then compiles classic ESP32 and ESP32-S3 with ESP-IDF, classic ESP32 with Arduino, and two independent station instances in one ESP-IDF firmware. GitHub Actions invokes the same script modes through a matrix job.
Include:
- Exact model and hardware revision
- Firmware version shown by the official application
- BLE local name
- Service and characteristic UUIDs
- ESPHome version
- ESP32 model and framework
- Sanitized logs
- Which readings and controls were physically verified
Never publish Wi-Fi credentials, API encryption keys, OTA passwords or complete Android bug reports.
- BLE protocol source and original communication logic:
madninjaskillz/allpowers-ble, MIT licensed. - Initial R600 ESPHome port developed with assistance from OpenAI ChatGPT.
- Generalization and maintenance by
dedalodaelus. - Generated and adapted code must be reviewed and validated against real hardware by maintainers and contributors.
MIT. See LICENSE.