Laundry, meet your smart home.

Path one

The Home Assistant integration

Three steps, and the household appears on your dashboard.

1. Generate a connect key. In The Wash Guide app: Settings → Smart home → Generate connect key. Copy it; it is shown only once, and you can revoke it from the same place at any time. PRO users can generate a control key here too, and paste both into Home Assistant at once.
2. Install the integration. The Wash Guide is in the HACS default store, so this is a plain search: open HACS, search for The Wash Guide, download, and restart. Then Settings → Devices & services → Add integration → The Wash Guide, and paste the key. The control key box on that same screen is optional, and can be filled in later with Configure.

   That badge opens your own Home Assistant instance straight onto the repository page in HACS. The integration is open source and lives at github.com/romuluz/thewashguide-homeassistant. For a setup without HACS, copying custom_components/thewashguide into config/custom_components/ does the same job by hand.

3. That’s it. Entities appear immediately, as one device.

What you get

• sensor.pending_tasks

  Washes waiting on the household board. The pending list rides along as attributes, each task with its id, so a template sensor can slice it per person and the control actions below can name a task precisely. Each task carries a kind, either a wash (a load of laundry) or a machine job (the machine's own maintenance wash).

• sensor.detergent_shield

  The weakest item in the shared cupboard, as a percentage. The full cupboard (each product's name, remaining doses and percentage) comes as attributes, which makes this the natural feed for shopping-list automations. Long-term statistics are recorded, so you get detergent burn-rate graphs for free.

• sensor.last_wash

  A timestamp for the household's most recent wash, with the item, shade, temperature and who ran it as attributes.

• sensor.next_scheduled_wash

  A timestamp for the next standing wash, with what, who and cadence as attributes, plus the full schedule list. Standing schedules are a PRO feature in the app, so in a household without them this sensor simply has no value.

• sensor.loads_since_machine_clean

  How many loads the drum has turned since its last maintenance wash, with clean_due, days_since_clean and the interval the app measures against as attributes. Statistics are recorded, so the sawtooth of a well-kept machine draws itself.

• sensor.last_machine_clean

  A timestamp for when the machine was last cleaned, with who did it, the last filter clean, and the household's recent care record as attributes.

• binary_sensor.wash_overdue

  On when a pending wash has waited more than a day, or when the app's nudge ladder is already active. The overdue tasks and their nudge levels come as attributes. The laundry-room lamp that slowly turns amber starts here.

• binary_sensor.maintenance_wash_due

  On when the drum has earned its empty hot cycle: thirty loads or two months, whichever arrives first. The attributes include whether the job is already on the household board, so a panel can offer to run it rather than ask for it twice.

• binary_sensor.filter_due

  On when the pump filter is due, a quarterly job that is time-based only, because a filter fills with lint and coins rather than loads.

• sensor.<name>_personality

  One per household member: their wash personality title, with tier, 30-day wash count and 30-day rewards (in the household's own reward currency) as attributes.

Events for automations

Four events land on the Home Assistant bus as fresh activity arrives:

• thewashguide_wash_logged (fields: ts, by, item, shade, temp_c)
• thewashguide_task_created (fields: summary, for, kind, tokens, created_at)
• thewashguide_task_completed (fields: summary, for, kind, tokens, completed_at)
• thewashguide_machine_cleaned (fields: kind (MAINTENANCE_WASH or FILTER_CLEAN), ts, by)

automation:
  - alias: "Celebrate a finished wash task"
    trigger:
      - platform: event
        event_type: thewashguide_task_completed
    action:
      - service: notify.family
        data:
          message: >
            {{ trigger.event.data.for }} finished
            "{{ trigger.event.data.summary }}"
            {% if trigger.event.data.tokens %}
            and earned {{ trigger.event.data.tokens }} rewards
            {% endif %}.

Data updates every 15 minutes, or every minute for a PRO household. The cloud tells the integration which cadence the plan allows and it paces itself, so an upgrade takes effect on the next poll with nothing to reconfigure. Anyone who would rather poll less often than their plan allows can set an interval in the integration’s options; it can never poll more often.

The connect key grants read-only access to the household’s laundry status: tasks, cupboard level, wash personalities, recent washes and the machine’s care record. It cannot log washes, change anything, or read anything outside the household. Revoking the key in the app cuts access on the next refresh.

Taking action (PRO)

With PRO, the smart home stops being read-only. Alongside the free connect key, the app can generate a control key (Settings → Smart home → Generate control key; the key list labels each key’s scope plainly). Paste it into the integration, at setup or later with Configure, and four services appear:

• thewashguide.create_task: post an open wash task to the household board, which anyone in the house can claim. The summary, note, load facts and a reward are all optional; a bare call posts a mixed, medium load. Attaching a reward requires an operator.
• thewashguide.cancel_task: cancel a task still waiting on the board. Operators may cancel any pending task; everyone else, their own.
• thewashguide.request_maintenance_wash: put the machine’s maintenance wash on the board. Open to the house by default, because the machine is nobody’s in particular; name a member to hand it to them.
• thewashguide.log_machine_clean: record that the machine was looked after, either the maintenance wash or the filter. If the maintenance wash is already waiting on the board, this completes that task rather than logging a second, parallel truth.

The key’s owner is the actor: your automations act as you, under the same household rules as the app itself. Rewards need an admin or a manager, juniors cannot create tasks at all, and a connect key presented where a control key is required is refused.

One line is worth explaining, because it is a design position rather than a limitation: a wash task cannot be completed from the smart home, and a maintenance wash can. Completing a wash means a person ran a load of laundry, spent detergent from the cupboard and added to their wash history, and an automation cannot honestly claim any of that. A maintenance wash is the opposite case. An empty drum at 90 degrees produces no laundry, spends no detergent and enters no wash log; the only thing it produces is the fact that it ran, and a washing machine that has just finished its cycle knows that fact better than the person who will remember to mention it on Thursday.

automation:
  - alias: "The machine asks for its own maintenance wash"
    trigger:
      - platform: state
        entity_id: binary_sensor.maintenance_wash_due
        to: "on"
    condition: >
      {{ not state_attr('binary_sensor.maintenance_wash_due',
                        'on_the_board') }}
    action:
      - service: thewashguide.request_maintenance_wash
        data:
          note: "The drum has done thirty loads since the last one."

  - alias: "And logs it when the cycle finishes"
    trigger:
      - platform: state
        entity_id: sensor.washing_machine_power
        below: 5
        for: "00:05:00"
    condition: "{{ is_state('input_boolean.running_maintenance_wash', 'on') }}"
    action:
      - service: thewashguide.log_machine_clean
        data:
          kind: maintenance_wash
      - service: input_boolean.turn_off
        target:
          entity_id: input_boolean.running_maintenance_wash

For anyone who would rather not install the integration, the control endpoint also answers a plain rest_command. The app shows its address beside the key.

rest_command:
  washguide_task:
    url: !secret washguide_control_url
    method: post
    headers: { x-api-key: !secret washguide_control_key }
    content_type: application/json
    payload: '{"action":"create_open_task","summary":"{{ summary }}"}'

Questions

The short answers