Integrar ‘AirTag’ en Home Assistant

En esta entrada vamos a integrar ‘AirTag’ en Home Assistant, para poder rastrear tus objetos desde tu panel de control.

Requisitos previos

Antes de empezar repasemos lo que vas a necesitar:

  • Esta “integración” va a servir tanto para los AirTag oficiales como para otros dispositivos compatibles con la red ‘Find my’ de Apple que permiten rastrean otros objetos. De hecho yo voy a utilizar estos clones baratos.
itag
*Algún precio puede haber cambiado desde la última revisión
  • Necesitas un dispositivo de Apple (iPhone / iPad) para configurar y vincular los rastreadores (al menos, en un primer momento). Además este dispositivo debe estar operativo ya que va a ser el que envíe la información de la localización a Home Assistant. Dicho esto, intentaremos que el proceso sea transparente para el usuario y la información podrá ser consultada desde cualquier dispositivo, tanto Android como iOS.
  • Tanto el dispositivo de Apple como los dispositivos de consulta deben tener instalada la aplicación de Home Assistant.

Extraer la localización del dispositivo Apple

Como ya te explique en esta entrada, para obtener la localización de los AirTag o dispositivos compatibles necesitas ejecutar la aplicación “Buscar” desde un dispositivo de Apple. Esto es exactamente lo que vamos a hacer, en dos sencillos pasos, creando un atajo con el objetivo de enviar la información a Home Assistant y poder manejarla desde ahí.

Primero, en Home Assistant, ve a Ajustes > Dispositivos y servicios > Ayudantes > Crear ayudante > Texto. Dale el nombre “AirTag”, asigna como valor máximo ‘255’ y pulsa en “Crear”. Esto creará la entidad ‘input_text.airtag’.

Luego desde tu dispositivo Apple pulsa en este enlace para importar el atajo que va a enviar la información a HA. Una vez importado, busca el apartado “Call” con el icono de Home Assistant y pulsa sobre el icono de la flecha para desplegar el detalle. En el apartado “Server” debes seleccionar tu instancia de Home Assistant.

⚠️Ten en cuenta que el atajo selecciona el texto posterior a la palabra "Objetos". Si tu aplicación está en un idioma diferente debes reemplazarla por la palabra correcta (por ejemplo, "Objects" o "Oggetti").

⚠️Puesto que los iPad tienen una pantalla más grande, es posible que capte demasiada información y por este motivo la localización de los items no llegue a HA. Para solucionarlo debes incluir en el atajo una acción para filtrar la información (por ejemplo, cortar la captura de pantalla antes de extraer el texto). 

Cada vez que ejecutes el atajo comprobarás que lo que hace es abrir la aplicación “Buscar”, realizar una serie de comandos para extraer y aislar la información de los objetos, y por último mandarla a HA como valor del ayudante que acabamos de crear.

Creación de sensores en Home Assistant

Aunque ya tenemos disponible la información “bruta” para poder afirmar que hemos podido integrar ‘AirTag’ en Home Assistant lo suyo es que dispongamos de un sensor para cada uno de nuestros objetos, indicando si están en casa o en su defecto su localización. Además vamos a conseguir sus coordenadas para transformarlo en un ‘device tracker’ y poder mostrarlo en un mapa.

Para ello sólo tienes que seguir estos pasos:

  1. Entra en la web de Geoapify y pulsa en “Get started”. A continuación baja hasta el final de la página, pulsa en “Get api key” y regístrate o accede con tu cuenta de Google.
  2. Pulsa en el botón de “Create a project” e introduce el nombre que quieras (por ejemplo, “Aguacatec”). Copia y conserva el código que figura en el campo “Key”.
  3. Copia el siguiente código en tu fichero ‘sensors.yaml’ y haz los siguientes ajustes:
    • Sustituye la palabra “ITEM” por el nombre del objeto que quieres rastrear (por ejemplo, “mochila”).
    • Ajusta el valor del campo ‘scan_interval’ al tiempo en segundos para actualizar las coordenadas del sensor (lo lógico es que la frecuencia sea igual o mayor al periodo en el que ejecutas el atajo del Apple).
    • Sustituye la palabra “ITEM_FINDMY_NAME” por el nombre exacto asignado en la aplicación “Buscar” del dispositivo Apple vinculado (por ejemplo, “Mochila Tito”).
    • Sustituye la palabra “HOME” por la palabra exacta asignada en la aplicación “Buscar” del dispositivo Apple vinculado, cuando el objeto está en casa (por ejemplo, “Casa” o “Home”).
    • Sustituye la palabra “FULLADRESS” por tu dirección completa (por ejemplo, “Calle Alcalá 77, Madrid”). Esta es la dirección considerada para mostrar las coordenadas cuando la aplicación “Buscar” del dispositivo Apple vinculado reporta que el objeto está en casa.
    • Sustituye la palabra “YOURAPYKEY” por el código generado en el paso anterior.
