Add a sensor for Yale Lock operation

[wbyoung]

Breaking change

Proposed change

There needs to be a way to access the activity from Yale Access BLE. I followed the way that the Yale integration is handling things and added a sensor.

Some requirements I think are worth considering:

• No activity should be discarded. When the yalexs_ble package reads the activity, it is removed from the lock and the Yale app will not be able to see it either.
• Users should be able to react to all activity with triggers.
• By default, the integration should not consume activity as it will be unexpected for users and would "break" other consumers of the activity.
• Disabling the sensor should be sufficient to disable the consumption of activity. Per the above point, starting with it'll disabled by default should be a preferred solution.

Ideas on how things could be improved:

• Consider not writing the state until after a brief delay, putting the current update in a pending state while waiting to see if more activity comes from the lock during that delay. Most of the time, then, only the most recent change will be written to HA state (which will likely cause less confusion).
• Write all activity to the recorder's history for the sensor to show a more accurate timeline of activity. I may be looking in the wrong places, but it looks like the only integrations they seem to do this are energy related components, so this may end up being an idea that's a little out there.
• Emit events to the bus for each activity to avoid missing out on proving an opportunity for all activity to be acted upon (see requirements above).

Type of change

• Dependency upgrade
• Bugfix (non-breaking change which fixes an issue)
• New integration (thank you!)
• New feature (which adds functionality to an existing integration)
• Deprecation (breaking change to happen in the future)
• Breaking change (fix/feature causing existing functionality to break)
• Code quality improvements to existing code or addition of tests

Additional information

• This PR fixes or closes issue: fixes #
• This PR is related to issue:
• Link to documentation pull request:
• Link to developer documentation pull request:
• Link to frontend pull request:

Checklist

• The code change is tested and works locally.
• Local tests pass. Your PR cannot be merged unless tests pass
• There is no commented out code in this PR.
• I have followed the development checklist
• I have followed the perfect PR recommendations
• The code has been formatted using Ruff (ruff format homeassistant tests)
• Tests have been added to verify that the new code works.

If user exposed functionality or configuration variables are added/changed:

• Documentation added/updated for www.home-assistant.io

If the code communicates with devices, web services, or third-party tools:

• The manifest file has all fields filled out correctly.
  Updated and included derived files by running: python3 -m script.hassfest.
• New or updated dependencies have been added to requirements_all.txt.
  Updated by running python3 -m script.gen_requirements_all.
• For the updated dependencies - a link to the changelog, or at minimum a diff between library versions is added to the PR description.

To help with the load of incoming pull requests:

• I have reviewed two other open pull requests in this repository.

[home-assistant]

Hey there @bdraco, mind taking a look at this pull request as it has been labeled with an integration (yalexs_ble) you are listed as a code owner for? Thanks!

Code owner commands

Code owners of yalexs_ble can trigger bot actions by commenting:

• @home-assistant close Closes the pull request.
• @home-assistant rename Awesome new title Renames the pull request.
• @home-assistant reopen Reopen the pull request.
• @home-assistant unassign yalexs_ble Removes the current integration label and assignees on the pull request, add the integration domain after the command.
• @home-assistant add-label needs-more-information Add a label (needs-more-information, problem in dependency, problem in custom component) to the pull request.
• @home-assistant remove-label needs-more-information Remove a label (needs-more-information, problem in dependency, problem in custom component) on the pull request.

[wbyoung]

I'll be working through getting the necessary support in the yalexs_ble at Yale-Libs/yalexs-ble#256 before this is ready for review, but it's working as expected locally.

[wbyoung]

Here's a diff for a proof of concept that implements the following:

• Immediate firing of an event with lock activity as it's received from the yalexs_ble library.
• Delayed updating of the HA sensor (by 2 sec) to allow updates to be coalesced into a single state change (to the most recent activity state). This may not work in every case as it's possible that the time to receive the next activity exceeds the 2 sec threshold.
• Writing activity that's passed over into the recorder so that it's still available in the History of the sensor.

If this approach were approved, the code would probably need to be refactored to add a coordinator to the integration. Putting this logic in a coordinator would better replicate the style across HA integrations with respect to separation of concerns.

[bdraco]

In Home Assistant's architecture, entity states are always meant to represent the current, real-time state (or as close as possible) of devices. Since lock operations/activities are inherently historical data (they represent past events like "locked 5 minutes ago" or "unlocked by user X at 3pm"), and we don't have access to them in real-time, a sensor entity storing this information would not be accepted as it violates core architectural principles.

While events aren't a perfect fit either (they're really designed for real-time occurrences), they're the best mechanism we currently have in Home Assistant for handling this type of historical activity data. The key difference is that events don't pollute the state machine with non-current data.

[bdraco]

Also there is definitely some demand for inserting historical data, and its come up many times before. An architecture discussion on home-assistant/architecture#580 this topic that has yet to conclude.

Inserting historical states into the database would need an approved arch discussion and a proper API on the recorder history module like stats currently has.

[wbyoung]

Inserting historical states into the database would need an approved arch discussion and a proper API on the recorder history module like stats currently has.

Yes, I had a feeling that I was hacking around in ways that would be rejected. 😛 I'll subscribe to that discussion and see how it resolves. I know it's a Pandora's box sort of situation for HA to handle historic data.

For my use case, I'll be 100% content with consuming events. So I'll give it another go with events.

Would a proper event entity or just something fired on the bus be preferred? The Event Entity seems more suited to things as they're happening as well, but has the advantage of being easier to enable/disable as well as easier to discover.

[github-actions]

There hasn't been any activity on this pull request recently. This pull request has been automatically marked as stale because of that and will be closed if no further activity occurs within 7 days.
If you are the author of this PR, please leave a comment if you want to keep it open. Also, please rebase your PR onto the latest dev branch to ensure that it's up to date with the latest changes.
Thank you for your contribution!

[wbyoung]

I will be coming back to this soon.

@bdraco if you have any opinions on the change in direction, it would help. My previous comment had the main question that needs input:

Would a proper event entity or just something fired on the bus be preferred?

[github-actions]

There hasn't been any activity on this pull request recently. This pull request has been automatically marked as stale because of that and will be closed if no further activity occurs within 7 days.
If you are the author of this PR, please leave a comment if you want to keep it open. Also, please rebase your PR onto the latest dev branch to ensure that it's up to date with the latest changes.
Thank you for your contribution!

[wbyoung]

@bdraco I've taken another stab at this and updated the underlying yalexs-ble PR, Yale-Libs/yalexs-ble#256.

In this iteration, I've stopped using a sensor and have switched over to using an Event entity type. The entity is disabled by default (which prevents consuming the activity from the lock). With documentation, it should be clear why this is the case and how to use this event. I think this seems like a pretty good compromise on how to get this feature into HA.

Let me know what you think and how to move forward from here. Sorry it took so long for me to get back to this.

Oh, this is also technically incomplete still until the PR gets merged in yalexs-ble because we'll also need to update the dependency here.