# Matter

> Referencia del controlador Matter: las redes Wi-Fi y Thread a las que se unen los dispositivos, la puesta en marcha por Bluetooth en la Fabric local, el recorrido de Emparejar dispositivo, la identidad del nodo, los tags que vienen del dispositivo y lo que hace escribir cada uno.

El controlador Matter lee equipos **Matter**: sensores inteligentes, enchufes, luces y dispositivos parecidos certificados para el estándar Matter, tanto si se unen a la red por **Wi-Fi** como por **Thread**. Es un solo controlador para los dos. La red es solo el camino de entrada: en cuanto un dispositivo está en ella, Ganter Lab lo lee del mismo modo, por la red local.

Ganter Lab actúa como un **controlador Matter con su propia Fabric local**: pone en marcha cada dispositivo una vez por **Bluetooth Low Energy** desde este ordenador, le entrega las credenciales de una red registrada en la tarjeta **Redes** del controlador, y a partir de ahí habla con él por la red local: a través de su router en un dispositivo Wi-Fi, a través de su Thread Border Router en un dispositivo Thread.

Usted nunca le dice a Ganter Lab si un dispositivo es Wi-Fi o Thread: **lo dice el propio dispositivo**. Una vez abierta la sesión por Bluetooth, Ganter Lab lee del dispositivo a qué tipo de red se une, antes de escribir nada en él, y se detiene con un mensaje propio cuando la red elegida es del otro tipo.

Eso invierte el orden habitual de configuración. Un dispositivo Matter no parte de un host y un puerto: parte de una **ceremonia de emparejamiento**, y después solo se guarda la identidad estable del nodo puesto en marcha.

Lo que hace falta antes de emparejar:

- Un **adaptador Bluetooth Low Energy** en este ordenador, encendido y con Windows permitiendo que Ganter Lab lo use.
- La red a la que se unirá el dispositivo, registrada en la tarjeta **Redes**: para un dispositivo Wi-Fi, el nombre de la Wi-Fi y su contraseña; para un dispositivo Thread, una red Thread existente con un Border Router, y su **conjunto de datos operativo activo** completo. Ganter Lab une dispositivos a su red; no puede inventarle credenciales.
- El **código de configuración** del dispositivo, impreso en el propio dispositivo o en su embalaje, y el dispositivo en modo de emparejamiento.

## Redes {#networks}

El panel del controlador Matter lleva una tarjeta titulada **Redes**: las redes Wi-Fi y Thread a las que se unen los dispositivos, una por fila. Una red se registra **una vez, antes del primer dispositivo**, y sirve a todos los dispositivos que se emparejan en ella, así que emparejar una segunda lámpara en la misma Wi-Fi ya no pide nada. La tarjeta solo se dibuja para un rol que puede configurar el Connector, porque guarda los secretos de las redes y no sirve más que para emparejar.

La cabecera de la tarjeta lleva sus comandos, en este orden:

| Comando | Qué hace | Qué no hace |
|---|---|---|
| **Añadir red Wi-Fi** | Añade una red Wi-Fi y la selecciona. Cuando este ordenador está conectado a una Wi-Fi cuyo nombre aún no está registrado, la red nueva toma ese nombre; si no, empieza sin nombre, para que usted lo escriba. Windows solo entrega el nombre, y solo cuando deja que las aplicaciones conozcan la ubicación de este ordenador (Windows 11 pide ese permiso); la contraseña la escribe siempre usted. | No lee la contraseña de Windows ni comprueba que la red exista. |
| **Añadir red Thread** | Añade una red Thread y la selecciona, con un nombre provisional (numerado cuando ya está ocupado) hasta que usted le dé el suyo, y a la espera de su conjunto de datos. | No habla con el Border Router: Ganter Lab solo usa el conjunto de datos de la red que creó el Border Router. |
| **Quitar red** | Quita la red seleccionada, tras una confirmación que la nombra y dice que los dispositivos ya emparejados no se ven afectados. Sin ninguna red seleccionada, sigue dibujado y atenuado, y su información emergente lo dice. | No toca los dispositivos ya emparejados en esa red: siguen funcionando y conservan su nombre en su campo **Red**. |

La tabla muestra, de cada red, su **Nombre**, su **Tipo de red** (**Red Wi-Fi** o **Red Thread**) y su **Estado**: **Lista para emparejar**, o lo que todavía le falta a la red. Una red cuyo nombre aún no se ha escrito aparece como **Red sin nombre**.

Los campos de la red seleccionada se editan allí mismo, bajo la tabla, y se guardan solos. Un valor que las reglas de abajo rechazan no se escribe, y el campo dice por qué.

