AP300: Add sensors, controls, and encrypted write support

[happytechca]

Summary

This PR expands AP300 support with new sensors and writable controls, discovered through
register scanning on an Apex 300 unit I recently acquired.

I want to acknowledge upfront that this touches quite a few files (14) across several areas of the codebase

I would have preferred to keep it tighter, but adding writable controls to an encrypted device
required changes that cut across the fields, enums, device reader, and base device layers.

I tried to keep each change minimal and consistent with existing patterns.

AP300 sensors added

• AC input frequency, voltage, current
• AC output frequency, voltage
• DC/AC input/output power
• Time remaining

AP300 controls added

• Switches: AC output, DC output (untested; no D1 hub to test), ECO, power lifting, charge from grid
• Selects: charging mode, working mode, display timeout
• Number sliders: battery SOC range start/end (0–100%)

New: NumberField

A new writeable field type (extends UIntField) for numeric slider controls like SOC
range. This required:

• NumberField class in bluetti_bt_lib/fields/
• get_number_fields() on BluettiDevice
• NumberField handling in build_write_command() (float → int conversion)
• Exclusion from get_sensor_fields() so sliders aren't surfaced as read-only sensors

New: WorkingMode enum

Enum with values: CUSTOM (1), SELF_CONSUMPTION (2), BACKUP (4), TIME_OF_USE (5)

New: DeviceReader.write() method

The existing DeviceWriter class explicitly does not support encryption ("Encryption on writes is not yet supported"), and lacks the BLE notification handler and key exchange infrastructure needed to communicate with encrypted devices like the AP300.

Rather than duplicating all of that plumbing into DeviceWriter, this PR adds a write() method to DeviceReader, which already has the full encryption handshake, notification handling, and connection lifecycle in place.

This keeps the encrypted write path minimal and avoids diverging two parallel implementations.

Tests (18 new, all 91 pass)

• NumberField: writeable, parse, range validation, allowed write types
• BluettiDevice: get_number_fields(), sensor exclusion, build_write_command with NumberField
• DeviceReader.write(): switch write, number write, non-writeable rejection
• Updated BLE mock to handle write commands (action=6) separately from reads

README updates

• Added AP300 controls to the Controls table
• Added @happytechca as AP300 contributor
• Updated write command docs to reflect encryption support

A note to @Patrick762

I'm very open to feedback, suggestions, or alternative approaches. If you'd prefer this broken into smaller PRs, scoped differently, or reworked in any way. Thank you!

Side note: Most of this code has been written by Claude Code and manually reviewed before the PR.

[defire04]

Hey! I noticed we solved the same problem in different ways.

I ran into the exact same encryption write problem on my AC180P and opened PR #59 which fixes DeviceWriter directly rather than adding write() to DeviceReader. My thinking was that mixing write logic into the reader makes both harder to reason about over time, and the reader/writer split is a nice boundary to keep.

Then I noticed that even with encryption working, every toggle still took 5–14 seconds because of reconnecting on every write. So I opened a follow-up PR (#60) that introduces a DeviceConnection class to hold a single shared BLE session between reader and writer — subsequent writes drop to ~0.03s.

If you want to see how it all looks wired up on the HA integration side, I have a test branch here:
defire04/hassio-bluetti-bt @ test-encrypted-writes-and-persistent-ble-connection

If PR #59 lands, the DeviceReader.write() part of your PR would create two parallel ways to do the same thing. The AP300 device definition, NumberField, and WorkingMode enum though stand completely on their own — I think it would also be easier for @Patrick762 to review them independently without the write infrastructure mixed in.

Would you consider splitting that out into a separate PR? Happy to hear any thoughts or feedback on my approach too — always open to suggestions

[happytechca]

@defire04 It's funny we worked on the same issue about a day apart.

I agree your approach is better, keeping the write logic in DeviceWriter rather than mixing it into DeviceReader makes a lot more sense from a separation of concerns perspective. And the persistent BLE connection in PR #60 is exactly what was needed. I had the same 5-14s toggle lag on my AP300 and it was on my list to investigate. Glad you already tackled it, initial tests looks good with my AP300 device.

Here's what I've done to move things forward:

1. Opened PR #61 with just the AP300 device model — sensors, controls, NumberField, and WorkingMode enum. No write infrastructure or overlap with your PRs. Can be reviewed/merged on its own.

2. Opened PR #234 on the HA integration side with the number platform and translations for the new AP300 controls.

3. For testing right now, I've combined your work (PRs Enable write commands for encrypted Bluetti devices (AC180P and others) #59 + Persistent BLE connection for instant writes and original app compatibility  #60) with the AP300 model on my fork branches (ap300-combined on both repos). Everything works great on my AP300 — sensors, all controls, encrypted writes, fast persistent connection. Instructions for other AP300 users to test via HACS are in the hassio PR.

I'll close PR #58 since #61 supersedes it.
I prefer to use your PRs as the foundation for write controls on encrypted devices.

Thanks for your work!