Replay historical Home Assistant activity while you are away, then manage the existing dashboard remotely
The presence_simulation custom integration uses Home Assistant history to reproduce earlier states for selected lights, switches, covers, media players, and other compatible entities. This guide explains the prerequisites, manual installation workflow, UI configuration, local verification, routine operation, and common troubleshooting steps. Once the integration works locally, we show how to connect the existing Home Assistant web interface through a Localtonet HTTP tunnel. Presence Simulation does not run its own web server, so remote access always targets Home Assistant itself rather than the custom component.
📋 What's in this guide
How Presence Simulation works
Presence Simulation is a Home Assistant custom integration intended to make an unoccupied home appear active. Instead of generating a fixed lighting schedule, it reads historical entity states from the Home Assistant database. It then applies the states recorded a configured number of days earlier to the entities included in a simulation.
The number of days used to look back is called the delta. For example, a delta of five tells the integration to use activity from five days ago. The Home Assistant recorder database must retain more history than the chosen delta. If the required period is no longer present in the database, the integration cannot replay that historical activity correctly.
If a simulation continues for longer than its delta period, the integration resets the simulation cycle and starts it again. It continues doing this until the simulation is stopped. This behavior allows a simulation to remain active for an extended absence without requiring a separate schedule for every future day.
Presence Simulation can reproduce light brightness and color-related behavior only when the necessary attributes exist in the recorder database. Without stored attributes, it can still reproduce basic light on and off activity. The project documentation identifies Light Reilluminator as an optional companion component for storing light attributes, but it is not required for basic presence simulation.
The integration runs inside Home Assistant and is managed through Home Assistant entities, services, and integration settings. It does not provide a separate hostname, listening port, or web interface. When remote management is needed, the network target is the existing Home Assistant web interface.
Prerequisites and planning
Begin with a working Home Assistant installation and administrative access to its integration settings. A manual installation also requires access to the Home Assistant configuration directory. How that directory is reached depends on the Home Assistant installation method, so this guide does not assume a particular shell, add-on, container mount, operating system, or file-sharing arrangement.
The project gives ~/.homeassistant as one possible configuration-directory example. It is not a universal path. Before copying or cloning anything, identify the actual configuration directory used by your deployment. It is the directory under which the integration's final path must become:
custom_components/presence_simulation
The contents of the project's custom_components/presence_simulation directory belong at that destination. Avoid introducing an extra directory level such as custom_components/presence_simulation/presence_simulation. Home Assistant will not discover the integration if its files are nested at the wrong level.
Confirm that history is available
The Home Assistant history integration must be active. The project notes that it is active by default, but a customized deployment may differ. In addition, the recorder must retain a period longer than the simulation delta. The documented default retention period is 10 days, and Home Assistant recorder configuration can change that period.
Treat retention and delta as a matched pair. If the recorder has 10 days of usable history, a delta requiring data beyond that period is unsuitable. Database purges, entity exclusions, recorder filters, or missing historical attributes can also affect what the integration is able to replay.
Choose safe test entities
For the first test, select a small set of visible, low-risk entities. A lamp is easier to observe and recover than a large group containing unrelated equipment. The integration supports documented domains such as light, cover, media_player, and input_select. It can also work with on/off entities that Home Assistant can control through homeassistant.turn_on and homeassistant.turn_off, including switches, groups, and automations.
Historical playback can turn selected entities on or off without a person being present. Exclude locks, alarms, heating equipment, cooking appliances, garage mechanisms, medical devices, and any entity whose unexpected state change could create danger or property damage. Review groups carefully because the integration acts on each entity in a selected group independently.
Back up before changing custom components
Create a usable backup of the Home Assistant configuration before adding or replacing custom-component files. A backup is especially important when updating an existing manual installation because files removed or renamed upstream can otherwise remain in the destination directory. Do not place passwords, tokens, or Home Assistant credentials in the component directory.
| Requirement | Why it matters | What to verify |
|---|---|---|
| Working Home Assistant | The component runs inside Home Assistant | The existing dashboard and integrations screen work locally |
| Configuration-directory access | Manual installation requires copying component files | You know the actual configuration directory for this deployment |
| History integration | The simulation reads historical entity states | History is active and contains data for the test entities |
| Sufficient recorder retention | The database must cover the selected delta | Retention is longer than the number of days used by the simulation |
| Safe test entities | The integration will cause real state changes | The initial selection is small, visible, and non-critical |
Manually install Presence Simulation
The project recommends HACS because HACS can help manage and track updates. However, manual installation is appropriate when HACS is unavailable, when you want direct control over installed files, or when you are diagnosing a repository-discovery problem.
There are two documented manual approaches. You can copy the component code into the correct directory yourself, or clone the repository from inside the Home Assistant configuration directory. Both approaches still require a Home Assistant restart before configuration.
Method 1: Copy the component files manually
Locate the Home Assistant configuration directory
Identify the configuration directory used by your actual deployment. The project mentions ~/.homeassistant only as an example, so do not assume that path applies to containers, appliances, managed installations, or other environments.
Create the integration directory
Under the configuration directory, create custom_components/presence_simulation. Preserve the underscore in presence_simulation. The similarly named presence-simulation path from unrelated repositories is not the documented directory for this project.
Copy the project component code
Copy the contents of the official repository's custom_components/presence_simulation directory into the destination you created. Keep the complete directory contents and their names intact. Copying only __init__.py is not a complete installation.
Check the final directory layout
Confirm that the component files are directly inside custom_components/presence_simulation. Correct any accidental extra nesting and make sure the Home Assistant process can read the files.
Restart Home Assistant
Restart Home Assistant using the normal supported procedure for your installation. A browser refresh alone is not sufficient because Home Assistant must load the new Python integration code during startup.
Method 2: Clone the repository into the configuration directory
The project also documents a Git-based installation. From the Home Assistant configuration directory, run:
git clone https://github.com/slashback100/presence_simulation.git .
The final dot tells Git to clone into the current directory. The repository contains its own custom_components/presence_simulation tree, so running the command from the correct configuration directory creates that component path.
The command targets the current directory rather than creating a separate repository folder. Run it only after confirming that you are in the intended Home Assistant configuration directory and that the operation will not conflict with existing repository metadata or files. If the directory is not suitable for a clone, use the manual copy method instead.
Restart Home Assistant after the clone completes. If you later update a Git-based installation, review upstream changes and preserve a backup rather than assuming that every pull or file replacement will be conflict-free.
Alternative: Install through HACS
Although this article focuses on manual installation, the recommended upstream path is HACS. With HACS already installed, search for Presence Simulation, select the found integration, choose Install, and restart Home Assistant. The project also notes that it can be added as a custom repository if the normal discovery procedure does not work.
HACS does not eliminate the restart or Home Assistant configuration steps. It primarily changes how the custom-component files and updates are managed.
Add and configure the integration in Home Assistant
After Home Assistant restarts, open its integrations interface. The exact navigation labels can vary between Home Assistant releases. In the documented workflow, open the integrations area, use the add button, search for Presence Simulation, select it, and confirm the addition.
You will then configure the first simulation. The integration creates a switch entity whose name is based on the name chosen during setup. The project uses switch.presence_simulation as an example, but the actual entity ID in your system can differ.
Open the Home Assistant integrations interface
Sign in to the local Home Assistant UI with an account permitted to add integrations, then open the integrations management screen.
Add Presence Simulation
Use the add control, search for Presence Simulation, select the matching custom integration, and confirm. If it is missing, stop here and troubleshoot installation discovery before configuring anything else.
Select the simulation entities
Choose one or more entities or groups. Supported examples include lights, switches, covers, light groups, media players, and compatible entities that can be turned on and off through Home Assistant services. Start with a limited, safe selection.
Set the history delta
Enter the number of days of history to replay. The recorder retention period must be greater than this value, and the selected entities must have relevant history during that period.
Choose the poll interval
Set how often the integration checks whether it has been requested to stop. The documented default is 30 seconds. A smaller interval can make stop requests take effect sooner, but it increases processing work.
Choose restoration and randomization behavior
Decide whether states should be restored to their pre-simulation values after the simulation. Set randomization to 0 to disable it, or use a positive number of seconds as the maximum timing offset added to or subtracted from historical changes.
Set unavailable-state and brightness options
Choose whether an unavailable historical state should be treated as off. For lights, a default brightness can be set from 1 to 100. A value of 0 means the simulation does not set brightness and the light keeps its last brightness value.
Save and identify the created switch
Complete the configuration, locate the resulting switch entity, and record its actual entity ID. The switch is on while its simulation is running and off otherwise. Integration options can be edited later from the integration screen.
Understanding the main options
| Option | Purpose | Planning consideration |
|---|---|---|
| Entities | Defines what the simulation may control | Groups are processed as individual member entities, so inspect membership carefully |
| Delta | Selects how many days back the simulation reads | Recorder retention must be longer than the delta |
| Poll interval | Controls how quickly stop requests are noticed | The default is 30 seconds; smaller values require more processing |
| Restore states | Restores states captured before simulation began | Test restoration with a small entity set before relying on it |
| Random offset | Varies historical event timing | 0 disables it; a positive value sets the maximum seconds added or subtracted |
| Unavailable as off | Maps unavailable historical records to an off state | Useful only where unavailable should genuinely be interpreted that way |
| Default brightness | Sets a light brightness during simulation | Use 1 to 100, or 0 to leave brightness unchanged |
Multiple simulation switches can be created and assigned different configurations. For example, separate switches could represent different safe entity sets or historical deltas. Keep names descriptive because service calls involving several switches need to identify the intended switch.
Verify the installation locally
Complete local verification before considering remote access. This separates integration problems from network problems and reduces the chance of exposing an interface that is not working correctly.
Confirm that Home Assistant restarted cleanly
Make sure the local dashboard loads and that normal integrations remain operational. If startup fails or new errors appear, review the custom-component directory and Home Assistant logs before continuing.
Confirm integration discovery
Verify that Presence Simulation can be found in the integrations interface and that its configuration entry appears after setup.
Inspect the created switch
Locate the switch entity created from your selected simulation name. Confirm that it is initially off unless you intentionally started the simulation.
Run a controlled simulation
Start the switch while observing the selected low-risk entities. Allow enough time for relevant historical events to be reached. A simulation cannot demonstrate a state change when no matching event exists in the selected historical period.
Stop and verify recovery
Turn the simulation off and allow for the configured poll interval. Confirm that the switch returns to off and verify state restoration if that option was enabled.
Check basic on and off behavior before evaluating brightness or color. If basic switching works but brightness does not, inspect whether those attributes were actually retained in the recorder database. The project explicitly states that without stored light attributes, the integration will only simulate turning lights on and off.
Presence Simulation follows historical timing. If the selected entities had no changes at the corresponding historical time, there may be nothing to replay during a short observation window. Check entity history and use a period with known, safe activity before diagnosing the installation as broken.
Start, stop, and manage simulations
The simplest control method is the switch entity created by the integration. Turning that switch on starts its simulation, and turning it off stops it. The switch state reflects whether the simulation is running.
The integration also registers three Home Assistant services:
presence_simulation.startstarts a simulation.presence_simulation.stopstops a simulation.presence_simulation.toggleswitches a simulation between running and stopped.
From version 4 onward, switch_id is mandatory when several Presence Simulation switches exist. It identifies the simulation switch the service should control. Always use the real entity ID created in your Home Assistant instance rather than copying an example unchanged.
A start call can optionally override configured values with a list of entities, a delta, state-restoration behavior, a random timing offset, unavailable-state handling, and brightness. The following project example illustrates the documented fields:
switch_id: switch.presence_simulation
entity_id:
- group.outside_lights
- light.living_room
- light.hall
delta: 5
restore_states: true
random: 300
unavailable_as_off: true
brightness: 75Treat the entity IDs in this example as placeholders. They are not expected to exist in your Home Assistant installation. Validate your own IDs and test service behavior locally before placing it in an automation.
A restart does not necessarily mean a running simulation is forgotten. The component code includes behavior intended to launch a simulation after Home Assistant starts when its switch indicates that it was running. Consider that behavior when performing maintenance or restarting Home Assistant during an absence.
Access the Home Assistant interface with Localtonet
Once Presence Simulation is installed, configured, and verified locally, you can make the existing Home Assistant web interface reachable through Localtonet. Our client establishes an outbound connection to a Localtonet relay, so this workflow does not require inbound router port forwarding, firewall changes, VPN setup, or a public IP address.
The correct local target is the Home Assistant interface already used on your network. It is not presence_simulation and it is not a new component-specific port. The project documentation does not define the Home Assistant URL, port, or local transport because those values belong to the parent Home Assistant deployment.
Before creating a tunnel, determine the local IP address or hostname and port that the Localtonet client device can use to reach Home Assistant. Also determine whether that endpoint uses HTTP or HTTPS. Do not assume a default port or downgrade a deployment that already expects HTTPS.
Home Assistant deployments vary across appliances, containers, reverse proxies, and customized network configurations. Use the exact local address, port, and protocol that already work from the device where the Localtonet client will run. If the local endpoint cannot be reached from that device, the tunnel cannot make it work.
Install and run the Localtonet client
Install our client on the Home Assistant host or another device that can reach the Home Assistant web endpoint. Use the current installation method provided for the selected operating system. This article does not hardcode a client command because installation details can vary by operating system and client version.
Authenticate or select the client device
Use the device-specific authentication token associated with the client that will run the tunnel. Keep the token private and never place it in screenshots, automation examples, logs, or public configuration.
Select an available relay server
Choose a server or region currently available in the Localtonet dashboard. Available server codes and regions can change and can vary by account or plan, so use the current displayed values rather than copying a hardcoded value from a tutorial.
Create the appropriate web tunnel
Create an HTTP/s tunnel that points to the Home Assistant local IP address and port reachable from the Localtonet client. Match the local protocol used by that endpoint. HTTP tunnels may use a generated subdomain, a selected subdomain where supported, or a custom domain, but exact custom-domain DNS requirements should be checked against current dashboard documentation.
Start the tunnel
Creating a tunnel does not make it active. Use the Start button and confirm that the selected client is connected and the tunnel is running. The assigned public HTTPS address is usable only while the client remains connected and the tunnel remains active.
Test the public address safely
Open the assigned public address from a separate network and confirm that the expected Home Assistant sign-in interface appears. Authenticate normally, verify the Presence Simulation switch, and test only low-risk controls. Stop or delete the tunnel when it is no longer required.
With Localtonet, the public URL reaches the Home Assistant interface through the outbound client connection. It does not expose a separate Presence Simulation API, nor does it change how the integration reads the recorder database. If Presence Simulation is missing or broken locally, creating a tunnel will not repair it.
Secure remote Home Assistant management
A remotely reachable Home Assistant interface can control physical devices and reveal household state. Treat it as a sensitive administrative endpoint. Remote availability should complement Home Assistant authentication and authorization, not replace them.
Verify that the public address shows only the intended Home Assistant application. If it displays a different service, directory listing, proxy error, or unexpected administrative interface, stop the tunnel and correct the local target before trying again.
Do not expose a troubleshooting shell, file share, database, or Home Assistant configuration directory as a substitute for the web interface. The tunnel target should be the already functioning web endpoint needed for the documented task.
Troubleshooting installation, simulation, and remote access
Presence Simulation does not appear in integrations
First confirm that Home Assistant was fully restarted after installation. Then inspect the final path. The component directory must be named presence_simulation and must sit directly under custom_components. An extra repository folder or a hyphenated directory name can prevent discovery.
Verify that the complete component directory was copied, not a single source file. Check that Home Assistant can read the files and review its logs for import, manifest, dependency, or configuration-flow errors. Release v5.3 specifically fixed a configuration-flow validator error affecting new initial setup, so compare an older installation with the current official release before spending time diagnosing an issue already corrected upstream.
The integration appears, but configuration fails
Confirm that the installed files all come from the same project version. Mixing files from different releases can create inconsistent behavior. Remove stale files only after making a backup, then install a complete release and restart Home Assistant.
Also verify that you selected the intended project. A different repository with a similar Presence Simulator name uses different paths and configuration behavior. This guide applies to the slashback100/presence_simulation project and its custom_components/presence_simulation directory.
The switch turns on, but no entities change
Inspect the historical data for the selected entities at the time represented by the delta. There must be relevant state changes to replay. Confirm that the history integration is active, that recorder retention exceeds the delta, and that recorder filtering has not excluded those entities.
Reduce the first test to one or two entities with known historical activity. Check whether the entity supports the expected Home Assistant turn-on and turn-off services. If a group is selected, inspect its individual members because the integration processes them independently.
Lights switch on and off, but brightness or color is missing
This usually indicates that basic states are available but the required light attributes were not stored in the recorder database. Presence Simulation cannot replay data that was not recorded. The project documents Light Reilluminator as an optional companion for retaining brightness and color-temperature values. Basic on and off simulation does not require it.
A stop request seems delayed
The poll interval determines how quickly the integration notices that it has been asked to stop. Its documented default is 30 seconds. Wait for that interval before assuming the stop request failed. Lowering the interval may improve responsiveness, but the project warns that smaller values increase processing work.
States do not return to their earlier values
Check whether state restoration was enabled for that simulation. Test restoration with a small entity set and no competing automations. Other Home Assistant automations, device behavior, manual input, or unavailable entities may change states during the same period, making the final result different from a simple isolated test.
The Localtonet public address does not load
Confirm that the Home Assistant UI still works locally from the Localtonet client device. Then confirm that the selected Localtonet device is connected, the tunnel has been started, and the configured local IP address, port, and protocol match the working endpoint. Remember that a created tunnel remains unavailable until it is started.
If the Home Assistant endpoint uses HTTPS locally, do not configure it as though it were plain HTTP. If a reverse proxy or another device provides the interface, the Localtonet client must be able to reach that exact target over the local network.
The public address opens the wrong application
Stop the tunnel immediately. The configured local port probably belongs to another service, or the local address points to the wrong device. Reconfirm the endpoint from the Localtonet client device before restarting the tunnel.
Home Assistant loads, but Presence Simulation is unavailable remotely
Determine whether the integration is available through the same Home Assistant account and interface locally. Localtonet carries access to the parent web interface; it does not alter Home Assistant permissions, entity visibility, dashboards, or integration state. If the feature is missing for that account locally, solve the Home Assistant configuration or authorization issue first.
Frequently asked questions
Does Presence Simulation have its own port or web server?
No separate network endpoint is documented. Presence Simulation runs as a Home Assistant custom integration and is controlled through Home Assistant switches, services, and integration options. A Localtonet tunnel should therefore target the existing Home Assistant web interface.
Is HACS required to install presence_simulation?
No. HACS is the recommended installation option because it helps manage and track updates, but the project also documents manual file copying and Git cloning. Every method requires a Home Assistant restart before the integration is configured.
Where should the custom component files be placed?
Place the complete component code under custom_components/presence_simulation inside the actual Home Assistant configuration directory. The project mentions ~/.homeassistant as an example configuration directory, but the correct location varies by deployment.
How much Home Assistant history does the simulation need?
Recorder retention must be longer than the chosen delta. The project documents a default retention period of 10 days, although Home Assistant recorder settings can change it. The relevant entities must also have usable history during the requested period.
Can Presence Simulation control more than lights?
Yes. Documented domains include lights, covers, media players, and input selects. It can also use compatible on/off entities controlled through homeassistant.turn_on and homeassistant.turn_off, including switches, groups, and automations.
Why are my lights changing state without reproducing brightness?
Brightness and color-related playback require those attributes to have been stored in the recorder database. Without them, the integration can still replay light on and off states. The project identifies Light Reilluminator as an optional component for storing relevant light attributes.
Can I create more than one presence simulation?
Yes. Version 4 and later support multiple independently controlled simulation switches with separate entities and options. When several switches exist, service calls require the appropriate switch_id.
Do I need router port forwarding to reach Home Assistant with Localtonet?
No. Our client establishes an outbound connection to a Localtonet relay, so the workflow does not require inbound router port forwarding, firewall changes, VPN setup, or a public IP address. The tunnel remains available only while the selected client is connected and the tunnel is running.
Which Home Assistant port should I enter in Localtonet?
Use the port from the Home Assistant web endpoint that already works from the Localtonet client device. This guide does not prescribe a default because the Presence Simulation project does not define Home Assistant's port, and deployments can use different ports, protocols, or reverse proxies.
Connect your verified Home Assistant interface with Localtonet
After Presence Simulation works locally, install our client on a device that can reach Home Assistant, create the appropriate HTTP/s tunnel, and start it when remote management is needed. Keep Home Assistant authentication enabled and stop the tunnel when access is no longer required.
Get Started Free →
