♻️ Sync Rules
This document covers how synapse handles syncing state with Home Assistant, manages entity registries, and basic troubleshooting for when things go wrong.
State Syncing
The synapse library operates off of a push model. When making changes to entity configuration / locals:
- written to local sqlite database
- if change should be reflect in ha (state / config update), immediately emit via websocket event
- receive by python
synapse-extension, and reflect change in entity config
The sqlite database exists to track current state, it does not contain any historical information. It's primary purpose to to restore state during application reboots (expected or otherwise), and it's data should reflect what is currently in memory by your app
Note: removing entities from code will NOT clean up from database automatically
Registry Sync
The application registry syncs with Home Assistant in a variety of situations. It works by condensing state into a single json object then emitting a message via websocket to the extension along with some application metadata. Once inside the python -
- Any registered entities that don't exist in the payload are removed
- New entities are created to match missing entities
- State & configuration updates passed to all entities
Registry syncs happen every time your application boots, as well as every time you create a new entity (may happen at any time).
Entity IDs for new entities
Entity IDs are generated by Home Assistant based off the name for the entity by default.
You can influence this with the suggested_object_id property, which takes priority.
If there is an ID conflict Home Assistant will append _2.
This behavior cannot be overridden but will not affect value syncing.