Skip to content

Home Information - Your home, your data, organized.

Python

Issue #296: HA lock support — simulator entity + inbound state translation (#304)

Tony C8700516aebd8
diff --git a/src/hi/services/hass/enums.py b/src/hi/services/hass/enums.py
index f5b97f2c..b66a5387 100644
--- a/src/hi/services/hass/enums.py
+++ b/src/hi/services/hass/enums.py
@@ -54,3 +54,5 @@ class HassStateValue:
ON = 'on'
OFF = 'off'
+ LOCKED = 'locked'
+ UNLOCKED = 'unlocked'
diff --git a/src/hi/services/hass/hass_converter.py b/src/hi/services/hass/hass_converter.py
index 562a0829..c4514121 100644
--- a/src/hi/services/hass/hass_converter.py
+++ b/src/hi/services/hass/hass_converter.py
@@ -1628,6 +1628,8 @@ class HassConverter:
return cls._light_to_sensor_value_map( hass_state )
if domain == HassApi.BINARY_SENSOR_DOMAIN:
return cls._binary_sensor_to_sensor_value_map( hass_state )
+ if domain == HassApi.LOCK_DOMAIN:
+ return cls._lock_to_sensor_value_map( hass_state )
return cls._passthrough_to_sensor_value_map( hass_state )
@classmethod
@@ -1735,6 +1737,26 @@ class HassConverter:
logger.warning( f'Unknown HAss binary state value "{hass_state.state_value}".' )
return None
+ @classmethod
+ def _lock_to_sensor_value_map(
+ cls, hass_state : HassState ) -> Dict[ IntegrationKey, str ]:
+ """Translate HA lock domain's domain-specific state strings
+ to HI's canonical ON_OFF values. HA reports ``'locked'`` /
+ ``'unlocked'`` as the entity state; HI's ON_OFF EntityState
+ keys off ``EntityStateValue.ON`` / ``OFF`` for display and
+ widget coercion. Without this, HI's checkbox would always
+ render as ``Off`` regardless of the lock's real state."""
+ sv = hass_state.state_value.lower()
+ if sv == HassStateValue.LOCKED:
+ value = str( EntityStateValue.ON )
+ elif sv == HassStateValue.UNLOCKED:
+ value = str( EntityStateValue.OFF )
+ else:
+ value = hass_state.state_value
+ if not value:
+ return {}
+ return { cls.hass_state_to_integration_key( hass_state ) : value }
+
@classmethod
def _passthrough_to_sensor_value_map(
cls, hass_state : HassState ) -> Dict[ IntegrationKey, str ]:
diff --git a/src/hi/services/hass/tests/test_hass_converter_lock.py b/src/hi/services/hass/tests/test_hass_converter_lock.py
new file mode 100644
index 00000000..c96fc8f0
--- /dev/null
+++ b/src/hi/services/hass/tests/test_hass_converter_lock.py
@@ -0,0 +1,140 @@
+import logging
+
+from django.test import TestCase
+
+from hi.apps.control.models import Controller
+from hi.apps.entity.enums import EntityStateType, EntityStateValue, EntityType
+from hi.apps.entity.models import EntityState
+from hi.services.hass.hass_converter import HassConverter
+from hi.services.hass.hass_models import HassDevice, HassServiceCall, HassState
+
+logging.disable(logging.CRITICAL)
+
+
+def _make_lock_hass_state(api_dict, entity_id='lock.front_door'):
+ return HassState(
+ api_dict=api_dict,
+ entity_id=entity_id,
+ domain='lock',
+ entity_name_sans_prefix=entity_id.split('.', 1)[1],
+ entity_name_sans_suffix=entity_id.split('.', 1)[1],
+ )
+
+
+def _build_lock_device(device_id='front_door', state='locked'):
+ api_dict = {
+ 'entity_id': f'lock.{device_id}',
+ 'state': state,
+ 'attributes': {
+ 'friendly_name': device_id.replace('_', ' ').title(),
+ },
+ 'last_changed': '2026-01-01T00:00:00+00:00',
+ 'last_reported': '2026-01-01T00:00:00+00:00',
+ 'last_updated': '2026-01-01T00:00:00+00:00',
+ 'context': {'id': 'ctx', 'parent_id': None, 'user_id': None},
+ }
+ hass_state = HassConverter.create_hass_state(api_dict)
+ device = HassDevice(device_id=device_id)
+ device.add_state(hass_state)
+ return device
+
+
+class TestLockInboundStateTranslation(TestCase):
+ """``hass_state_to_sensor_value_map`` translates HA's
+ domain-specific lock state strings to HI's canonical ON_OFF
+ values; without this, HI's checkbox display always reads as
+ Off because ``SensorResponse.is_on`` checks for ``'on'``."""
+
+ def test_locked_maps_to_canonical_on(self):
+ hass_state = _make_lock_hass_state({
+ 'entity_id': 'lock.front_door',
+ 'state': 'locked',
+ 'attributes': {'friendly_name': 'Front Door'},
+ })
+ value_map = HassConverter.hass_state_to_sensor_value_map(hass_state)
+ self.assertEqual(len(value_map), 1)
+ self.assertEqual(list(value_map.values())[0], str(EntityStateValue.ON))
+
+ def test_unlocked_maps_to_canonical_off(self):
+ hass_state = _make_lock_hass_state({
+ 'entity_id': 'lock.front_door',
+ 'state': 'unlocked',
+ 'attributes': {'friendly_name': 'Front Door'},
+ })
+ value_map = HassConverter.hass_state_to_sensor_value_map(hass_state)
+ self.assertEqual(list(value_map.values())[0], str(EntityStateValue.OFF))
+
+ def test_unrecognized_state_value_passes_through(self):
+ # HA may emit transitional states like 'locking' or
+ # 'unlocking' on real locks; we don't translate those — the
+ # next poll will land on a final state.
+ hass_state = _make_lock_hass_state({
+ 'entity_id': 'lock.front_door',
+ 'state': 'locking',
+ 'attributes': {'friendly_name': 'Front Door'},
+ })
+ value_map = HassConverter.hass_state_to_sensor_value_map(hass_state)
+ self.assertEqual(list(value_map.values())[0], 'locking')
+
+
+class TestLockImport(TestCase):
+ """Verify a lock entity from HA is imported with the right
+ EntityType, EntityStateType, and a controllable on/off path."""
+
+ def test_lock_imports_as_door_lock_entity_with_on_off_state_and_controller(self):
+ device = _build_lock_device(device_id='front_door', state='locked')
+ entity = HassConverter.create_models_for_hass_device(
+ hass_device=device,
+ add_alarm_events=False,
+ )
+ self.assertEqual(entity.entity_type, EntityType.DOOR_LOCK)
+
+ entity_states = list(EntityState.objects.filter(entity=entity))
+ self.assertEqual(len(entity_states), 1)
+ self.assertEqual(entity_states[0].entity_state_type, EntityStateType.ON_OFF)
+
+ controllers = list(Controller.objects.filter(entity_state=entity_states[0]))
+ self.assertEqual(len(controllers), 1)
+ # Outbound payload routes 'on' to lock.lock, 'off' to
+ # lock.unlock — the existing CONTROL_SERVICE_MAPPING entry.
+ payload = controllers[0].integration_payload
+ self.assertEqual(payload.get('domain'), 'lock')
+ self.assertEqual(payload.get('on_service'), 'lock')
+ self.assertEqual(payload.get('off_service'), 'unlock')
+
+
+class TestLockOutboundDispatch(TestCase):
+ """Verify ``hi_value_to_hass_service_call`` routes the lock's
+ payload-driven 'on'/'off' to the right HA services. This is
+ the production path for a real imported lock; the existing
+ best-effort lock test in ``test_hass_controller.py`` covers
+ the no-payload fallback."""
+
+ def _payload(self):
+ return {
+ 'domain': 'lock',
+ 'is_controllable': True,
+ 'on_service': 'lock',
+ 'off_service': 'unlock',
+ 'parameters': {},
+ }
+
+ def test_on_routes_to_lock_service(self):
+ service_call = HassConverter.hi_value_to_hass_service_call(
+ hass_substate_id='lock.front_door',
+ hi_control_value='on',
+ domain_payload=self._payload(),
+ )
+ self.assertEqual(service_call, HassServiceCall(
+ domain='lock', service='lock', hass_entity_id='lock.front_door',
+ ))
+
+ def test_off_routes_to_unlock_service(self):
+ service_call = HassConverter.hi_value_to_hass_service_call(
+ hass_substate_id='lock.front_door',
+ hi_control_value='off',
+ domain_payload=self._payload(),
+ )
+ self.assertEqual(service_call, HassServiceCall(
+ domain='lock', service='unlock', hass_entity_id='lock.front_door',
+ ))
diff --git a/src/hi/simulator/management/commands/seed_sim_profiles.py b/src/hi/simulator/management/commands/seed_sim_profiles.py
index fba49b64..84a6e21f 100644
--- a/src/hi/simulator/management/commands/seed_sim_profiles.py
+++ b/src/hi/simulator/management/commands/seed_sim_profiles.py
@@ -81,6 +81,7 @@ from hi.simulator.services.hass.sim_models import (
HassInsteonMotionDetectorFields,
HassInsteonOpenCloseSensorFields,
HassInsteonOutletFields,
+ HassLockFields,
HassSmartBulbFields,
)
from hi.simulator.services.homebox.attachment_catalog import AttachmentTemplate
@@ -345,6 +346,7 @@ class Command(BaseCommand):
self._add_hass_outlet( profile, 'Zoo Outlet' , '01.BB.06' )
self._add_hass_smart_bulb( profile, 'Zoo Smart Bulb' )
self._add_hass_color_smart_bulb( profile, 'Zoo Color Bulb' )
+ self._add_hass_lock( profile, 'Zoo Lock' )
return profile.db_sim_entities.count()
def _build_volume(self, profile: SimProfile) -> int:
@@ -476,6 +478,15 @@ class Command(BaseCommand):
fields_kwargs = {'name': name},
)
+ def _add_hass_lock(self, profile, name):
+ self._create_db_entity(
+ profile = profile,
+ simulator_id = 'hass',
+ fields_class = HassLockFields,
+ sim_entity_type = SimEntityType.DOOR_LOCK,
+ fields_kwargs = {'name': name},
+ )
+
def _add_homebox_item(self, profile, name, **fields_kwargs):
kwargs = {'name': name}
kwargs.update(fields_kwargs)
diff --git a/src/hi/simulator/services/hass/service_dispatchers.py b/src/hi/simulator/services/hass/service_dispatchers.py
index 86048d47..a60f5097 100644
--- a/src/hi/simulator/services/hass/service_dispatchers.py
+++ b/src/hi/simulator/services/hass/service_dispatchers.py
@@ -28,7 +28,7 @@ from typing import Any, Dict, List, Optional, Tuple
from hi.simulator.enums import SimStateType
-from .sim_models import HassColorSmartBulbFields
+from .sim_models import HassColorSmartBulbFields, HassLockFields
class HassServiceDispatcher:
@@ -149,6 +149,24 @@ class HassServiceDispatcher:
updates.append( ( 'brightness', '255' ) )
return updates
+ @staticmethod
+ def _lock( sim_entity,
+ domain : str,
+ service : str,
+ payload : Dict[ str, Any ],
+ ) -> List[ Tuple[ str, str ] ]:
+ """Lock domain: ``lock.lock`` and ``lock.unlock`` toggle
+ the lock's primary ON_OFF SimState. The state's ``state``
+ property maps the value to HA's ``'locked'`` / ``'unlocked'``
+ strings on emit."""
+ if domain != 'lock':
+ return []
+ if service == 'lock':
+ return [ ( 'lock', 'on' ) ]
+ if service == 'unlock':
+ return [ ( 'lock', 'off' ) ]
+ return []
+
@staticmethod
def _extract_brightness_value_str( payload : Dict[ str, Any ] ) -> Optional[ str ]:
"""Read brightness from an HA service-call payload as a
@@ -175,4 +193,5 @@ class HassServiceDispatcher:
# objects exist as references. Keyed off SimEntityFields class.
HassServiceDispatcher._REGISTRY = {
HassColorSmartBulbFields: HassServiceDispatcher._color_smart_bulb,
+ HassLockFields: HassServiceDispatcher._lock,
}
diff --git a/src/hi/simulator/services/hass/sim_models.py b/src/hi/simulator/services/hass/sim_models.py
index 815d3482..4e80a8fd 100644
--- a/src/hi/simulator/services/hass/sim_models.py
+++ b/src/hi/simulator/services/hass/sim_models.py
@@ -694,6 +694,49 @@ class HassColorSmartBulbColorModeState( HassState ):
return {}
+@dataclass( frozen = True )
+class HassLockFields( SimEntityFields ):
+ """A lock device. Single ON_OFF SimState whose value drives
+ HA's domain-specific ``state`` strings (``'locked'`` /
+ ``'unlocked'``)."""
+ pass
+
+
+def _lock_entity_id( name : str ) -> str:
+ suffix = name.lower().replace( ' ', '_' )
+ return f'lock.{suffix}'
+
+
+@dataclass
+class HassLockState( HassState ):
+ """A lock's state. Internally ON_OFF (locked == on); the
+ ``state`` property maps to HA's domain-specific
+ ``'locked'`` / ``'unlocked'`` strings."""
+
+ sim_entity_fields : HassLockFields
+ sim_state_type : SimStateType = SimStateType.ON_OFF
+ sim_state_id : str = 'lock'
+ value : str = 'on'
+
+ @property
+ def name(self):
+ return f'{self.entity_name} Lock'
+
+ @property
+ def entity_id(self):
+ return _lock_entity_id( self.entity_name )
+
+ @property
+ def state(self):
+ return 'locked' if str_to_bool( self.value ) else 'unlocked'
+
+ @property
+ def attributes(self) -> Dict[ str, str ]:
+ return {
+ 'friendly_name': self.entity_name,
+ }
+
+
HASS_SIM_ENTITY_DEFINITION_LIST = [
SimEntityDefinition(
class_label = 'Insteon Switch',
@@ -775,4 +818,12 @@ HASS_SIM_ENTITY_DEFINITION_LIST = [
HassColorSmartBulbColorModeState,
],
),
+ SimEntityDefinition(
+ class_label = 'Lock',
+ sim_entity_type = SimEntityType.DOOR_LOCK,
+ sim_entity_fields_class = HassLockFields,
+ sim_state_class_list = [
+ HassLockState,
+ ],
+ ),
]