| Tipo | Campo | Qué es | Formato |
|---|---|---|---|
| Wi-Fi | **Nombre de la Wi-Fi** | El nombre (SSID) que se entrega al dispositivo, tal cual lo emite el router: las mayúsculas cuentan. Cada nombre de Wi-Fi se registra una vez. | De 1 a 32 bytes de texto (UTF-8). |
| Wi-Fi | **Contraseña** | La contraseña de la Wi-Fi que se entrega al dispositivo. | Vacía para una red abierta; si no, de 8 a 63 caracteres ASCII imprimibles (una frase de contraseña WPA), o exactamente 64 dígitos hexadecimales (la clave en bruto). |
| Thread | **Nombre** | Su nombre para la red, para reconocerla al emparejar y en cada dispositivo. Cada nombre de red Thread se registra una vez. | Texto libre. |
| Thread | **Conjunto de datos operativo Thread** | El conjunto de datos activo completo de su red Thread, obtenido del administrador de la red o de su Border Router. Home Assistant lo muestra; Alexa y Apple no. | Texto hexadecimal (se toleran los espacios en blanco y un prefijo `hex:`), de 254 bytes como mucho una vez descodificado. Tiene que ser el conjunto de datos completo: Active Timestamp, Channel, Channel Mask, Extended PAN ID, Mesh-Local Prefix, Network Key, Network Name, PAN ID, PSKc y Security Policy tienen que estar todos presentes, y un conjunto de datos parcial o mal formado se rechaza nombrando el elemento que falta. |

Dos cosas deciden si un dispositivo Wi-Fi se puede emparejar, y la tarjeta dice las dos junto a los campos:

- **La mayoría de los dispositivos solo se unen a redes de 2,4 GHz.** Un router que emite un mismo nombre en 2,4 GHz y en 5 GHz les sirve; una red que solo existe en 5 GHz, no.
- **Este equipo y los dispositivos tienen que estar en la misma red local.** Una red de invitados, o el aislamiento de clientes activado en el router, impide que el equipo encuentre los dispositivos una vez que se han unido.

Una red solo sirve para emparejar mientras su secreto cumple esas reglas: una red Wi-Fi con nombre y contraseña válidos (vacía incluida), una red Thread con un conjunto de datos válido.

Editar una red cambia lo que entrega el **siguiente** emparejamiento, nunca lo que un dispositivo ya recibió. Un dispositivo que tiene que pasar a otra red, o cuyo router recibió una contraseña nueva, se restablece y se vuelve a emparejar.

## El recorrido de Emparejar dispositivo {#the-pair-device-flow}

En el controlador Matter, la barra de herramientas ofrece **Emparejar dispositivo** donde los demás controladores ofrecen Añadir dispositivo, y también la entrada Matter del menú Nuevo… de la columna. Mientras ninguna red sirva para emparejar, sigue dibujado y atenuado, con la información emergente "Añada primero la red a la que se va a unir el dispositivo." Si no, abre un formulario:

| Campo | Qué es | Formato | Por defecto |
|---|---|---|---|
| Nombre del dispositivo | El nombre editable que llevará el dispositivo en el Connector. | Texto libre | `Dispositivo Matter` |
| Código de configuración Matter | El código de emparejamiento manual oficial, o la carga QR completa. Se escribe oculto, con un mando para revelarlo. | Un código manual de 11 o 21 dígitos (los guiones y los espacios se ignoran; el dígito de control se verifica), o la carga QR completa que empieza por `MT:`. Una carga QR que no anuncia la puesta en marcha por Bluetooth se rechaza, igual que los códigos de acceso reservados o fuera de rango. | vacío |
| Red | La red registrada a la que se unirá el dispositivo. Con una sola red que sirva, el formulario dice en una línea cuál es y de qué tipo, sin nada que elegir; con más, es una lista para elegir. | Una de las redes que sirven en la tarjeta **Redes** | la única, cuando hay una sola |
| Carpeta de destino | Solo cuando el Nuevo dispositivo de una carpeta abrió el formulario: la carpeta en la que se archiva el dispositivo emparejado. Abierto con Emparejar dispositivo, no hay esa línea y el dispositivo queda en el nivel propio del controlador. | Solo lectura | la carpeta que abrió el formulario |

Una carpeta del controlador Matter ofrece **Nuevo dispositivo** (en su tabla Dispositivos, en su menú del clic derecho y en Nuevo… > Matter > `<Carpeta>`). Abre este mismo formulario, en gris del mismo modo mientras ninguna red sirva, y el dispositivo emparejado se archiva en esa carpeta.

