Commissioning Zigbee sin estados imaginarios.

Bases recomendadas: producción https://api.voltic.es/api/v1/bms, desarrollo https://api-dev.voltic.es/api/v1/bms y local http://localhost:8090/api/v1/bms. Las llamadas requieren bearer o sesión autenticada.

const room = await api.get(`/installer/rooms/${roomUuid}/devices`);
const slots = room.data;
const hubUuid = room.context.hub.uuid;

{
  "jwt": "eyJhbGciOiJIUzUxMiIs..."
}

Suscripción obligatoria antes del POST

const topic = `${hubUuid}/installer/join-events`;
const mqttClient = connectToConfiguredBroker({
  username: authenticatedUser.username,
  password: buildingJwt.jwt,
});

mqttClient.subscribe(topic);
mqttClient.on("message", (receivedTopic, payload) => {
  if (receivedTopic !== topic) return;
  renderJoinEvent(JSON.parse(payload.toString()));
});

{
  "mode": "new_device",
  "room_uuid": "ROOM_UUID",
  "device_uuid": "EMPTY_SLOT_UUID"
}

{
  "mode": "replacement",
  "device_ieee": "0x94b216fffe90b13d",
  "new_device_ieee": "0x583bc2fffe9021f1"
}

HTTP/1.1 202 Accepted
Retry-After: 5

{
  "data": {
    "operation_uuid": "019f8e9d-928f-70e3-8481-d2c3af57310c",
    "mode": "replacement",
    "new_device_ieee": "0x583bc2fffe9021f1",
    "requested_backend": {
      "type": "auto",
      "device_uuid": null
    },
    "status": "queued",
    "message": "Join request queued.",
    "selected_backend": null,
    "attempts": 0,
    "retry_after_seconds": 5
  }
}

Selección avanzada del backend

{
  "mode": "replacement",
  "device_ieee": "OLD_IEEE",
  "new_device_ieee": "NEW_IEEE",
  "join_backend": "device",
  "join_backend_device_uuid": "ROUTER_DEVICE_UUID"
}

Eventos del feed MQTT

{
  "operation_uuid": "019f8e9d-928f-70e3-8481-d2c3af57310c",
  "type": "device_interview",
  "status": "successful",
  "ieee_address": "0x583bc2fffe9021f1",
  "friendly_name": "0x583bc2fffe9021f1",
  "supported": true,
  "model": "Frostline 2",
  "vendor": "Voltic",
  "reported_at": "2026-07-23T10:56:12Z"
}

async function pollJoin(hubUuid, operationUuid) {
  while (true) {
    const { data } = await api.get(
      `/installer/hubs/${hubUuid}/join-requests/${operationUuid}`
    );

    updateScreen(data);
    if (data.status === "succeeded" || data.status === "failed") return data;

    await wait((data.retry_after_seconds ?? 5) * 1000);
  }
}

{
  "status": "succeeded",
  "message": "Join request completed successfully.",
  "joined_device": {
    "ieee_address": "0x583bc2fffe9021f1",
    "friendly_name": "hotel/room/1132/bed/thermostat/0x583bc2fffe9021f1",
    "discovered_friendly_name": "0x583bc2fffe9021f1",
    "manufacturer": "Voltic",
    "model": "Frostline 2",
    "type": "Router",
    "topic": "hotel/room/1132/bed/thermostat/0x583bc2fffe9021f1"
  },
  "error": null
}

Evitar duplicados

Si se pierde la respuesta del POST, consultar primero el estado visible del hub o repetir el POST sabiendo que el backend reutiliza la operación activa del hub. Nunca lanzar operaciones en paralelo desde dos pantallas para el mismo hub.

type JoinBackend =
  | { type?: "auto" }
  | { type: "coordinator" }
  | { type: "device"; deviceUuid: string };

type ReplacementInput = {
  hubUuid: string;
  currentDeviceIeee: string;
  newDeviceIeee: string;
  backend?: JoinBackend;
};

async function replaceDevice(input: ReplacementInput) {
  const backend = input.backend ?? { type: "auto" as const };

  const body = {
    mode: "replacement",
    device_ieee: input.currentDeviceIeee,
    new_device_ieee: input.newDeviceIeee,
    ...(backend.type !== "auto" && { join_backend: backend.type }),
    ...(backend.type === "device" && {
      join_backend_device_uuid: backend.deviceUuid,
    }),
  };

  const response = await api.post(
    `/installer/hubs/${input.hubUuid}/join-requests`,
    body
  );

  return response.data;
}

Modelo de pantalla recomendado

• Suscribirse al feed {hubUuid}/installer/join-events antes del POST.
• Crear la operación y conservar operation_uuid; comprobar 202 y Retry-After: 5.
• Poner únicamente el IEEE esperado en pairing dentro de la ventana de 120 segundos.
• Ver device_joined → interview started → interview successful en el feed.
• Ver el último evento reflejado en join_event durante el polling.
• Confirmar succeeded y el topic nuevo terminado en el IEEE nuevo.
• Confirmar en Zigbee2MQTT que el anterior fue eliminado y el nuevo conserva el friendly name canónico.
• Confirmar en BMS que el nuevo Device está activo y el anterior tiene soft-delete.
• Repetir un fallo controlado para validar timeout, copy de error y reintento con coordinador/router explícito.

Comandos de observación

# Feed reducido para frontend
mosquitto_sub -h "$MQTT_HOST" -p 8883 \
  -u "$MQTT_USER" -P "$MQTT_JWT" \
  -t "$HUB_UUID/installer/join-events" -v

# Operación autoritativa
curl -sS -H "Authorization: Bearer $API_TOKEN" \
  "$API_BASE/installer/hubs/$HUB_UUID/join-requests/$OPERATION_UUID"