Unclear documentation for custom chores

[colececil]

System Health details

System Information

version	core-2024.3.3
installation_type	Unsupported Third Party Container
dev	false
hassio	false
docker	true
user	abc
virtualenv	false
python_version	3.12.2
os_name	Linux
os_version	5.10.131-2-rockchip-g8802564cbf09
arch	aarch64
timezone	America/Chicago
config_dir	/config

Home Assistant Community Store

GitHub API | ok -- | -- GitHub Content | ok GitHub Web | ok GitHub API Calls Remaining | 5000 Installed Version | 1.34.0 Stage | running Available Repositories | 1400 Downloaded Repositories | 12

Home Assistant Cloud

logged_in | false -- | -- can_reach_cert_server | ok can_reach_cloud_auth | ok can_reach_cloud | ok

Dashboards

dashboards | 5 -- | -- resources | 7 views | 5 mode | storage

Recorder

oldest_recorder_run | March 21, 2024 at 7:02 AM -- | -- current_recorder_run | March 30, 2024 at 6:43 PM estimated_db_size | 19.76 MiB database_engine | sqlite database_version | 3.44.2

Checklist

• [X] I have enabled debug logging for my installation.
• [X] I have filled out the issue template to the best of my ability.
• [X] This issue only contains 1 issue (if you have multiple issues, open one issue for each issue).
• [X] This issue is not a duplicate issue of currently previous issues..

Describe the issue

Hi @bmcclure, thanks so much for creating this project! I've been planning on setting up a chore system in Home Assistant, and what you've created almost exactly fits what I envisioned, which is amazing.

One issue I've run into - it seems like there are some details missing from the documentation in how to use custom chores. I've tried a bunch of stuff, but I can't get them to show up on the calendar. Here are the things that are unclear to me:

1. When I call the add_date service, I can see the date gets added in the sensor's "Add dates" field, but nothing else really seems to happen. I'm also not clear on what the "Add dates" field means or how it affects things.
2. The documentation says the update_state service is useful for custom chores, but it doesn't seem to explain how. I tried calling it after calling the add_date service, but it doesn't look like it's doing anything besides updating the "Last updated" timestamp.
3. When creating a new chore sensor, there is an option called "Manual update - sensor state updated manually by a service (Blueprint)". I don't see this option mentioned in the documentation, and I'm unclear on what it does. I tried both with it enabled and with it disabled, but I couldn't find the difference in behavior.

If you can fill me in on these details, I'd be happy to create a pull request with updates to the documentation. Thanks!

Reproduction steps

See details included in the issue description.

Debug logs

I don't think these are needed, but I can provide them later if requested.

Diagnostics dump

No response

[bmcclure]

Thanks for the report! You're absolutely right about the lack of good docs, I hope to get to that soon, but certainly do appreciate the help if you end up contributing to it as well! I honestly have not tested custom chores very much yet myself so I apologize in advance for any oversights there.

1. add_date should add the date to the "add dates" sensor, which is a list that gets pulled from when the chore's state gets updated. Depending on how many future dates are configured to show on the calendar, it should be taking the "add dates" dates into account and showing them when appropriate. Something here may need fixing, though, since it sounds like you might be using it correctly already.
2. I think you're doing it right, but there may be a bug in the integration currently where updating the state isn't using the custom dates correctly. If the chore doesn't have the Manual Update option selected, then calling the update_state service shouldn't even be needed AFAIK. I will try to reproduce this and get it fixed ASAP.
3. "Manual update" is also not tested very thoroughly on my part yet, and the blueprint referenced in the name doesn't exist yet so you'd need to create the service by hand. The idea is that the service can listen for the chore_helper_loaded event to be called and then it can manually fire the update_state service anytime after that at its discretion. This should be unnecessary for normal chores, but is required for any chores with the "Manual update" option enabled since those don't (or at least shouldn't) recalculate their state automatically.

It sounds like there may be some issues that need fixing here based on the details you provided. I will try and reproduce these issues on my local environment, and assuming I can, I'll get them fixed ASAP. On the documentation front, other than the fact that some of this doesn't seem to work currently, I appreciate anything that you're able to clarify or expand on!

[colececil]

Thanks so much for the details. I'll try to take a look at this again soon!