**Emparejar dispositivo** en el formulario se queda deshabilitado hasta que el nombre y el código de configuración están rellenos y alguna red sirve. Mientras el emparejamiento corre, el formulario informa de su etapa: **Validar** (comprobar el código y el secreto de la red), **Buscar** (buscar el dispositivo por Bluetooth), **Emparejar** (autenticar con el código de configuración y leer a qué tipo de red se une el dispositivo), **Unirse a la red** (enviar la red al dispositivo y después preguntar por él en la red local hasta que responda; la línea de estado dice si esa red es Wi-Fi o Thread) y **Guardar** (abrir la sesión segura con el dispositivo en la red local, terminar su puesta en marcha y anotar el nodo en la Fabric local).

**Cancelar** está disponible mientras el dispositivo físico todavía no se ha modificado; en cuanto la puesta en marcha ha alterado el dispositivo, el botón dice que Ganter Lab está terminando de forma segura y el recorrido completa el registro en vez de abandonar un nodo a medio poner en marcha. Se empareja de uno en uno; un segundo intento mientras hay uno en curso se rechaza.

El dispositivo nuevo guarda el nombre de la red a la que se unió, que se muestra en su campo **Red**. Emparejar el siguiente dispositivo en la misma red solo pide su nombre y su código de configuración.

## Cuando el emparejamiento falla {#when-pairing-fails}

Si el emparejamiento falla, el mensaje declara la causa y qué hacer:

| Causa | Qué significa | El equipo | Qué hacer |
|---|---|---|---|
| Código de configuración no válido | El código no es un código manual oficial de 11 o 21 dígitos, ni una carga QR `MT:` completa. | Intacto | Releer el código impreso. |
| Conjunto de datos Thread no válido | El conjunto de datos de la red Thread elegida no está completo y bien formado. | Intacto | Volver a copiar el conjunto de datos activo completo en esa red, en la tarjeta **Redes**. |
| Nombre o contraseña de Wi-Fi no válidos | El nombre o la contraseña de la red Wi-Fi elegida no cumplen las reglas de la tarjeta **Redes**. | Intacto | Corregirlos en la tarjeta. |
| Bluetooth ausente, apagado o denegado | Este equipo no tiene un adaptador Bluetooth Low Energy utilizable, el Bluetooth está apagado, o Windows ha denegado a Ganter Lab el acceso a él. | Intacto | Encender el Bluetooth, o permitir en Windows que Ganter Lab lo use, y volver a intentarlo. |
| Ningún dispositivo encontrado que coincida | Ningún dispositivo en modo de emparejamiento respondió para este código de configuración. | Intacto | Poner el dispositivo en modo de emparejamiento, mantenerlo cerca de este ordenador y volver a intentarlo. |
| Código de configuración rechazado | El dispositivo rechazó el código. | Intacto | Releer el código impreso y volver a poner el dispositivo en modo de emparejamiento. |
| El dispositivo se une por Wi-Fi | La red elegida es Thread. | Intacto: se leyó, y no se escribió nada en él | Registrar la red Wi-Fi a la que se unirá el dispositivo y volver a emparejar, eligiéndola. |
| El dispositivo se une por Thread | La red elegida es Wi-Fi. | Intacto: se leyó, y no se escribió nada en él | Registrar la red Thread y volver a emparejar, eligiéndola. |
| El dispositivo es cableado (Ethernet) | El emparejamiento por Bluetooth no sirve para un dispositivo cableado. | Intacto: se leyó, y no se escribió nada en él | Ganter Lab no puede emparejar este dispositivo. |
| El dispositivo no dice su red | El dispositivo no declara ni Wi-Fi, ni Thread, ni Ethernet. | Intacto: se leyó, y no se escribió nada en él | Ganter Lab no puede emparejar este dispositivo. |
| Red Wi-Fi no encontrada | El dispositivo respondió que no encontró ninguna Wi-Fi con ese nombre: una errata o un fallo de mayúsculas, una red solo en 5 GHz, o un dispositivo fuera de alcance. | No conserva nada: descarta lo que recibió y vuelve al modo de emparejamiento. Sin ID de nodo. | Corregir el nombre en la tarjeta **Redes**, comprobar que el router lo emite en 2,4 GHz y volver a emparejar. |
| Contraseña de Wi-Fi rechazada | El dispositivo respondió que la Wi-Fi rechazó la contraseña. | No conserva nada: descarta lo que recibió y vuelve al modo de emparejamiento. Sin ID de nodo. | Corregir la contraseña en la tarjeta **Redes** y volver a emparejar. |
| El dispositivo no pudo unirse a la red | El dispositivo respondió que no pudo unirse a la red, por un motivo distinto de los dos anteriores (en Thread, cualquier rechazo, incluida una red que no encontró). | No conserva nada: descarta lo que recibió y vuelve al modo de emparejamiento. Sin ID de nodo. | Revisar la red en la tarjeta **Redes** (en Thread, volver a copiar el conjunto de datos activo vigente y comprobar que el Border Router está encendido) y volver a emparejar. |
| El dispositivo no apareció en la red | El dispositivo no dio ninguna respuesta sobre la red, o nunca apareció después en la red local. Algunos dispositivos dejan el Bluetooth para unirse a la red y no pueden responder en absoluto. | Puesto en marcha: el mensaje muestra el ID de nodo | En Wi-Fi, comprobar que este ordenador y el dispositivo están en la misma red local, sin red de invitados ni aislamiento de clientes entre ellos; en Thread, que el Border Router está encendido y es alcanzable. Después, recuperar el nodo con Descubrir. |
| La sesión segura no se abrió | El dispositivo se unió a la red y se encontró allí, pero la sesión segura con él, o la finalización del emparejamiento por esa sesión, falló. El diario técnico indica el paso y lo que respondió el dispositivo. | Puesto en marcha: el mensaje muestra el ID de nodo | Recuperar el nodo con Descubrir. Si Descubrir lo encuentra sin valores con el dispositivo encendido, volver a poner el dispositivo en modo de emparejamiento y emparejarlo de nuevo. |
| Otro emparejamiento en curso | Se empareja de uno en uno. | Intacto | Esperar a que termine y volver a intentarlo. |
| No se pudo guardar la Fabric local | Ganter Lab no pudo guardar la Fabric de forma segura. | Intacto cuando ocurre antes de que empiece el emparejamiento; puesto en marcha, con el ID de nodo, cuando ocurre después | Resolver el problema de almacenamiento antes de restablecer nada. |

