HomeAssistant - Tapo: Cameras Control
Custom component - Tapo: Cameras Control - to add Tapo cameras, doorbells and chimes into Home Assistant
⭐ Now also exposing a stream for devices that have no RTSP or ONVIF capabilities.
Contributing
Before opening a pull request, read CONTRIBUTING.md, especially if the work used an AI assistant.
AI-assisted contributions are welcome when the author has reviewed, understood, and can explain the changes. Purely AI-generated or “vibe coded” PRs where the author did not review the code and behavior are not welcome and may be closed. Reviewing unverified generated code often takes longer than implementing the change directly.
AI coding assistants must read AGENTS.md and CONTRIBUTING.md before modifying files, creating commits, pushing branches, or opening PRs.
Please keep PRs small, focused, tested, and easy to review. Be explicit about what was tested, what was not tested, what device models were used, and whether AI generated or drafted any part of the change.
For changes that need Home Assistant runtime verification, AI assistants should guide the user through testing in their Home Assistant instance, review the results with them, and iterate until the behavior is understood.
Installation
Copy contents of custom_components/tapo_control/ to custom_components/tapo_control/ in your Home Assistant config folder.
Installation using HACS
HACS is a community store for Home Assistant. You can install HACS and then install Tapo: Cameras Control from the HACS store.
Requirements
Network
Following (v)LAN ports must be open in firewall for the camera to access your Tapo Device from Home Assistant:
Chimes:
- TCP/80 - HTTP for control of the camera (services)
Cameras and Doorbells:
- TCP/443 - HTTPS for control of the camera (services)
- TCP/8800 - Proprietary protocol for video streaming and recordings downloads (if available on device)
- TCP/554 - RTSP to fetch video stream from the camera (if available on device)
- TCP/2020 - ONVIF to track detected movement via a binary sensor (if available on device)
- UDP/20005 (broadcast) for doorbell press event on standalone doorbell, or hub for a doorbell
These are not WAN ports, DO NOT OPEN WAN PORTS VIA PORT FORWARDING. You might need to open (v)lan ports only if you know what all of this means.
Third-Party Compatibility
Ensure you have Third Party Compatibility turned on in the official Tapo app on your smartphone.
Tapo App -> Me -> Third-Party Compatibility -> On
Usage
Add cameras, doorbells or chimes via Integrations (search for Tapo: Cameras Control) in Home Assistant UI. You can also simply click the button below if you have MyHomeAssistant redirects set up.
Note: There are other Tapo integrations, make sure you select Tapo: Cameras Control. Otherwise you might choose the one for plugs and lights, or the official HA one which has a minimum feature set compared to this integration as of December 2024.
When integrating Tapo cameras, doorbells and chimes, ensure only ONE integration is used. If multiple are used at the same time it will result in conflicts and instability of connection to camera for all the integrations / services connecting to camera.
If you are adding a chime, set Control Port to 80 instead of 443.
Devices are also automatically discovered when they are (re)connected to WIFI.
To add multiple devices, add integration multiple times.
See examples for lovelace cards.
Quick Start
This custom component creates:
Doorbells, Cameras (for each lens, if supported):
- Up to 4 camera entities: HD and SD, using RTSP standard or TP-Link proprietary video protocol. If you choose to use direct entities, it is recommended to disable
Use Stream from Home Assistant in options for the best performance and battery life.
- Binary sensor for motion after the motion is detected for the first time and a binary sensor for doorbell press
- Light entity, if the camera supports a floodlight switch and nightlight light entity with on/off and brightness control
- Buttons for Calibrate, Format, Manual Alarm start & stop, Moving the camera, Reboot and syncing time
- Switch entities for Auto track, Automatic Reboot, Flip setting, LED Indicator, Lens Distortion Correction, (Rich) Notifications, Recording, Microphone Mute, Microphone Noise Cancelling, Automatically Upgrade Firmware, HDR mode, Alarm Trigger Event types, Privacy Zones, Diagnose Mode, Smart Track specific switches, Smart Dual Track specific switches, Preset Patrol Mode, Audio Recording and Privacy mode
- Select entities for Automatic Alarm, Automatic Reboot Time, Light Frequency, Motion Detection, Night Vision, Spotlight Intensity, Alarm Type, Quick Response, Smart Dual Track Method and Move to Preset
- Number entity for Movement Angle, Speaker Volume, Microphone Volume, Spotlight Intensity, Siren Volume, Siren Duration and Motion Detection Digital Sensitivity
- Media Source for browsing and playing recordings stored on camera
- Sensor entity that reports monitor media sync status
- Sensor entities for Storage diagnostics and Last Automatic Reboot Time
Chimes:
- Number entity for Chime Duration, Chime Volume, Chime Play Duration and Chime Play Volume
- Switch entity for Chime Ringtone and LED
- Select entity for Chime Sound Type and Chime Play Type
- Sensor entities for Network SSID, Signal Level, RSSI
- Button entity for Reboot and Ringing the chime
Additionally, following services are available for cameras:
tapo_control.save_preset
Saves the current PTZ position to a preset
- name Required: Name of the preset. Cannot be empty or a number
tapo_control.delete_preset
Deletes a preset
- preset Required: PTZ preset ID or a Name. See possible presets in entity attributes
tapo_control.set_record_plan
tapo_control.set_record_plan updates the weekly recording schedule on cameras that support it. Target one camera entity for the device (HD, SD, or Direct).
- enabled (required): Enable or disable recording. Disabling does not clear the schedule.
- sunday through saturday (optional): Lists of
HHMM-HHMM:mode periods in the camera’s local time. Mode 1 records continuously; mode 2 records on motion. Use 2400 for the end of the day. Split overnight periods across two days.
- Omitted days remain unchanged. An empty list (
[]) clears that day’s schedule. Gaps between periods have no recording.
For example, update Monday and clear Sunday while leaving the other days unchanged:
action: tapo_control.set_record_plan
target:
entity_id: camera.your_camera_hd
data:
enabled: true
monday:
- "0000-0700:1"
- "0700-2400:2"
sunday: []
After the call, check the camera entity’s record_plan attribute and the schedule in the Tapo app. The Record to SD Card switch reflects whether recording is enabled.
Sound Detection
Integration is capable of analysing sound from camera microphone and expose noise detected via binary_sensor.
You need to enable this feature in integration options by checking “Enable sound threshold detection”. After enabling it, you can also set any other options starting with [Sound Detection]. You will need to restart Home Asssistant after doing any changes.
For more information and troubleshooting see Home Assistant ffmpeg documentation on which this feature is based on.
Integration is capable of synchronizing recordings for fast playback.
Synchronization is turned off by default, you can browse media stored on camera and request it to be played. However, downloading is rather slow, so it is a good idea to enable media synchronization in background. That way, you will be able to play any synchronized media from camera instantly.
Requested recordings download in the background, with progress shown in a notification. While a download is active, cached recordings remain playable. Reloading the integration cancels its on-demand downloads; switching media sync off lets the current recording finish before the sync stops.
A ✓ at the beginning of a recording’s title means its video is downloaded and ready to play (for example, ✓00:00:02–00:00:04). Refresh or reopen the recording list after a download finishes to see the checkmark; a preloaded thumbnail alone does not mark a recording as ready.
With both Cache thumbnails and Preload thumbnails enabled, the initial media scan after startup downloads available detection-event thumbnails for recordings, even when video synchronization is disabled. Battery and solar-powered cameras skip this bulk thumbnail download to let them return to sleep sooner; thumbnails are requested for the selected day when you browse recordings instead. Each recording uses the thumbnail of the first detection event that starts within it. The images are saved in the cold storage thumbs folder without downloading the videos. Existing thumbnails are reused, and thumbnails are copied to hot storage when you browse the recordings. Recordings without a matching event, or cameras that cannot list events or provide snapshots, still get a generated thumbnail when the video is downloaded.
If the initial media scan fails (for example, because no SD card is inserted), retries use the battery polling interval on battery and solar-powered cameras (10 minutes by default), or 60 seconds on mains-powered cameras. This applies even when video synchronization is disabled. An available camera or newly inserted card can therefore be detected on a later retry without reloading the integration.
You can enable this setting by navigating to Home Assistant Settings -> Devices & services and clicking the Tapo: Cameras control integration. There, click on the Configure button next to the Tapo device you wish to turn media synchronization on for, and choose Configure media. Here, you need to define the number of hours to synchronize. Unless it is specified, synchronization does not run. Here, you are able to also set the storage path where the synchronized recordings will be stored (defaults to /config/.storage/tapo_control).
The default storage is included in Home Assistant configuration backups. To keep recordings and thumbnails out of those backups, choose a directory such as /media/tapo_control/front_camera and exclude media from your backups.
The same Configure media form includes two options. Cache thumbnails is off and Preload thumbnails is on by default. This loads thumbnails only while browsing and removes them after about five minutes.
| Cache thumbnails |
Preload thumbnails |
Behavior for videos not yet downloaded |
| On |
On |
Fetch thumbnails at startup and while browsing; keep them while the recordings remain on the camera. |
| On |
Off |
Fetch thumbnails only while browsing; keep them while the recordings remain on the camera. |
| Off |
On |
Fetch thumbnails only while browsing; delete disk and web copies after about five minutes. |
| Off |
Off |
Do not fetch or display thumbnails for undownloaded videos; remove any previously cached copies. |
These options do not disable thumbnails for downloaded videos, including videos downloaded for playback. Battery and solar cameras still skip startup thumbnail preloading. Changing either option reloads the camera entry and cancels active downloads.
Finally, you can turn on, or off switch entity switch.*_media_sync.
Notice: Recordings are deleted after the number of hours you have chosen to synchronize passes, once both the actual recording time and the file modified time is older than the number of hours set.
With thumbnail caching enabled, thumbnails are kept independently of this video retention period. They are removed once a subsequent startup scan finds that the recording is no longer on the camera. With caching disabled, thumbnails remain while their downloaded videos exist; other thumbnails follow the short retention described above.
Whenever a recording is downloaded (either because you requested playback or media sync picked it up), the integration fires a Home Assistant event tapo_control_media_downloaded with data:
entry_id: Config entry id of the devicestartDate / endDate: Recording start/end timestamps (UTC, in seconds)filePath: Full path to the downloaded mp4 in cold storage
Example automation trigger:
trigger:
- platform: event
event_type: tapo_control_media_downloaded
action:
- service: notify.mobile_app_phone
data:
message: >
New Tapo recording from {{ trigger.event.data.startDate | timestamp_local }}
Troubleshooting | FAQ
I see error `Invalid cloud password.`
These steps apply even if camera worked before, and now does not (for example, after firmware update).
After every step, test if camera works in HA, and after each step try checking Third-Party Compatibility off and on again.
- Ensure you have Third Party Compatibility turned on in official Tapo app on your smartphone. Tapo App -> Me -> Third-Party Compatibility -> On
- Try checking Third-Party Compatibility off and on again and opening the camera via Tapo App, while being on the same network as the camera is.
- Reset your password.
- Make sure your camera can access the internet.
- Reboot your camera a few times.
- Reset the camera. Remove it from your account, do a factory reset, add it back with internet access, add it back to the integration.
- If all of this fails (unlikely) repeat from step 1, wait a few hours and try again.
Which stream to use?
This integration exposes 4 different camera entities:
- HD Stream
- SD Stream
- HD Stream (Direct)
- SD Stream (Direct)
Direct streams use proprietary TP-Link streaming protocol. Non-direct ones use standard RTSP protocol.
Why use the Direct streams?
- If you have a device which does not have RTSP functionality, it is the only way. This includes battery devices, solar devices, as well as devices working through a hub.
- If you have used up all your RTSP streams and/or your RTSP streams are unstable in Home Assistant.
- Direct streams are extremely fast to load and have less than a half a second delay in stream* (*make sure to DISABLE
Use Stream from Home Assistant (restart required) in integration options for the fastest experience). Under the hood, the new streams are a binary stream of data “straight to your browser”, with no unnecessary translations or overhead.
Configuring Direct stream parameters
Open the integration options, choose Configure device, and edit Direct stream FFmpeg parameters. This advanced YAML mapping overrides parameters for direct streams and snapshots on that device, including both HD and SD. Changes apply when a new stream starts. Reload the integration after saving to stop existing streams.
For example, to try the settings reported for the C560WS in PR #1279:
-probesize: 50000
-analyzeduration: 1000000
-vsync: null
These settings have not been verified across all cameras. To try only removing -vsync, enter just -vsync: null. Set the mapping to {} to restore the original behavior: probe size 32 bytes, analysis duration 0 microseconds, and -vsync 0 for direct MJPEG and snapshots (no -vsync for Home Assistant stream playback).
Supported keys are -loglevel, -probesize, -analyzeduration, -frames:v, -map-video, -vsync, -c:v, and -f, matching the video arguments supported by pytapo. Values must be non-empty strings or numbers; only -vsync accepts null, which omits that flag. Codec, format, frame count, and video mapping overrides also affect snapshots, so changing them can prevent playback or image capture. RTSP streams use the existing Extra arguments for ffmpeg option instead.
Why not use the Direct streams?
If you have an option to use RTSP, it is recommended to stick with RTSP streams.
- Direct streams take a bit more CPU resources since the device running this integration is now handling the binary stream directly, instead of camera exposing a standardized RTSP stream.
- Direct streams cannot be used with webrtc card, or go2rtc.
- RTSP streams are very fast with almost no delay using the webrtc Home Assistant camera card
Binary sensor for motion doesn't show up or work
Motion sensor is added only after a motion is detected for the first time.
It also requires ONVIF support on the device. If the device is not exposing Onvif interface (most likely if it is battery or solar powered), motion events will not work.
If the initial ONVIF connection fails, integration setup continues and ONVIF is retried during camera updates. Motion events and time synchronization require a successful ONVIF connection. Enable debug logging for custom_components.tapo_control to see the camera address, failed operation, initialization duration, and exception traceback. For event subscription failures handled internally by Home Assistant, also enable homeassistant.components.onvif debug logging:
logger:
logs:
custom_components.tapo_control: debug
homeassistant.components.onvif: debug
- Make sure the camera has motion detection turned on
- Make sure the camera has privacy mode turned off
- Make sure the camera can see you and your movement
- If you have webhooks enabled, and your Home Assistant internal URL is reachable on HTTP, make sure camera can reach it.
- Make sure you have correct IP set for Home Assistant. Turn on Advanced Mode under
/profile. Go to /config/network and under Network Adapter verify correct IP is shown for the device. If it is not correct, under Home Assistant URL uncheck Automatic next to Local Network and set it to http://<some IP address>:8123. DO NOT USE HTTPS.
- Certain camera firmwares have pullpoint broken, with only webhooks working. If you are not able to run webhooks because of above (https, or vlan setup), binary sensor will never show up.
- Try walking in front of the camera
- If above didn’t work, restart the camera and try again
Also make sure that:
- binary sensor is not disabled via entity, check .storage/core.entity_registry for disabled entities, look for “disabled_by”: “user” on platform “tapo_control”. If it is, remove the whole entity or change to “disabled_by”: null, and restart HASS.
- binary sensor is enabled in tapo integration options
- onvif port 2020 on camera is opened
- onvif on camera is not being used more than once concurrently, and is only used by this integration
Big delay in camera stream
This is a known issue of Home Assistant.
There is an ability to disable usage of Home Assistant Stream component for the camera, which might lower the delay very significantly at cost of higher CPU usage.
You can choose to disable stream component when adding the camera, or via Options when camera has already been added. This change requires a restart of Home Assistant.
There might be some disadvantages to doing this, like losing option to control playback and a higher CPU usage.
Results depend on your hardware and future Home Assistant updates.
If you disable stream and your hardware is not up to the task, you will get artifacts, bigger delay and freezes.
If you wish, try it out and see what works best for you.
Another possibility is using WebRTC Camera by AlexxIT.
Example working configuration:
type: custom:webrtc-camera
entity: camera.bedroom_hd
No audio in camera stream
Supported audio codecs in Home Assistant are “aac”, “ac3” and “mp3”.
Tapo Cameras use PCM ALAW (alaw) which is not supported.
More details here.
You can get sound working using WebRTC Camera by AlexxIT.
Example working configuration:
type: custom:webrtc-camera
entity: camera.bedroom_hd
I see error `Invalid authentication data. Make sure you have created your 3rd party account via Tapo app. You can also test if these credentials work via rtsp stream, for example VLC using link rtsp://username:password@IP Address:554/stream1` when I enter correct password
You might be entering incorrect password or are encountering a camera limitation.
- Check logs for any error messages
- Check that HA can reach the camera on ports 554 and 2020
Finally, most likely issue, see official Tapo documentation
Q3: Can multiple accounts/devices view the Tapo camera at the same time?
A: Currently, each camera can be controlled or managed by only one account on the Tapo App. You can share it with 5 different accounts at most, and these two accounts can only access live view and playback features of the camera.
Each camera also supports up to 2 simultaneous video streams. You could use up to 2 devices to view the live feed of the camera simultaneously using the Tapo App or via RTSP. You may also only view the playback of a camera using one Tapo app at a time.
As well as:
Q4: Why can’t I use Tapo Care, SD card, and NVR at the same time?
A: Due to the limited hardware performance of the camera itself, Tapo Care works best with one of the NVR or SD card recordings.
If you are using an SD card and Tapo Care at the same time, the NVR(RTSP/ONVIF) will be disabled.
To restart the recording on the NVR, please remove the SD card from the camera.
Supported models
Users reported full functionality with following Tapo Cameras, Doorbells and Chimes:
- TC55
- TC60
- TC70
- TC(A)72NL/EU
- TC82
- TC85
- C100
- C110
- C120
- C200
- C201
- C206
- C210
- C211
- C216
- C220
- C225
- C236
- C250
- C260
- C310
- C320WS
- C401
- C402
- C403
- C410
- C420
- C420S2
- C425
- C460
- C500
- C510W
- C520WS
- C530WS
- C610
- C710
- C720
- D100C
- D130
- D205
- D230
- D235
The integration should work with any other Tapo Camera based devices and chimes.
If you had success with some other model, please report it via a new issue.
Note: If the device is not exposing Onvif interface (most likely if it is battery or solar powered), motion events will not work.
What is webhook when referred to on camera?
Camera uses ONVIF standard to communicate motion events. This communication can work with 2 ways:
- Pullpoint: Client opens connection to the camera and waits until the camera responds. Camera responds only when there is some event to communicate. After camera responds, client reopens the connection and waits again.
- Webhook: Client tells the camera its URL to receive events at. When an event happens, camera communicates this to the URL client defined.
Webhooks are the preffered method of communication as they are faster and lighter. That being said;
- Webhooks require an HTTP only HA setup because Tapo cameras do not support HTTPS webhooks
- Webhooks require a proper base_url to be defined in HA, so that the URL communicated is correct (you can check URL sent by enabling debug logs for homeassistant.onvif)
Points above are automatically determined by this integration and if the HA does not meet the criteria, webhooks are disabled. That being said;
- There are camera (and/or firmwares) which freeze when both webhooks and pullpoint connection is created, which happens at the start to see if webhooks is supported at all so that communication can fallback back to pullpoint.
- There are camera firmwares which have pullpoint broken (1.3.6 C200) and only webhooks work
For webhooks to work, all the user needs to do is make sure he is using HA on HTTP and that the HA is available on the URL communicated.
Is this integration free and fully local?
Yes, the integration is free and does not require any paid subscriptions. It is also fully local requiring no internet access from the camera or this integration.
I receive Exception: Invalid authentication data when executing an automation / script
Firmwares of cameras expect messages in sequential order. Sending them in parallel can lead to 401 code from camera which shows us with this exception.
You will need to send the automation actions in sequence instead, possibly with delay as well if needed.
See https://github.com/JurajNyiri/HomeAssistant-Tapo-Control/issues/488 for more information.
Time synchronization synchronizes incorrect time
Due to unknown root cause some cameras behave differently than others when setting time through ONVIF standard and so far no root cause was found.
Setting time is not possible through the official application and this integration uses an undocumented and unsupported camera functionality through ONVIF standard.
If the time is set incorretly, eg. 1 hour ahead:
- Ensure correct timezone is set both for Home Assistant and device
- If still experiencing issue, navigate to
/config/integrations/integration/tapo_control
- Click on Configure under device you wish to synchronize time for
- Select
Configure time synchronization, Submit
- Adjust the time offset either for period of DST, or outside of DST
Please open a new issue, or discuss on Home Assistant: Community Forum.
Join discussion on Discord.
Thank you
Disclaimer
This integration is using python module Pytapo which is an unofficial module for achieving interoperability with Tapo cameras.
Author is in no way affiliated with Tp-Link or Tapo.
All the api requests used within the pytapo library are available and published on the internet (examples linked above) and the pytapo module is purely just a wrapper around those https requests.
Author does not guarantee functionality of this integration and is not responsible for any damage.
All product names, trademarks and registered trademarks in this repository, are property of their respective owners.
评论