Comandos
Todas as ações do dispositivo passam pelo registo COMMAND (0x0060, u8) — no Modbus, holding 0x8113 (só de escrita). Uma escrita coloca o opcode em fila; a execução ocorre no ciclo principal do dispositivo (milissegundos na maioria dos comandos; os que tocam na flash demoram mais).
Semântica de conclusão e de resultado
-
Ocupado:
CMD_STATE(0x006A) bit 0 = BUSY enquanto um comando é executado. BUSY é o sinal de conclusão — consulte até 0 antes de ler o resultado. Um novo comando escrito enquanto BUSY está ativo é descartado (bit 1 OVERRUN ativo; o comando em execução não é perturbado; OVERRUN limpa quando o comando seguinte for aceite). No Modbus, uma escrita de COMMAND enquanto ocupado → exceção 06. -
Resultado:
ERROR(0x0002; readback Modbus holding 0x8114) guarda o resultado após a conclusão (0x00 = OK).ERRORlê 0xF0 (Modbus 0xFFFF) durante toda a execução e é escrito em conjunto com a conclusão; julgue a conclusão por BUSY e leia o resultado de ERROR depois. -
Atualidade:
CMD_SEQ(0x0067) incrementa uma vez por comando concluído — consulte-o para distinguir um resultado novo de um antigo. -
Padrão: verifique BUSY = 0 → escreva os parâmetros e depois COMMAND → consulte BUSY → 0 (tempos limite: ≥1 s para comandos simples e gravações, ≥0.5 s para uma escrita de página de atualização, ≥3 s para COMMIT de atualização; em I²C tolere ≥10 ms de clock stretching e repita as leituras com NACK — nunca reenvie às cegas uma escrita de COMMAND) → leia
ERROR. Passo a passo completo: Sequências D2. -
Comandos que reiniciam o módulo (0x02 RESET, 0x13 ACTIVATE, 0x16 ADDR_BY_UID no módulo correspondente): por Modbus a resposta pode ser truncada ou não existir (e um atraso de TX configurado pode suprimi-la); confirme consultando de novo o dispositivo após o reinício.
Códigos de erro (ERROR 0x0002)
| Código | Nome | Significado |
|---|---|---|
| 0x00 | OK | aceite / concluído |
| 0xF0 | PENDING | comando ainda em execução (com BUSY = 1) |
| 0xF6 | NVM_IO | falhou uma escrita persistente (SAVE_CAL / SAVE_CONFIG / importação de histórico) |
| 0xF7 | NO_KEY | certificação recusada — não há chave de dispositivo provisionada |
| 0xF8 | — | operação recusada pela política de assistência |
| 0xF9 | NVM_RATE_LIMIT | reescrita de persistência com limite de frequência (mínimo ~5 s entre gravações) — tente mais tarde |
| 0xFA | OP_RETRY | operação já em curso · recusada no estado atual (p. ex. armazenamento de energia em FAULT, valor de adoção negativo) |
| 0xFB | KEY_GATE | comando com chave sem uma chave válida de uso único (LT_KEY) |
| 0xFC | VALUE_CRC | CRC da página de atualização não coincide (reenvie a página) · época da hora abaixo de 1 600 000 000 · UID não coincide (ADDR_BY_UID) · registo de histórico inexistente (HIST_READ) |
| 0xFD | PARAM | parâmetro / valor de configuração inválido — nada persistido |
| 0xFE | UNKNOWN_CMD | opcode não suportado |
Conjunto de comandos
Comandos da família
| Op | Nome | Efeito |
|---|---|---|
| 0x01 | SAVE_CAL | gravar os registos de calibração (assistência/fábrica; protegido por UNLOCK no Modbus; com limite de frequência → 0xF9) |
| 0x02 | RESET | reinício a quente (protegido por UNLOCK no Modbus; não espere resposta Modbus ou resposta truncada) |
| 0x03 | LATCH_PERIOD | na próxima fronteira de janela, capture o banco selecionado por LATCH_BANK (0..7; ≥ 8 → 0xFD) e reinicie a sua acumulação — bit 8 de capacidade; caso contrário 0xFE |
| 0x04 | SAVE_CONFIG | guarda a configuração (leitura-modificação-escrita; calibração inalterada; não protegido por UNLOCK). Valores validados contra a tabela legal; ilegal → 0xFD, nada guardado; limite de frequência → 0xF9; uma gravação sem alterações é uma operação OK sem efeito (continua a disparar CONFIG_CHANGED) |
| 0x06 | SET_TIME | aplica a época escrita em TIME_SET/RTC_EPOCH; época < 1 600 000 000 → 0xFC; o bit 4 de STATUS fica ativo de imediato |
| 0x07 | ENERGY_RESET | opcode de família, condicionado a UNLOCK. Não utilizado (0xFE / exceção 03) — a reposição do contador faz-se pelo LT_RESET com chave descrito abaixo |
| 0x0E | IDENTIFY | faz piscar os LED durante 10 s — localize o módulo num armário. Não condicionado |
| 0x0F | ATTEST | assine o desafio de 32 B em 0x0B80 (mapa de registos); ~55 ms; 0xF7 = sem chave |
| 0x10 | OTA_BEGIN | abrir uma sessão de atualização (Atualização de firmware) |
| 0x11 | OTA_BLOCK_WR | programar uma página de 256 B (limitada a uma página / ~250 ms — BUSY até chegar a sua vez) |
| 0x12 | OTA_COMMIT | verificar + armar a imagem preparada (sem reinício); consultar BUSY ≥ 3 s |
| 0x13 | OTA_ACTIVATE | reinício para a imagem armada (apenas quando OTA_STATUS = 2; ~4 s até reaparecer) |
| 0x14 | FW_ABORT | fechar a sessão de atualização / desarmar uma imagem armada |
| 0x15 | — | reservado (fábrica/assistência) |
| 0x16 | ADDR_BY_UID | o módulo cujo UID coincide com ADDR_UID recebe o(s) endereço(s) preparado(s), grava-os juntamente com quaisquer outras alterações CFG_ pendentes e reinicia; os outros módulos respondem 0xFC. Ambos os campos de novo endereço a zero → 0xFD; endereço inválido → 0xFD; limite de frequência de gravação → 0xF9. Funciona num broadcast Modbus. Não protegido |
Comandos com chave (contadores de vida útil e histórico)
Estes comandos alteram o estado relevante para a medição, por isso cada um exige que a chave de uso único correspondente seja escrita em LT_KEY (0x0844 / Modbus holding 0x8142–43, palavra alta primeiro) imediatamente antes do comando. A chave é consumida por qualquer comando seguinte; chave errada ou ausente → ERROR 0xFB. Esta é uma proteção de ação deliberada, acima do transporte (não é o UNLOCK do Modbus).
| Op | Nome | Chave (u32) | Efeito |
|---|---|---|---|
| 0x08 | HIST_READ | — (sem chave) | carregue o registo selecionado por HIST_PERIOD/HIST_BACK em HIST_REC; sem tal registo → 0xFC |
| 0x09 | HIST_FLUSH | — (sem chave) | libertar a energia agora: sempre a cópia de retenção; o registo NVM só se tiverem passado ≥ 10 s desde a sua última escrita (também implicado por RESET e ativação de atualização) |
| 0x0A | LT_RESET | 0x4C545253 "LTRS" |
põe a zero a energia de vida; contador de geração ++ (registado). Falha do armazenamento → 0xFA |
| 0x0B | LT_ADOPT | 0x4C544150 "LTAP" |
adotar os valores de contador em preparação (substituição de placa / migração); geração ++ (registado). Ordem de preparação: importação Wh · exportação Wh · importação reativa varh · exportação reativa varh (4×i64); um valor negativo → 0xFA |
| 0x0C | HIST_WRITE | 0x48494D50 "HIMP" |
importa o registo de 80 B em HIST_REC para o anel horário (HIST_PERIOD tem de ser 1, senão 0xFC); marca temporal não mais recente → 0xFD; erro de E/S NVM → 0xF6 |
| 0x0D | HIST_CLEAR | 0x48434C52 "HCLR" |
apagamento passo a passo do anel horário; repetir enquanto estiver a correr → 0xFA (registado) |
Reposições de vida útil, adoções e escritas de histórico ficam registadas no registo de eventos com valores antes/depois — não podem acontecer em silêncio.
Resumo das proteções
| Mecanismo | Âmbito | Como |
|---|---|---|
| UNLOCK Modbus | 0x01 · 0x02 · 0x07 · 0x10 · 0x12 · 0x13 · 0x14 · 0x15 | chave 0xA5C3 → holding 0x8112; janela de 10 s, um comando; pode partilhar um FC16 com o opcode (Modbus) |
| LT_KEY | 0x0A–0x0D, ambos os transportes | magia por comando, uso único |
| Lista de permissões de broadcast | Unidade Modbus 0 | apenas definição da hora, instantâneo, endereçamento por UID (Modbus) |
Não protegidos em nenhum transporte: 0x04, 0x06, 0x08, 0x09, 0x0E, 0x0F, 0x11, 0x16. O I²C não tem passo UNLOCK: o acesso físico ao barramento I²C da placa é a fronteira de confiança da instalação; os comandos protegidos estão protegidos em ambos os transportes.