Siempre que un fallo llega después de que el equipo ya se hubiera puesto en marcha, el mensaje lo dice y muestra el ID de nodo: el nodo **sigue en la Fabric** y se puede añadir más tarde con Descubrir en cuanto alcance la red. En ese caso no reinicie el dispositivo; solo un mensaje que dice que no se guardó nada significa que el equipo quedó intacto.

Un dispositivo que responde que no pudo unirse a la red es la excepción: no guarda nada que valga la pena conservar. Ganter Lab termina el emparejamiento en el dispositivo, que descarta lo que recibió y vuelve en el acto al modo de emparejamiento, y quita su nodo de la Fabric; por eso el mensaje no lleva ID de nodo y Descubrir nunca lista un nodo que no puede responder. Corrija la red y vuelva a emparejar. Solo un dispositivo que no dio ninguna respuesta conserva su nodo, porque si se unió solo se sabe cuando aparece en la red local.

## Qué se guarda {#what-is-stored}

| Qué | Dónde se guarda | Cómo |
|---|---|---|
| El nombre y el tipo de una red | La configuración de la estación | Tal como se escribieron. |
| La contraseña de la Wi-Fi y el conjunto de datos operativo Thread | La configuración de la estación | Protegidos para el usuario de Windows que los escribió, igual que las contraseñas de los dispositivos: en otra cuenta de Windows se leen vacíos y hay que volver a escribirlos. Una copia de seguridad los deja fuera; la [exportación para otra máquina](settings-backups#export-for-another-machine) los lleva, sellados con su propia contraseña. |
| El código de configuración | En ningún sitio | Existe solo en el formulario mientras corre el emparejamiento, y se borra cuando el emparejamiento termina, falla o se cancela. |
| La red a la que se unió un dispositivo | La configuración del dispositivo | Su nombre, que se muestra en el campo **Red** del dispositivo. |
| La identidad del dispositivo | La configuración del dispositivo y la Fabric local | El ID de nodo. |

La contraseña de la Wi-Fi y el conjunto de datos nunca aparecen en el diario técnico, en la dirección de un dispositivo ni en su Thing Description. Las redes y el emparejamiento no se ofrecen a los agentes por el servidor MCP: emparejar necesita a alguien junto al dispositivo, y las redes guardan secretos.

## La identidad del nodo {#node-identity}

Un dispositivo emparejado queda ligado al **ID de nodo** estable de 64 bits del equipo, mostrado de solo lectura en su tarjeta Conexión como 16 dígitos hexadecimales, junto al estado del dispositivo. El nombre visible editable es suyo y se puede cambiar; el ID de nodo no. Un dispositivo cuya identidad guardada ya no se puede leer muestra en su lugar **Necesita volver a emparejarse**.

El panel del dispositivo muestra también un campo **Red** de solo lectura: el nombre de la red a la que se unió el dispositivo al emparejarse. Un dispositivo emparejado por una versión que no lo registraba dice que no se registró nada. El campo es un registro, no un ajuste: editar o quitar esa red en la tarjeta **Redes** no cambia nada en el dispositivo.

Como la identidad es el ID de nodo, los dispositivos Matter mantienen un estado de conexión independiente: deshabilitar, eliminar o perder un nodo no deja a otro no disponible, y eliminar un dispositivo libera solo su uso de la sesión segura, no quita el equipo de la Fabric local.

## Descubrimiento {#discovery}

**Descubrir** en el controlador Matter lista los nodos ya puestos en marcha en la Fabric local de
esta aplicación y lee, de cada uno, los valores que publica. Para leerlos abre una sesión segura con
cada nodo, así que un nodo que está fuera de la red sigue en la lista, sin valores, una vez que su
sesión no se pudo abrir. Los candidatos del descubrimiento llevan la identidad del nodo y ningún
secreto de configuración. El recorrido general del descubrimiento se describe en
[Descubrimiento](connector-discovery).

| El nodo | Su tarjeta | Sus verbos |
|---|---|---|
| No tiene dispositivo aquí: su dispositivo se eliminó, o su emparejamiento terminó sin uno | Los valores que publica, cada uno marcado | **Añadir dispositivo** crea el dispositivo con los valores marcados como sus tags, sin una ceremonia nueva. |
| Es un dispositivo configurado, con valores que aún no tienen tag | Marcado como ya configurado, con cuántos valores publica que todavía no son tags, y esos valores marcados | **Añadir tags** añade los valores marcados a ese dispositivo; **Abrir** lo abre. |
| Es un dispositivo configurado con un tag para cada valor | "Ya configurado, con un tag para cada valor que publica el dispositivo." | **Abrir** lo abre. |
| Es un dispositivo configurado que no informó de ningún valor | "Ya configurado. El dispositivo no informó de ningún valor: vuelva a ejecutar Descubrir cuando esté en línea." | **Abrir** lo abre. |

Los valores de un dispositivo configurado se comparan con sus tags por salida, clúster y atributo,
nunca por nombre: un tag que usted renombró sigue contando, y un valor nunca se añade dos veces.

La propia página del dispositivo ofrece lo mismo sin salir de ella: **Descubrir tags**, en la cabecera de su tarjeta de tags, lee solo ese nodo y lista, marcados, los valores para los que todavía no tiene tag, con **Añadir tags** (vea [Descubrir los tags de un dispositivo](connector-discovery#discovering-a-devices-tags)).

## Tags {#tags}

Los tags de un dispositivo Matter vienen del propio dispositivo: nadie escribe un clúster ni un
número de atributo para ellos. Un emparejamiento que sale bien lleva directamente a ellos. El
registro de acciones se lee "Se emparejó el dispositivo Matter 'Luz de la cocina'.", la página se
abre en el controlador Matter, con el dispositivo nuevo resaltado en su tabla Dispositivos, y una exploración de ese único dispositivo se lanza enseguida. El
dispositivo que creó el emparejamiento aparece en **Dispositivos descubiertos** con los valores que
publica, todos marcados, y la exploración termina con "Marque los valores de 'Luz de la cocina' que
se van a crear como tags y pulse Añadir tags." Desmarque lo que no quiera y pulse **Añadir tags**;
el registro de acciones se lee entonces "Se añadieron 5 tags a 'Luz de la cocina'." Un dispositivo
que todavía no ha respondido no informa de nada: "'Luz de la cocina' todavía no informó de ningún
valor. Vuelva a ejecutar Descubrir cuando esté en línea." La misma tarjeta vuelve en cada
**Descubrir** posterior, con los valores para los que el dispositivo todavía no tiene tag.

**Añadir tags** solo se dibuja para un rol con Configurar Connector. Queda atenuado, con su motivo
como información emergente, mientras corre una exploración o un emparejamiento, mientras la estación
rechaza cambios y mientras no hay nada marcado ("Marque al menos un valor para añadir."). Un valor
cuya salida, clúster y atributo el dispositivo ya lee nunca se vuelve a añadir; cuando todos los
valores marcados ya están, no se guarda nada: "'Luz de la cocina' ya tiene un tag para cada valor
marcado, así que no se añadió nada." Un nombre que ya lleva otro tag del dispositivo recibe un
número detrás, como en Brillo (2).

La exploración lee lo que el dispositivo publica, tal como lo organiza la especificación Matter:

| Qué | Dónde lo dice el dispositivo |
|---|---|
| Sus salidas (endpoints) | El clúster Descriptor (0x001D) en el endpoint 0, atributo `PartsList` |
| Los clústeres de cada salida | El Descriptor de esa salida, atributo `ServerList` |
| Los valores de cada clúster | Su atributo `AttributeList` (0xFFFB) |
| Los comandos que admite cada clúster | Su atributo `AcceptedCommandList` (0xFFF9) |
| Las funciones opcionales que implementa cada clúster | Su atributo `FeatureMap` (0xFFFC) |
| La lectura actual de cada valor | El propio valor, leído una vez |

Lo que ofrece la exploración, y con qué nombre:

| Un valor | Se ofrece como |
|---|---|
| Uno que el controlador conoce (la sección siguiente) | Su nombre claro en el idioma de la estación y el tipo que le da la especificación; se puede escribir solo cuando el dispositivo admite la forma en que la especificación lo cambia, si no, de solo lectura |
| Uno que el controlador conoce, de una función que el clúster no implementa: tono y saturación sin la función Hue and Saturation, temperatura de color sin la función Color Temperature | No se ofrece |
| Uno que el controlador no conoce | De solo lectura, con su nombre en la especificación Matter (`Level Control OnLevel`), o con el clúster y el número de atributo cuando el controlador no conoce el atributo (`On/Off attribute 0x131B0001`); su tipo es el de la lectura que devolvió el dispositivo |
| El mismo valor en más de una salida | Su nombre dice qué salida, como en Brillo (salida 2) |
| Un atributo global (0xFFF8 a 0xFFFD), o un valor del propio nodo (endpoint 0) | No se ofrece |
| Una lista o una estructura, un valor de un tipo que el controlador no maneja, un valor del que el dispositivo no devolvió lectura | Se deja fuera y se cuenta en la línea que cierra la exploración |

Un tag que se ofrece como escribible llega con el acceso Lectura y escritura; todos los demás llegan
con Solo lectura.

## Los valores que el controlador conoce {#the-values-the-driver-knows}

El controlador lleva una tabla, tomada de la especificación Matter, de los valores que conoce por su
nombre y de cómo cambia cada uno. Un valor cambia de una de tres formas: con un comando que envía el
controlador y que el dispositivo debe listar entre los comandos que admite; con una escritura del
propio atributo, donde la especificación lo hace escribible y el dispositivo lo lista; o de ninguna
forma, para un valor que el dispositivo solo informa.

| Valor | Clúster y atributo | Tipo | Qué hace en el dispositivo escribirlo | Rango que define la especificación |
|---|---|---|---|---|
| Encendido | On/Off (0x0006), `OnOff` (0x0000) | Boolean | true envía el comando `On` (0x01), false envía `Off` (0x00); escribible solo cuando el dispositivo admite los dos | true o false |
| Brillo | Level Control (0x0008), `CurrentLevel` (0x0000) | UInt32 | Envía `MoveToLevelWithOnOff` (0x04) con el nivel, un tiempo de transición de 0 y sin opciones forzadas: la salida se enciende con el nivel y se apaga en el mínimo | 0 a 254 |
| Tono | Color Control (0x0300), `CurrentHue` (0x0000) | UInt32 | Envía `MoveToHue` (0x00) por el camino más corto, con un tiempo de transición de 0; solo con la función Hue and Saturation | 0 a 254 |
| Saturación | Color Control (0x0300), `CurrentSaturation` (0x0001) | UInt32 | Envía `MoveToSaturation` (0x03) con un tiempo de transición de 0; solo con la función Hue and Saturation | 0 a 254 |
| Temperatura de color | Color Control (0x0300), `ColorTemperatureMireds` (0x0007) | UInt32 | Envía `MoveToColorTemperature` (0x0A) con un tiempo de transición de 0; solo con la función Color Temperature. El dispositivo mantiene el valor dentro de sus propios límites | 0 a 65279, en mireds |
| Posición de la persiana | Window Covering (0x0102), `CurrentPositionLiftPercent100ths` (0x000E) | UInt32 | Envía `GoToLiftPercentage` (0x05) | 0 (abierta) a 10000 (cerrada), en centésimas de porcentaje |
| Temperatura ambiente | Thermostat (0x0201), `LocalTemperature` (0x0000) | Float, en °C | Nada: solo lectura | -27315 a 32767, en centésimas de grado Celsius; se lee de -273,15 a 327,67 °C |
| Consigna de refrigeración | Thermostat (0x0201), `OccupiedCoolingSetpoint` (0x0011) | Float, en °C | Escribe el atributo. El dispositivo rechaza una consigna fuera de sus propios límites | -27315 a 32767, en centésimas de grado Celsius; se lee de -273,15 a 327,67 °C |
| Consigna de calefacción | Thermostat (0x0201), `OccupiedHeatingSetpoint` (0x0012) | Float, en °C | Escribe el atributo. El dispositivo rechaza una consigna fuera de sus propios límites | -27315 a 32767, en centésimas de grado Celsius; se lee de -273,15 a 327,67 °C |
| Modo del ventilador | Fan Control (0x0202), `FanMode` (0x0000) | UInt32 | Escribe el atributo | 0 apagado, 1 bajo, 2 medio, 3 alto, 4 encendido, 5 automático, 6 inteligente |
| Ajuste de velocidad del ventilador | Fan Control (0x0202), `PercentSetting` (0x0002) | UInt32 | Escribe el atributo | 0 a 100 por ciento |
| Velocidad del ventilador | Fan Control (0x0202), `PercentCurrent` (0x0003) | UInt32 | Nada: solo lectura | 0 a 100 por ciento |
| Temperatura | Temperature Measurement (0x0402), `MeasuredValue` (0x0000) | Float, en °C | Nada: solo lectura | -27315 a 32767, en centésimas de grado Celsius; se lee de -273,15 a 327,67 °C |
| Humedad | Relative Humidity Measurement (0x0405), `MeasuredValue` (0x0000) | Float, en % | Nada: solo lectura | 0 a 10000, en centésimas de porcentaje; se lee de 0 a 100 % |
| Iluminancia | Illuminance Measurement (0x0400), `MeasuredValue` (0x0000) | UInt32 | Nada: solo lectura | 0 a 65534, que es 10000 × log10(lux) + 1 |
| Presión | Pressure Measurement (0x0403), `MeasuredValue` (0x0000) | Float, en kPa | Nada: solo lectura | -32767 a 32767, en décimas de kilopascal; se lee de -3276,7 a 3276,7 kPa |
| Ocupación | Occupancy Sensing (0x0406), `Occupancy` (0x0000) | Boolean | Nada: solo lectura | true cuando hay alguien |
| Estado | Boolean State (0x0045), `StateValue` (0x0000) | Boolean | Nada: solo lectura | true o false |

La especificación envía las temperaturas, la humedad y la presión en unidades fijas: centésimas de
grado Celsius, centésimas de porcentaje y décimas de kilopascal. El descubrimiento ofrece esos
valores ya en °C, % y kPa: el tag llega con el factor en su etapa Escala (0,01 para una temperatura
y una humedad, 0,1 para una presión) y con la unidad, así que un dispositivo que envía 2150 se lee
21,5 °C. Una escritura deshace esa etapa antes de que el valor salga, así que una consigna escrita
como 21,5 llega al dispositivo como 2150. La iluminancia es logarítmica (10000 × log10(lux) + 1),
así que ningún factor la convierte: se lee el número que envía el dispositivo. Todos los demás
valores también se leen tal como los envía el dispositivo.

Las cerraduras, el color por coordenadas X e Y, las escenas, los grupos y el comando `Toggle` no
están en la tabla. Un dispositivo Matter tampoco tiene comandos propios: todo cambio es una
escritura en uno de sus tags.

## Escribir un valor {#writing-a-value}

Un tag Matter con acceso Lectura y escritura cambia el dispositivo cuando se escribe: desde su
tarjeta Valor en vivo, un control del dashboard, la Logic o un agente. La escritura entra en la cola
del dispositivo como la de cualquier controlador, por turno con las lecturas del dispositivo, y su
respuesta es la del propio dispositivo. El controlador elige el comando Matter o la escritura del
atributo a partir de la tabla; nadie elige un comando. Solo el SUCCESS del dispositivo cuenta como
escrito. Todo lo demás se rechaza, con un motivo:

| Qué pasa | Dónde se decide | El motivo que se da |
|---|---|---|
| El punto no es un valor de la tabla del controlador | Antes de enviar nada | El controlador no sabe cómo cambia el dispositivo ese valor, así que el tag solo lo lee. |
| El punto es un valor que la tabla marca como de solo lectura | Antes de enviar nada | El dispositivo informa de ese valor y nada de fuera lo fija. |
| El valor escrito no es true ni false (en un valor Boolean), o no es un número entero | Antes de enviar nada | Lo que admite el valor, y lo que se escribió. |
| El valor está fuera del rango que define la especificación | Antes de enviar nada | El rango, como lo da la tabla de arriba. |
| El tag no nombra ningún clúster | Antes de enviar nada | Que un valor Matter se encuentra por su salida, su clúster y su atributo. |
| El dispositivo responde con cualquier estado que no sea SUCCESS | El dispositivo | El estado tal como lo dio el dispositivo: su nombre en la especificación y su número, por ejemplo CONSTRAINT_ERROR, 0x87 (el valor está fuera de lo que el dispositivo admite) o UNSUPPORTED_COMMAND, 0x81 (el dispositivo no admite el comando que cambia ese valor). Un estado que añade el clúster va detrás (FAILURE, 0x01, cluster 0x02), y un estado que la especificación no nombra se lee solo con su número. |
| El dispositivo no responde a tiempo | El dispositivo | Sin respuesta. |

Una escritura rechazada nunca se informa como escrita, ni como un equipo inalcanzable. En la página
del tag, la línea de estado se lee "Escritura rechazada por el equipo: CONSTRAINT_ERROR, 0x87."
cuando el dispositivo la rechazó, con el motivo en lugar del estado para un rechazo resuelto antes
de enviar nada, y "Escritura no confirmada: el equipo no respondió a tiempo." cuando no llegó
respuesta; "Error de escritura: no se pudo alcanzar el equipo." queda para un dispositivo que no
está conectado. El motivo también viaja con la escritura: la línea del diario de esa escritura lo
nombra, con lo que significa el estado, y el `tag_write` de un agente lo devuelve.

## Un tag hecho a mano {#a-tag-made-by-hand}

Para el raro valor que el dispositivo no publica de una forma que la exploración ofrezca, **Añadir
tag** en un dispositivo Matter crea un tag para rellenar a mano. Su tarjeta Fuente muestra tres
campos en una fila, y la vista previa de la dirección debajo los monta como
`<endpoint>/<cluster>/<attribute>`, en decimal (`1/8/0` es el brillo de la primera salida). Mientras
no se elige un clúster el tag no se guarda, y el panel dice: "Elija el clúster que lee este tag. Sin
él, nunca se pide nada al dispositivo."

| Campo | Qué hace | Valores | Predeterminado |
|---|---|---|---|
| **Salida (endpoint)** | Qué salida del dispositivo lee el tag. | 0 a 65535; 1 es la primera salida controlable, 0 el propio nodo | 1 |
| **Clúster Matter** | Qué clúster de esa salida lee el tag. | Los clústeres del catálogo Matter por su nombre en la especificación con su número, como en `Level Control (0x0008)`; un clúster que el catálogo no nombra, encontrado por una exploración, aparece primero por su número | ninguno |
| **Atributo** | Qué atributo del clúster lee el tag. | 0 o más; 0 es el valor propio del clúster | 0 |

El nombre del tag es libre: nombra el tag y no selecciona nada en el dispositivo. El tipo de dato se
elige entre Boolean, Int32, UInt32, Float, Double y String; una lectura que el tipo declarado no
puede representar se lee como error y no como un número de relleno.
El valor llega tal como lo envía el dispositivo: una temperatura, una humedad o una presión hecha a
mano se lee en centésimas o décimas hasta que le dé en su etapa Escala el factor y la unidad de la
tabla de arriba.

El campo de acceso ofrece escritura solo donde la tabla del controlador cambia el valor, y si no,
ofrece Solo lectura y dice debajo por qué:

| El punto | El campo de acceso ofrece | Lo que dice |
|---|---|---|
| Un valor de la tabla que cambia un comando o una escritura del atributo | Solo lectura, Solo escritura y Lectura y escritura | Nada |
| Todavía sin clúster elegido | Solo lectura | "Solo lectura hasta que el tag nombre un valor del dispositivo: elija su clúster." |
| Un valor que la tabla no conoce | Solo lectura | "Solo lectura: el controlador no sabe cómo cambia el dispositivo este valor." |
| Un valor que la tabla marca como de solo lectura | Solo lectura | "Solo lectura: el dispositivo informa este valor y nada desde fuera lo establece." |

Cuando una edición de la salida, del clúster o del atributo apunta el tag a un valor que el
controlador no puede escribir, su acceso vuelve a Solo lectura. Un tag que ofreció el
descubrimiento conserva el acceso que el descubrimiento le dio, porque solo el descubrimiento
pregunta al dispositivo qué comandos admite: un valor que el dispositivo no enumeró sigue en Solo
lectura, y el campo sigue ofreciendo escritura.

## Tags guardados por versiones anteriores {#tags-saved-by-earlier-versions}

Una versión anterior nombraba el clúster de un tag Matter solo con el nombre del tag, con una
dirección `<endpoint>/<attribute>`. Cuando esta versión arranca por primera vez, cada tag de un
dispositivo Matter cuyo nombre es un clúster del catálogo Matter (la parte que sigue a los últimos
dos puntos, sin los espacios de alrededor, sin distinguir mayúsculas) recibe ese clúster, así que
sigue leyendo exactamente el valor que leía. Su nombre queda como estaba, y la vista previa de su
dirección pasa a mostrar `<endpoint>/<cluster>/<attribute>`. Un tag cuyo nombre no coincidía con
ningún clúster nunca leyó nada: se queda sin clúster, sus lecturas se rechazan con un motivo que lo
dice, y su página pide el clúster. Un tag convertido conserva el acceso que tenía, Solo lectura, el
único que ofrecían esas versiones; para escribirlo, elija Lectura y escritura, que sirve para los
valores de la tabla de arriba.