- platform: rest
  name: airtag_ITEM
  value_template: "{{ value_json.results[0].formatted }}"
  json_attributes_path: "$.results[0]"
  json_attributes:
    - lon
    - lat
    - district
    - city
    - postcode
    - street
    - housenumber
    - state
    - country
    - country_code
  verify_ssl: true
  scan_interval: 900 # every 15 min
  resource_template: >
    {% set address = states('input_text.airtag').split('ITEM_FINDMY_NAME')[1].split('•')[0] %}
    {% if address == "HOME" %}
      {% set home = "FULLADRESS" %}
      {{
        "https://api.geoapify.com/v1/geocode/search?text="
        + home | urlencode
        + "&apiKey=YOURAPYKEY&format=json"
      }}
    {% else %}
      {{
        "https://api.geoapify.com/v1/geocode/search?text="
        + address | urlencode
        + "&apiKey=YOURAPYKEY&format=json"
      }}
    {% endif %}
  1. Reinicia Home Assistant por completo (no es suficiente con recargar).
  2. Ahora comprobarás que ya tienes como entidad disponible ‘sensor.airtag_ITEM’ cuyo estado es la dirección completa del airtag, además de tener otros atributos relativos a su localización. Toda esta información está disponible para que la utilices en tus tarjetas o tus automatizaciones.
  3. Ahora vamos a crear la entidad ‘device tracker’ del AirTag. Esto te va a permitir situarla en tus tarjetas de tipo mapa, y generar automatizaciones cuando entre o salga de una zona geográfica. Para ello pulsa en primer lugar en el siguiente botón para importar el blueprint que he preparado.
Open your Home Assistant instance and show the blueprint import dialog with a specific blueprint pre-filled.
  1. Verás que la configuración es muy sencilla. Sólo tienes que seleccionar el sensor que se ha creado en el paso 6, e indicar una (o varias) palabra clave que va a identificar que tu AirTag está en casa (por ejemplo, el nombre de tu calle). Procura indicar esta palabra tal y como aparece en la aplicación “Buscar” de Apple. El blueprint va a actualizar las coordenadas del ‘device tracker’ cada vez que se actualice el sensor del AirTag.
  2. Ahora tienes que abrir tu fichero ‘known_devices.yaml’ y pegar el siguiente código. Asegúrate de que le das exactamente el mismo nombre a tu ITEM que en el sensor creado, y después reinicia Home Assistant.
airtag_ITEM:
  name: airtag_ITEM
  mac:
  icon: mdi:bag-personal ## Reemplaza este icono por el que represente a tu objeto
  picture: local/images/mochila.png ## Reemplaza esta ruta por la de la imagen que represente a tu objeto
  track: true
  1. Ahora también tendrás disponible la entidad ‘device_tracker.airtag_ITEM’, que puedes utilizar en tus mapas y en tus automatizaciones. Por ejemplo, para recibir una notificación cuando un AirTag sale de la zona “Casa”. De esta forma ya puedes incluir en tu panel de control una tarjeta como esta, que muestra todos tus objetos en un mapa
Airtag
type: map
entities:
  - entity: device_tracker.airtag_mochila
aspect_ratio: 50%
card_mod:
  style:
    ha-map $ ha-entity-marker $: |
      .marker {
        border: 0px!important;
        background: transparent!important;
        }

Gestión de ubicaciones incorrectas

Algunos usuarios han reportado que cuando sus AirTag se encuentran en una localización concreta, reciben unas coordenadas de un lugar diferente. Esto puede suceder si, por ejemplo, existe una calle en otra ciudad (o país) que se llama igual que aquella donde vives o contiene un término similar (algo típico en sitios con nombres comunes como “Calle Gran Vía” o “Plaza Mayor”).

La manera más sencilla de solucionar estos errores recurrentes es reemplazar esta ubicación incorrecta por la dirección que queremos mostrar. Para ello sólo hay que modificar el sensor ‘rest’ que hemos creado en el fichero ‘sensors.yaml’ de la siguiente manera.

