Faça o ZBCMR-01 ser reconhecido pelo Zigbee2MQTT

Recentemente comprei um motor de persiana inteligente Nova Digital ZBCMR-01, mas ao tentar adicioná‑lo ao Zigbee2MQTT ele apareceu como “não suportado. O motivo é simples: o modelo que comprei tem um fingerprint diferente do que está cadastrado na base de dados do z2m. Neste post mostro como contornar o problema usando um conversor externo, passo a passo, e ainda como enviar a correção para que todos se beneficiem.

Se você já viu a mensagem de dispositivo não suportado, não desista: a solução está em habilitar os conversores externos e criar um arquivo pequeno que mapeia o fingerprint do seu lote.

Por que o ZBCMR-01 não é reconhecido?

A página do Zigbee2MQTT para o ZBCMR-01 lista o modelo como suportado, mas o fingerprint cadastrado é zigbeeModel: TS0105 + manufacturerName: _TZE600_ogyg1y6b. Seu módulo, de um lote diferente, se identifica como TS0601 + _TZE284_5blghqkp, uma combinação que ainda não está na base de dados, portanto o z2m recusa o dispositivo mesmo sendo “o mesmo produto”.

Passo a passo para adicionar o conversor externo

1. Verifique a versão do z2m – Acesse Settings > About. Se estiver desatualizado, atualize (geralmente não resolve sozinho, mas vale testar). Fonte principal.
2. Habilite conversores externos (necessário a partir da v2.11). Em configuration.yaml (do z2m e não do Home Assistant. Acesse por tanto o arquivo /root/config/zigbee2mqtt/configuration.yaml) confirme ou adicione:
   

   advanced:
      enable_external_js: true

   É provável que já exista uma seção chamada “advanced”. Depois reinicie o z2m. Mais detalhes.

3. Adicione o conversor externo – O jeito mais fácil é pelo frontend: Settings > Dev console > External converters. Crie um arquivo, por exemplo nova-zbcmr01.mjs, com o seguinte conteúdo:
   

   import * as legacy from ‘zigbee-herdsman-converters/lib/legacy’;
   import * as exposes from ‘zigbee-herdsman-converters/lib/exposes’;
   import * as tuya from ‘zigbee-herdsman-converters/lib/tuya’;

   const e = exposes.presets;
   const ea = exposes.access;

   export default {
       fingerprint: tuya.fingerprint(‘TS0601’, [‘_TZE284_5blghqkp’]),
       model: ‘ZBCMR-01’,
       vendor: ‘Nova Digital’,
       description: ‘Roller Blind Motor (lote TS0601)’,
       fromZigbee: [legacy.fromZigbee.tuya_cover],
       toZigbee: [legacy.toZigbee.tuya_cover_control],
       exposes: [e.cover_position().setAccess(‘position’, ea.STATE_SET)],
   };

   Se preferir, salve o arquivo diretamente na pasta external_converters/ (irmã do configuration.yaml).

4. Reinicie o z2m e repareie – Vá em Settings > Tools > Restart Zigbee2MQTT. Se o dispositivo já estava listado como “unsupported”, remova-o e coloque‑o em modo de pareamento novamente (reset físico do motor + permitir entrada na rede).
5. Teste abrir/fechar/parar e posição – Use os comandos OPEN, CLOSE, STOP e ajuste a posição com valores de 0 a 100. Caso o comportamento esteja invertido ou a posição não seja reportada, ajuste o conversor (por exemplo, invertendo a posição) ou siga o guia de descoberta de DPs para Tuya (fonte complementar 3).
6. Depois que funcionar – Abra uma issue “New device support” no repositório do Zigbee2MQTT (exemplo de issue) anexando os dados da interview, para que esse fingerprint seja incorporado oficialmente e você não precise manter o conversor externo para sempre.

Após seguir esses passos, seu motor deve aparecer na lista de dispositivos com as funcionalidades de abertura, fechamento, parada e controle de posição. Teste cada comando e confirme que os relatórios de estado estão corretos.

Testando e ajustando

Como os Datapoints (DPs) da Tuya podem variar entre lotes, vale observar o log do z2m enquanto aciona o motor. Se notar que a posição está invertida, basta mudar a linha exposes: [e.cover_position().setAccess(‘position’, ea.STATE_SET)] para usar exposes: [e.cover_position().setAccess(‘position’, ea.STATE_SET)] com a opção invert_cover: true na configuração do dispositivo, ou ajustar o conversor para mapear o DP correto. Se precisar de ajuda com o mapeamento de DPs, consulte o guia detalhado de suporte a novos dispositivos Tuya (fonte complementar 3).

Contribuindo para a base oficial

Quando tudo estiver funcionando, considere devolver à comunidade. Abra uma pull request no repositório zigbee-herdsman-converters ou uma issue no zigbee2mqtt com o fingerprint e a descrição do seu lote. Assim, o suporte será integrado nas próximas versões e você poderá remover o conversor externo.