Add acknowledgements for proxy subscribe and configuration requests

[kbx81]

What does this implement/fix?

Client side of the proxy request acknowledgements introduced in esphome/esphome#18312 (API 1.16). Devices now answer serial proxy subscribe/unsubscribe/configure/modem-pin requests and Z-Wave proxy subscribe/unsubscribe with a status, including a denial reason (PORT_IN_USE / IN_USE) when another client holds the subscription.

• api.proto synced with the firmware repo; bindings regenerated via the docker builder. New ZWaveProxyRequestResponse (id 151) with ZWaveProxyStatus; SerialProxyStatus gains PORT_IN_USE and INVALID_ARGUMENT; SerialProxyRequestType gains the response-only CONFIGURE and SET_MODEM_PINS discriminators.
• The existing serial_proxy_subscribe_await_response / serial_proxy_unsubscribe_await_response methods now work (the firmware previously never sent the response they await, so they always timed out).
• New methods: serial_proxy_configure_await_response, serial_proxy_set_modem_pins_await_response, zwave_proxy_subscribe, zwave_proxy_unsubscribe, zwave_proxy_subscribe_await_response, zwave_proxy_unsubscribe_await_response.
• All *_await_response methods gate on the device API version: below 1.16 the request is sent fire-and-forget and None is returned, so callers never hang against older firmware. serial_proxy_flush is deliberately not gated — its acknowledgement predates 1.16.

Verified against real hardware (ESP32-S3 with W5500 ethernet) in three directions: this client against API 1.16 firmware (all acknowledgement and denial paths), this client against pre-1.16 firmware (fallback returns None immediately, flush still round-trips), and the released 45.10.0 client against API 1.16 firmware (unsolicited acks are ignored cleanly, unknown id 151 skipped at debug level).

Types of changes

• Bugfix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)
• Code quality improvements to existing code or addition of tests
• Other

Related issue or feature (if applicable):

• fixes

Pull request in esphome (if applicable):

• [api] Acknowledge proxy subscribe and configuration requests esphome#18312

Checklist:

• The code change is tested and works locally.
• If api.proto was modified, a linked pull request has been made to esphome with the same changes.
• Tests have been added to verify that the new code works (under tests/ folder).

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 100.00%. Comparing base (cfbbfb2) to head (b338d4f).
⚠️ Report is 1 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff            @@
##              main     #1865   +/-   ##
=========================================
  Coverage   100.00%   100.00%           
=========================================
  Files           26        26           
  Lines         4288      4339   +51     
=========================================
+ Hits          4288      4339   +51     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[codspeed-hq]

Merging this PR will not alter performance

✅ 56 untouched benchmarks

---

_{Comparing kbx81:proxy-subscribe-acks (b338d4f) with main (cfbbfb2)¹}

Footnotes

1. No successful run was found on main (b9eb7b4) during the generation of this report, so cfbbfb2 was used instead as the comparison base. There might be some changes unrelated to this pull request in this report. ↩

[coderabbitai]

Walkthrough

The protocol now defines serial and Z-Wave proxy acknowledgements. APIClient supports API 1.16 response handling with legacy fallback. Models, message registration, validation, and client tests cover the new operations and statuses.

Changes

Proxy acknowledgement support

Layer / File(s)	Summary
Acknowledgement contracts and models aioesphomeapi/api.proto, aioesphomeapi/model.py, aioesphomeapi/core.py	Added Z-Wave acknowledgement messages and statuses. Added serial configure and modem-pin request types and error statuses. Registered and exported the new model.
Version-gated proxy request handling aioesphomeapi/client.py	Added validated serial request builders and acknowledgement-aware configure, modem-pin, subscribe, unsubscribe, and Z-Wave proxy methods. Older devices retain fire-and-forget behavior.
Acknowledgement and compatibility coverage tests/test_client.py	Added tests for response matching, statuses, validation, denied operations, API 1.16 handling, and pre-1.16 behavior.

Estimated code review effort: 4 (Complex) | ~45 minutes

Sequence Diagram(s)

sequenceDiagram
  participant APIClient
  participant ESPHomeDevice
  APIClient->>ESPHomeDevice: Send proxy request
  alt API 1.16 or newer
    ESPHomeDevice-->>APIClient: Return matching acknowledgement
    APIClient-->>APIClient: Return response model
  else API below 1.16
    APIClient-->>APIClient: Return None after sending
  end

Loading

Possibly related PRs

• esphome/aioesphomeapi#1845: Adds related Z-Wave proxy protocol support in the same API and model registration areas.

Suggested reviewers: bdraco, jesserockz, bluetoothbot

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly summarizes the main change: adding acknowledgements for proxy subscription and configuration requests.
Description check	✅ Passed	The description directly explains the client-side acknowledgement support, compatibility behavior, API changes, and tests.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

🧹 Nitpick comments (1)

aioesphomeapi/client.py (1)

831-837: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚖️ Poor tradeoff

Place private helpers after public API methods.

These underscore-prefixed helpers are placed between public API methods. Move them to the class private-helper section after the public API methods.

As per coding guidelines: “Organize methods with public API at the top and private helpers (_underscore_prefixed) at the bottom.”

Also applies to: 852-857, 903-907

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@aioesphomeapi/client.py` around lines 831 - 837, Move the private helper
methods _await_serial_proxy_response and the other underscore-prefixed methods
identified in this area below all public API methods in the client class,
keeping their implementations unchanged and preserving the existing
private-helper section organization.

Source: Coding guidelines

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Nitpick comments:
In `@aioesphomeapi/client.py`:
- Around line 831-837: Move the private helper methods
_await_serial_proxy_response and the other underscore-prefixed methods
identified in this area below all public API methods in the client class,
keeping their implementations unchanged and preserving the existing
private-helper section organization.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 5e61ee06-3a1a-44dd-87b5-988e755164fb

📥 Commits

Reviewing files that changed from the base of the PR and between b9eb7b4 and b338d4f.

📒 Files selected for processing (6)

• aioesphomeapi/api.proto
• aioesphomeapi/api_pb2.py
• aioesphomeapi/client.py
• aioesphomeapi/core.py
• aioesphomeapi/model.py
• tests/test_client.py