- platform: rest
  name: airtag_ITEM
  value_template: "{{ value_json.results[0].formatted }}"
  json_attributes_path: "$.results[0]"
  json_attributes:
    - lon
    - lat
    - district
    - city
    - postcode
    - street
    - housenumber
    - state
    - country
    - country_code
  verify_ssl: true
  scan_interval: 900 # every 15 min
  resource_template: >
    {% set address = states('input_text.airtag').split('ITEM_FINDMY_NAME')[1].split('•')[0] %}
    {% set aright = "FULL_RIGHT_ADDRESS" %}
    {% if address == "HOME" %}
      {% set home = "FULLADRESS" %}
      {{
        "https://api.geoapify.com/v1/geocode/search?text="
        + home | urlencode
        + "&apiKey=YOURAPYKEY&format=json"
      }}
    {% elif "WRONG_ADDRESS" in address %}
      {{
        "https://api.geoapify.com/v1/geocode/search?text="
        + aright | urlencode
        + "&apiKey=YOURAPYKEY&format=json"
      }}
    {% else %}
      {{
        "https://api.geoapify.com/v1/geocode/search?text="
        + address | urlencode
        + "&apiKey=YOURAPYKEY&format=json"
      }}
    {% endif %}

Si analizas el código comprobarás que es exactamente igual al inicial, con dos diferencias.

  • Debes sustituir el término “FULL_RIGHT_ADDRESS” por la dirección correcta que quieres mostrar (por ejemplo, “Calle Gran Vía 77, Madrid, España”). Esto servirá para forzar estas coordenadas y evitar la ubicación errónea.
  • Debes sustituir el término “WRONG_ADDRESS” por la dirección que genera la ubicación errónea (por ejemplo, “Calle Gran Vía 77”). Esto servirá para identificar los casos en los que se produce el error, y sustituir la dirección por la ubicación correcta.

Actualización de la información

Normalmente la utilidad de estos dispositivos es poder consultar su localización cuando lo necesitamos, por lo que no necesitamos actualizar su estado continuamente. Con esta idea vamos a definir distintas formas de actualizar la información en Home Assistant.

Solicitud manual desde cualquier dispositivo

Cualquier usuario con acceso a Home Assistant puede solicitar la actualización de la localización al dispositivo de Apple, a través del envío de una notificación del siguiente tipo, que puedes personalizar e incluir en un script, una automatización o en tu panel de control.

service: notify.mobile_app_DISPOSITIVO_APPLE
data:
  message: ¿Dónde están los AirTag?
  data:
    shortcut:
      name: AirTag to HA

Actualización automática

Si lo deseas, desde la aplicación Atajos del dispositivo de Apple también puedes establecer automatizaciones para que el atajo se ejecute por ejemplo cada día a cierta hora.

Además, dependiendo de la versión iOS del dispositivo, para ciertos desencadenantes puedes definir que se ejecute sin necesidad de confirmación por parte del usuario. De esta forma puedes actualizar la información sin molestarle.

Desde iOS 14 puedes ejecutar automatizaciones sin necesidad de confirmación en función de la hora del día, una alarma, estado de reposo, conexión con carPlay, modo entrenamiento del Apple Watch, contacto con NFC, abrir una app, activación del modo de vuelo, no molestar o ahorrar batería, el nivel de batería o la conexión con el cargador. Puedes consultar que otro tipo de automatizaciones (como al recibir un correo o escuchar un sonido) se han incorporado en versiones superiores en este enlace.

Ejemplos de uso

Tanto si eres usuario de Apple como de Android, aquí tienes algunos ejempos de la utilidad de integrar ‘AirTag’ en Home Assistant:

  • Para mi el más evidente, permitir que usuarios de Android puedan tener acceso a la ubicación de los objetos con un AirTag.
  • Establecer un sistema “antirrobo”, definiendo una automatización que te envíe una notificación cuando alguno de tus objetos no está en la dirección de tu casa.
  • Recibir una notificación cuando tu mascota se haya ido de casa (o haya vuelto).
  • Activar el sistema de seguridad de tu casa cuando el AirTag de tu maleta de viaje esté fuera de casa.

¿Dudas?¿necesitas ayuda? entra aquí
Y si te ha gustado, compártelo! 🙂
sorteo
Send this to a friend