HA Backend Integration

The TappRFID backend integration connects your HA instance to the TappRFID cloud. Once installed and authenticated, HA creates sensor entities for every task and log in your account. You can use these sensors in dashboards, automations, and scripts — and optionally trigger task completions back from HA.

Requirements

Active TappRFID cloud subscription
Cloud sync enabled in the app (see Cloud Sync)
Home Assistant 2023.4 or later
HACS installed for the recommended install path

Install via HACS (recommended)

HACS lets you install and update the integration from the HA UI without touching the filesystem.

Open Home Assistant and go to HACS in the sidebar.
Click Integrations.
Click the three-dot menu (⋮) in the top right and choose Custom repositories.

In the Repository field, enter:

https://github.com/mrcpuddington/tap-home-assistant-integration

Set Category to Integration and click Add.
Close the dialog. Search for TappRFID in HACS Integrations.
Click TappRFID → Download → confirm the version and click Download again.
Restart Home Assistant — the integration won’t appear until HA restarts.

Install manually (ZIP)

Use this if you prefer not to use HACS or can’t install it.

Go to the TappRFID integration repository on GitHub and download the latest release ZIP from the Releases section.
Extract the ZIP. Inside you’ll find a folder named tap_rfid.

Copy the tap_rfid folder into your HA config directory:

/config/custom_components/tap_rfid/

The result should look like:

/config/
└── custom_components/
    └── tap_rfid/
        ├── __init__.py
        ├── manifest.json
        ├── sensor.py
        └── ...

Restart Home Assistant.

Connect and authenticate

After installing and restarting:

In Home Assistant, go to Settings → Devices & Services.
Click + Add Integration (bottom right).
Search for TappRFID and select it.
A browser window opens for OAuth sign-in. Use the same account credentials as in the TappRFID app.
Authorise the connection. You’ll be redirected back to HA.
The integration appears as connected with a device entry.

Verify the connection in the app

In TappRFID: Settings → Home Assistant → Verify Home Assistant Connection.

You should see a success message. If not, check the troubleshooting section below.

Entities created

Once connected, HA creates sensor entities for every task and log in your account. Entities update in near real-time as you make changes in the app.

Task sensors

Each task creates one sensor:

sensor.tapprfid_<task_name>

States:

State	Meaning
`overdue`	Past due — the task hasn’t been completed in time
`due_soon`	Due within the next few hours (configurable threshold)
`on_track`	Completed recently, next due date is in the future
`complete`	Completed today (for daily tasks)
`unavailable`	Entity can’t be reached — check connection

Attributes:

Attribute	Type	Description
`task_id`	string	UUID — use this in service calls
`last_completed`	datetime	When the task was last completed
`streak`	integer	Current consecutive completion streak
`next_due`	datetime	When the task is next due
`interval_days`	float	Recurrence interval
`friendly_name`	string	Display name from the app

Log sensors

Each log creates one sensor:

sensor.tapprfid_log_<log_name>

States: Timestamp of the most recent log entry (ISO 8601 string), or unknown if no entries exist.

Attributes:

Attribute	Type	Description
`log_id`	string	UUID — use this in service calls
`entry_count`	integer	Total number of entries
`last_note`	string	Note text from the most recent entry (if any)
`friendly_name`	string	Display name from the app

Service calls

Service calls let HA trigger actions back in TappRFID — completing tasks, reopening them, or adding log entries. These actions sync to the app within seconds.

Complete a task

service: tap_rfid.complete_task
data:
  task_id: "YOUR_TASK_UUID"

Marks the task complete with the current timestamp. This is equivalent to tapping the task in the app.

Reopen a task

service: tap_rfid.reopen_task
data:
  task_id: "YOUR_TASK_UUID"

Removes the most recent completion, marking the task as incomplete. Use this if you accidentally completed a task.

Add a log entry

service: tap_rfid.add_log_entry
data:
  log_id: "YOUR_LOG_UUID"
  note: "Optional note text"

Adds an entry to a log. The note field is optional.

Find task and log IDs

In Home Assistant: open the entity, go to the Attributes section, copy task_id or log_id.
In the TappRFID app: open the task or log detail screen — the UUID is shown at the bottom under the debug section (Settings → Debug must be enabled).

Configuration options

In TappRFID: Settings → Home Assistant:

Option	Default	Description
Enable HA Sensors	On	Creates and updates sensor entities in HA
Enable HA Actions	Off	Allows service calls to complete/reopen tasks and add log entries
Due Soon Threshold	2 hours	How far in advance a task enters `due_soon` state

Read-only mode: Leave Enable HA Actions off if you want sensor data in dashboards without allowing HA to write back to your tasks.

Updating the integration

Via HACS

HACS will show a pending update when a new version is available. Go to HACS → Integrations → TappRFID and click Update. Restart HA after updating.

Manually

Download the new release ZIP, replace the tap_rfid folder in /config/custom_components/, and restart HA.

Troubleshooting

Integration not appearing after install:

Confirm you restarted HA after installing.
Check /config/custom_components/tap_rfid/ exists and contains manifest.json.
Clear your browser cache if using the web UI.

Authentication fails or redirects incorrectly:

Confirm your cloud account is connected and active in the TappRFID app.
Try removing the integration (Settings → Devices & Services → TappRFID → Delete) and re-adding it.
Check that your HA instance has outbound internet access.

Entities show unavailable:

In TappRFID: Settings → Home Assistant → Verify Connection.
Check cloud sync is running: Settings → Cloud Account.
Review HA logs: Settings → System → Logs → filter for tap_rfid.

Service call fails with “unknown service”:

Confirm Enable HA Actions is on in the app.
Confirm the integration is connected (not just installed).
Reload the integration: Settings → Devices & Services → TappRFID → ⋮ → Reload.

Entities not updating after app changes:

The integration polls every 30 seconds by default. Wait up to a minute.
Trigger a manual sync in the app: pull-to-refresh on any screen.
Check Settings → Debug → Sync log in the app for errors.

For dashboard display, see the Lovelace Card docs. For automation examples, see Automations.