Document the full API, add periodic charge/discharge endpoints, fix error handling - #28
Open
Poshy163 wants to merge 1 commit into
Open
Conversation
…ix error handling Supersedes the work on feature/time-charge-endpoints, whose RETURN_CODES table, success-detection helper and tests are carried over here. Documentation ------------- The developer portal needs registration to read, so mirror it in docs/: - docs/API.md - all 19 endpoints, each with what it needs, what it returns (every field, type and unit), a captured live response, and the matching library method. - docs/RETURN_CODES.md - the complete return code table (both pages of the portal's paginated list), grouped by cause. Verified endpoint by endpoint against the live API, which turned up four places where the official documentation is wrong: - getVerificationCode is GET, not POST (POST returns HTTP 405) - bindSn is POST, not GET as the bundled Postman collection has it - getOneDayPowerBySn returns cbat/pchargingPile, not cobat/pChargingPile - return code 6017 "No operation permissions" exists but is unpublished New endpoints ------------- getTimeChargeBySn and setTimeChargeBySn - the periodic (weekly) scheduler. Up to 6 periods per day, per-weekday selection and a power setpoint per period, where updateChargeConfigInfo only offers two daily periods. Exposed on getdata() behind get_timecharge=False. The flag is appended after self_delay so existing positional callers are unaffected. Not every system is entitled to it - systems without the feature answer 6017, which is handled as "feature unavailable" rather than an error. Fixes ----- - getVerificationCode used POST, which the API rejects with a 405. It could never have worked. Now GET. - Wrapper methods caught exceptions from api_get()/api_post(), logged them and returned None without re-raising, so a transport failure reached the caller indistinguishable from an empty result. homeassistant-alphaESS relies on the exception surfacing to mark an update failed and retry with backoff, so entities could sit unavailable long after the network recovered. All 19 wrappers now re-raise. Fixes CharlesGillanders#26. - api_post() logged an error on success-with-payload and returned None silently on genuine API errors - the two branches were inverted, so a failed write was invisible. Return values are unchanged. - Success detection now accepts code 200, "msg" or "info". The portal documents the periodic endpoints as using "info" while the live API returns "msg" for all 19. - Failed responses now log the decoded return code description, so "6017" reads as "(No operation permissions)" instead of a bare number. Tests ----- 34 tests, no network access - the aiohttp session is mocked. Cover the new endpoints, success detection via each of the three signals, that transport errors re-raise from all 19 wrappers, that API-level errors still return None, that getVerificationCode issues a GET, and that getdata keeps self_delay positional.
Contributor
Author
|
Bump @CharlesGillanders. this is needed to start the fix towards CharlesGillanders/homeassistant-alphaESS#267 and CharlesGillanders/homeassistant-alphaESS#269 |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Mirrors the AlphaESS developer portal docs into
docs/and adds the two periodic charge/discharge endpoints.Also contains the fixes from #26 / #27, and bumps the version to 0.0.20.
Docs
The portal needs an account to read, which makes it awkward to point people at. So it's mirrored here:
docs/API.md- all 19 endpoints, what each takes and returns, with a real response for eachdocs/RETURN_CODES.md- the return code table (both pages of it)I called every endpoint while writing it and hit a few things the portal gets wrong:
getVerificationCodeis GET, not POST. POST just 405s, so our version could never have worked.bindSnis POST, not GET like the Postman collection in the repo has itgetOneDayPowerBySnreturnscbat/pchargingPile, the docs saycobat/pChargingPile6017 No operation permissionsthat isn't in the return code list at allNew endpoints
getTimeChargeBySn/setTimeChargeBySn. Same idea asupdateChargeConfigInfobut you get 6 periods a day instead of 2, per weekday, with a power setpoint.Wired into
getdata()behindget_timecharge=False. It's afterself_delayin the signature so existing positional calls don't break.Not every system can use it. Mine (SMILE5) returns 6017 on both inverters, so that's treated as "not available" rather than an error.
Fixes
getVerificationCodewas POSTing, now GETsapi_posthad its branches the wrong way round, logging an error on success and silently returning None on failure, so a failed write was invisible(No operation permissions)instead of a bare number