rbAmp
PT
Loja
Docs
Atualizado a · Editar no GitHub (Edit on GitHub)

11 · Registo de alterações

Este capítulo espelha CHANGELOG.md na raiz do repositório. As versões públicas retomam com a versão 1.7.2; as versões intermédias foram lançadas apenas internamente.

1.7.3 — A energia STD fica nos contadores, modelos de pinça de 100 A e 50 A, mensagem de módulo bloqueado (2026-11-01)

Fixo

  • Os módulos STD que reportam ambos os bancos de instantâneos (bit de capacidade 8) e contadores de energia no próprio dispositivo (bit 13), como a imagem de módulo 0x0001007E: a energia e as chamadas de período passam a usar os contadores persistidos. Antes, um módulo deste tipo era comutado para o banco 0 integrado no anfitrião sem qualquer aviso. As chamadas aos bancos de instantâneos (rbamp_std_arm_banks, rbamp_std_latch, rbamp_std_read_latch) são uma ferramenta separada que depende apenas do bit 8 e funcionam nestes módulos como antes. rbamp_std_info_t.period_source indica a fonte efetivamente usada.

Adicionado

  • README: secção "linha STD" com a versão mínima de componente para a imagem de módulo 0x0001007E e as chamadas de banco de instantâneos.

  • O exemplo std_meter arma o seu próprio banco 1 em cada módulo que reporta bancos de instantâneos, também quando a energia vem dos contadores.

  • Nome do firmware para o REG_VERSION BASIC 0x0E: rbamp_basic_fw_name() devolve "1.4.22" (todas as variantes BASIC).

  • Registo de modelos de sensor: os modelos de pinça 2000:1 códigos 11 (50 A) e 13 (100 A) são agora modelos caracterizados (classificados em 50.0 A / 100.0 A, fundo de escala 62.5 A / 116.5 A, pico 88.4 A / 164.7 A). O código 12 (80 A) mantém-se para módulos já associados a ele.

Alterado

  • rbamp_set_ct_model_ch_force() num módulo BASIC de classe 2 ou 3 devolve ESP_ERR_INVALID_STATE com uma linha de registo que indica a configuração bloqueada quando o módulo recusa a escrita (o firmware 1.4.22 e posteriores recusa escritas de classe e modelo num módulo emparelhado de fábrica fora do modo de manutenção). Antes, a recusa aparecia como um erro genérico de parâmetro. O caminho de força só funciona nesse módulo no modo de manutenção.

1.7.2 — Correção do calibre SCT-013, retoma após paragem do mestre, leituras de janela numa transação (2026-10-21)

Primeiro lançamento público desde a 1.5.0. Inclui 1.6.0 – 1.7.2 em conjunto: a linha de módulos STD atrás do mesmo handle, a linha data-ready, eventos, energia em µWh e grandezas de fase, uma contagem de canais que acompanha o módulo (1, 2, 3, 5 ou 7), o registo de modelos de sensor com limites de corte, leituras de janela em uma transação, retoma após uma falha do mestre, e a correção do calibre SCT-013 para os módulos de linha de corrente cujo firmware mantém a calibração de 30 A (o firmware que reporta a capacidade de autocorreção corrige-se a si próprio). A validação em hardware desta linha foi feita num anfitrião com ESP-IDF 5.4.1.

Adicionado

  • SCT-013-060 e -100 são aceites (antes eram recusados do lado do cliente por estarem reservados); os limites de corte do modelo de sensor foram atualizados para os valores medidos.
  • Troca de calibre SCT-013: um módulo de sensor de corrente da classe 1 é calibrado com o sensor de 30 A, e o firmware até 1.4.19 mantém essa calibração depois de o utilizador associar outro modelo. A biblioteca passa a ler o ganho que o módulo aplica em rbamp_begin(), após uma escrita de modelo e após cada reinício detetado do módulo, e escala a corrente, o pico de corrente, a potência real, a potência média do período, a energia que integra, o digest e os limiares de evento para o modelo selecionado. Tensão e fator de potência não são escalados. rbamp_sct_correction() reporta o resultado por canal (rbamp_sct_correction_t: estado, modelo, escala, ganho aplicado) e rbamp_sct_refresh() reavalia sob pedido. Um ganho que ainda seja igual à predefinição bruta (modelo trocado neste arranque sem reinício) dispara um CMD_RESET; um ganho aplicado inesperado, um modelo desconhecido, ou uma predefinição bruta que sobreviva ao reset deixam as leituras sem escala com um aviso. Um módulo que reporta a capacidade de autocorreção (firmware 1.4.20 e posteriores) corrige-se a si próprio e fica com escala 1 — detetado pela capacidade, nunca pela VERSION. CONFIG_RBAMP_SCT_RATING_CORRECTION (por defeito ativo) desliga o mecanismo.

  • rbamp_begin_resume() — rbamp_begin() sem a preparação do latch. Um módulo BASIC continua a fazer a média até ao próximo latch, por isso após um reinício ou uma interrupção do master o primeiro instantâneo consumido integra sobre a janela do próprio módulo e recupera a energia do tempo de inatividade. Os instantâneos seguintes usam o relógio do master como antes. Os módulos STD comportam-se exatamente como com rbamp_begin().

  • rbamp_period_snapshot_t: module_window_ms (a duração própria do módulo para a janela com latch, 0 no STD; o módulo conta commits de 100 ms no firmware atual e de 200 ms no firmware anterior à v1.2 — a biblioteca percebe qual pelo próprio instantâneo e reporta-o em module_commit_ms), module_uptime_s, window_from_boot (a janela começou no arranque do módulo: um reinício, ou o primeiro latch desde o arranque) e window_long (mais de 6 h, onde a média do módulo perde precisão). No primeiro instantâneo após rbamp_begin_resume(), module_restarted = window_from_boot.

  • rbamp_read_uptime_s() — segundos desde o arranque do módulo (BASIC e STD). Lê 0 no firmware BASIC que não o publica; nesse caso window_from_boot fica a false.

  • rbamp_read_digest() — uma janela de um módulo BASIC numa só transação: estado, sequência da janela e os campos escolhidos (corrente, tensão, potência real com sinal em watts inteiros, fator de potência) para os canais 0-2. Feita para ler cada janela publicada na linha de pronto. rbamp_set_digest_fields() escolhe os campos; a biblioteca escreve a escolha no módulo e volta a escrevê-la após um reinício detetado do módulo. Requer firmware BASIC com a capacidade de digest; não disponível no STD.

  • rbamp_basic_fw_name() — o nome da versão de firmware para um byte de versão BASIC ("1.4.19" para 0x0B, e assim por diante).

  • rbamp_read_sensor_class() — a classe de sensor atual do módulo.

  • rbamp_sensor_model_limits() — a corrente RMS nominal de um modelo de sensor, a corrente RMS a que uma sinusoide começa a cortar, e o teto instantâneo de corte, em A, a partir do registo de modelos gerado (0 quando desconhecido). rbamp_sensor_model_rated_a() é a forma abreviada da corrente nominal; note que a classificação pode diferir dos amperes no nome do modelo.

  • O registo gerado de modelos de sensor foi atualizado com esses limites.

  • rbamp_set_ct_model_ch_force() — caminho de assistência que define o modelo de um canal independentemente da classe e do modelo atual do módulo. Substitui a calibração que a unidade tem para esse canal pela predefinição genérica do modelo; siga-a com uma calibração.

Alterado

  • rbamp_set_ct_model(), rbamp_set_ct_model_ch() e rbamp_configure_channels() num módulo de classe 1 sem a capacidade de autocorreção (firmware até 1.4.19) terminam com um reinício do módulo (CMD_RESET, o mesmo UID verificado, cerca de um segundo): a única forma de o módulo voltar ao seu ganho calibrado após uma escrita de modelo. A biblioteca reaplica o que lhe pertence (latch de primeira amostra, máscara de digest na próxima utilização); os acumuladores de período recomeçam como após qualquer reinício do módulo.

  • O transporte já não chama i2c_master_bus_reset() por conta própria antes da última tentativa de uma transação falhada. O driver já reinicia a sua máquina de estados após cada transação falhada, e a reposição explícita não toma o bloqueio do barramento: quando outra tarefa tem uma transação em curso, emite um STOP nos pinos vivos, que o manipulador de interrupções do driver pode tomar pelo fim de uma leitura e bloquear na ISR (visto num host com um módulo ligado a quente). CONFIG_RBAMP_BUS_RESET_ON_RETRY_EXHAUSTION restaura o comportamento antigo para um master de tarefa única.

  • rbamp_set_sensor_class(), rbamp_set_ct_model(), rbamp_set_ct_model_ch() e rbamp_configure_channels() leem antes de escrever. Uma classe ou modelo que o módulo já tem não é reescrita (sem escrita no barramento): no módulo, uma escrita de classe limpa os modelos de TC mesmo quando o valor não muda, e uma escrita de modelo reaplica a predefinição genérica por cima da calibração própria da unidade mesmo quando o modelo não muda; por isso reaplicar uma configuração guardada a cada reconexão costumava degradar as leituras. Um módulo de classe 2 ou 3 (fornecido e calibrado juntamente com o seu sensor) não é reconfigurado: ESP_ERR_INVALID_STATE. rbamp_configure_channels() decide todo o pedido antes da primeira escrita, por isso, num módulo assim, nada fica meio aplicado.

  • Documentação de latch_ms: apenas diagnóstico, pode ler valores curtos sob carga; a janela de integração de energia é master_dt_ms ou module_window_ms.

  • A documentação e a ajuda do Kconfig indicam agora que a janela de publicação do módulo é de 100 ms em toda a família (imagens antigas: 200 ms). A estabilização de 300 ms que a biblioteca aplica após um latch STD é descrita como o limite superior seguro que é. Nenhum comportamento temporal mudou.

Fixo

  • rbamp_read_all() / rbamp_read_all_ready() num módulo com mais de três canais (UI5/UI7, BASIC ou STD) escreviam os canais 3+ para além dos arrays de três entradas de rbamp_snapshot_t: frequency, topology e channels eram sobrescritos (o host via então channels = 0) e o último canal caía quatro bytes para além da estrutura, na pilha do chamador. A chamada passa a preencher apenas ch0-2 (RBAMP_SNAPSHOT_CHANNELS), exatamente como o instantâneo de período; os ch3+ ficam em rbamp_read_channel() / rbamp_read_all_channels(). Encontrado num host com um módulo de 7 canais. Uma simulação no host de todo o componente, contra uma imagem de registos falsa, executa agora read_all para 1/3/5/7 canais com palavras-guarda depois da estrutura.

1.7.1 — A contagem de canais acompanha o módulo (2026-10-18)

Fixo

  • O rbamp_new() criava um handle cujo número de canais estava fixo em três, por isso um módulo de canal único (UI1, I1) continuava a reportar três canais após rbamp_begin(). O construtor por omissão passa agora a adotar o número de canais e a presença de tensão a partir do registo de variante do módulo; três canais continuam a ser apenas o valor de recurso para firmware que não publica a variante. rbamp_new_with_topology() continua a fixar o número como antes (regista-se um aviso quando o módulo discorda). Reportado a partir de um host com um UI1; validado aí: um módulo UI1 reporta um canal e a variante UI1 após rbamp_begin().

  • rbamp_read_variant() na linha BASIC devolvia UNKNOWN para os códigos UI5 / UI7; agora mapeia todos os códigos conhecidos.

Adicionado

  • rbamp_variant_t rbamp_variant(rbamp_handle_t dev) — a variante em cache estabelecida por rbamp_begin(), sem tráfego no barramento. RBAMP_VARIANT_UNKNOWN antes de rbamp_begin() ou quando o módulo não publica a sua variante.

  • Testes unitários em anfitrião para a política de variantes dos dois construtores (test/host/test_std_decode.c).

1.7.0 — energia em µWh, corrente de arranque, ângulos de fase e sequência (2026-10-17)

Suporte para a versão de imagem de módulo 0x0001007A / 0x0001007B. Cada acrescento depende do que o módulo reporta; os módulos antigos comportam-se exatamente como antes.

Validado em módulos STD com versão de imagem de módulo 0x0001007B numa aplicação de anfitrião: obtenção/definição da corrente de arranque e releitura, ângulos de fase e sequência de fases num módulo trifásico, flags de energia fina, delta de energia através de reinícios de módulo.

Adicionado

  • Energia com resolução em µWh / µvarh em rbamp_std_energy_t: act_import_uwh, act_export_uwh, act_net_uwh, rea_import_uvarh, rea_export_uvarh, ch_import_uwh[], ch_export_uwh[], além de fine / fine_reactive. Os campos são preenchidos em todos os módulos: a partir dos contadores µ do próprio módulo quando os publica (versão de imagem 0x0001007A; reativa a partir de 0x0001007B), caso contrário escalados a partir dos contadores grossos com fine a false — quem chama pode usar os campos µ sem condições. Lidos como instantâneos coerentes (uma transação por bloco). rbamp_std_energy_delta aplica as mesmas regras (mudança de geração → sem delta, queda de tempo de atividade = reinício, contador abaixo da leitura anterior → 0, líquido = importação − exportação). rbamp_read_period_snapshot no caminho de contadores usa a diferença em µWh quando disponível.

  • Corrente de arranque para energia: rbamp_std_get_start_current / rbamp_std_set_start_current (µA; 0 = desligado; um valor fora do conjunto aceite pelo módulo → ESP_ERR_INVALID_ARG sem escrita no barramento; lido de volta e confirmado; rbamp_save_user_config persiste-o). Abaixo desta corrente do canal o módulo não contabiliza energia; as leituras não são afetadas. Também em rbamp_std_config_t (start_ua, start_ua_supported). ESP_ERR_NOT_SUPPORTED sem tráfego no barramento antes da versão de imagem de módulo 0x0001007B.

  • Ângulo de fase da tensão: rbamp_std_voltage_t.angle_deg / angle_valid (graus em relação à entrada de tensão 0; versão de imagem do módulo 0x0001007A+, módulos trifásicos; caso contrário angle_valid é false). Mesma leitura numa só rajada que antes.

  • Sequência de fases: rbamp_std_read_phase_seq → rbamp_std_phase_seq_t (RBAMP_STD_PHASE_SEQ_NA / FORWARD / REVERSE / ABNORMAL); ESP_ERR_NOT_SUPPORTED sem tráfego no barramento antes da versão de imagem de módulo 0x0001007A.

  • Teste unitário no host das funções puras de descodificação: test/host/run.sh (gcc, sem ESP-IDF). As regras de delta de energia vivem agora em src/rbamp_std_decode.c.

Alterado

  • rbamp_is_provisioned (linha STD) documenta o marcador de calibração da versão de imagem de módulo 0x0001007A: uma unidade calibrada com um firmware anterior lê false após a atualização, até um rbamp_save_gains.

Nota de atualização

  • A estrutura do instantâneo de energia (rbamp_std_energy_t) ganhou campos nesta versão. Se a sua aplicação o guardar como blob binário bruto (NVS, ficheiro), guarde apenas os campos de que precisa num formato fixo seu; um blob guardado por uma versão antiga não corresponderá ao novo tamanho.

1.6.1 — Conclusão de comandos, leituras coerentes, verificações de sessão OTA (2026-10-11)

Correções no lado da biblioteca a partir da auditoria do firmware/biblioteca de 2026-10-11. Sem API nova; o comportamento das chamadas existentes na linha STD ficou mais rigoroso.

Alterado

  • A conclusão de um comando é o registo de estado de comando do módulo (flag de ocupado limpa e contador de comandos concluídos avançado), nunca apenas o registo de erros; o veredicto só é lido após a conclusão. As gravações (rbamp_save_gains, rbamp_save_user_config), rbamp_std_cal_thd_floor, rbamp_reset, a mudança de endereço e todos os comandos OTA usam-no — sem pausas fixas de estabilização nos módulos que publicam o registo, com timeouts de pelo menos 1 s (3 s para o commit OTA). Um comando escrito enquanto o módulo está ocupado é primeiro aguardado; um comando que o módulo descartou (overrun) falha com ESP_ERR_INVALID_STATE em vez de devolver o veredicto do comando anterior.

  • Uma escrita de comando nunca é repetida em caso de erro de transporte (uma retentativa poderia entregar o opcode duas vezes). As leituras e escritas de registos de dados mantêm a retentativa.

  • Leituras de bloco são uma transação — o módulo serve cada leitura a partir de um instantâneo coerente, por isso os contadores de energia, blocos de canal e totais já não se desfasam entre rajadas. rbamp_read_all num módulo STD lê o bloco de tensão e cada bloco de canal inteiro, em vez de campo a campo.

  • OTA: após cada página, a sessão tem de continuar aberta (estado 1); caso contrário, ESP_ERR_INVALID_STATE com o motivo do módulo registado — reinicie a partir de begin. As consultas durante uma paragem da flash já não repõem o barramento. rbamp_std_ota_activate aguarda a janela de teste de ~10 s do módulo e confirma que a imagem em execução é a versão preparada e que a troca deixou de estar pendente. rbamp_std_ota_write_image (imagem não assinada gerada no anfitrião) devolve ESP_ERR_NOT_SUPPORTED antes de tocar no módulo — o firmware do módulo só aceita imagens preparadas pelo fabricante.

  • Alteração de endereço (rbamp_commit_address_change, STD): a gravação da configuração é síncrona (limite de frequência → ESP_ERR_NOT_FINISHED, tente novamente após ~5 s), e o handle só muda para o novo endereço depois de um módulo responder aí; caso contrário, ESP_ERR_NOT_FOUND e o handle mantém o endereço antigo.

  • rbamp_std_read_totals: os campos de energia dos blocos agregados leem 0 (não preenchidos pelo módulo — use rbamp_std_read_energy).

  • rbamp_read_frequency (STD): 0 vindo do módulo significa sem rede → ESP_ERR_INVALID_RESPONSE / NaN (rbamp_read_all assinala-o como implausível).

  • rbamp_is_provisioned (STD): documentado como fiável a partir da versão de imagem de módulo 0x00010079 (as imagens mais antigas reportam também calibração válida com ganhos predefinidos).

1.6.0 — linha de módulos STD, linha data-ready, eventos (2026-10-11)

Adicionado

  • Linha de módulos STD (mapa de registos de 16 bits) atrás do mesmo handle e API da linha original: rbamp_std_probe / rbamp_std_identify / rbamp_std_info, leituras em tempo real por canal incl. potência reativa e aparente (rbamp_read_reactive_power, rbamp_read_apparent_power, rbamp_std_read_channel, rbamp_std_read_voltage), totais por fase e globais (rbamp_std_read_totals), configuração e harmónicos (rbamp_std_read_config, rbamp_std_set_harmonics, rbamp_std_cal_thd_floor).

  • Energia em módulos sem bancos de instantâneos: a fonte do período é escolhida a partir das capacidades do módulo em rbamp_begin (rbamp_std_info_t.period_source); a energia do período é a diferença de duas leituras dos contadores persistentes, com regras de reinício e de reposição de contadores. rbamp_std_read_energy (Wh / varh, mais mWh por canal e por grupo no mapa 0x36+), rbamp_std_energy_delta, rbamp_energy_add_wh, RBAMP_ENERGY_CH_TOTAL. rbamp_period_snapshot_t passou a ter avg_p_total, wh_net e module_restarted.

  • Bancos de latch nos módulos que os têm: rbamp_std_arm_banks, rbamp_std_latch, rbamp_std_read_latch, rbamp_std_latch_wh.

  • Relógio do módulo, histórico e registo de eventos: rbamp_std_set_time, rbamp_std_read_time, rbamp_std_read_image_version, rbamp_std_hist_info, rbamp_std_hist_read, rbamp_std_hist_read_raw, rbamp_std_event_read, rbamp_std_hist_flush (o anel horário é persistente; o registo de 15 minutos é apenas o último).

  • Saúde: rbamp_std_read_health estendido com bits de estado, fontes de vida e calibração, contadores de tramas, tempo de atividade, e causa de reinício + contagem de arranques (versão de imagem de módulo 0x00010076 e posteriores, RBAMP_STD_RST_*).

  • Comandos e serviço: rbamp_std_command, rbamp_std_wait_idle, rbamp_std_locate, rbamp_std_read_board_id, rbamp_std_ota_board_ok (verificação da placa antes de um fluxo OTA), rbamp_std_set_address_by_uid.

  • OTA: atualização de imagem em banco duplo, incluindo imagens assinadas preparadas (rbamp_std_ota_begin … rbamp_std_ota_activate, rbamp_std_ota_write_prepared, rbamp_std_ota_write_prepared_pair, rbamp_std_ota_diag, rbamp_std_ota_staged_version, rbamp_std_ota_abort).

  • Certificado e atestação: rbamp_std_read_certificate, rbamp_std_attest (a verificação da assinatura é feita pela aplicação).

  • Linha de dados prontos (DRDY), ambas as linhas de módulos: rbamp_set_drdy_gpio, rbamp_wait_data_ready, rbamp_read_all_ready, rbamp_read_data_seq. Uma linha de dreno aberto pode ser partilhada por vários módulos; a biblioteca verifica a sequência de publicação, conta janelas perdidas, reporta a latência e deteta uma linha retida em LOW (alarme). Alternativa por sondagem via CONFIG_RBAMP_DRDY_POLL_MS. Os módulos STD precisam de versão de imagem 0x00010075 ou posterior.

  • Eventos nas duas linhas: rbamp_read_event_mask, rbamp_set_event_mask, rbamp_set_event_thresholds, rbamp_begin_event_flags, RBAMP_EVENT_NVM_FAULT; rbamp_read_event_flags / rbamp_clear_event_flags / rbamp_has_error / rbamp_clear_error passam agora a cobrir a linha STD.

  • Kconfig: RBAMP_I2C_SCL_WAIT_US (orçamento de clock-stretch, por defeito 10 ms) e RBAMP_DRDY_POLL_MS.

  • Exemplo std_meter.

Alterado

  • As chamadas de período em módulos sem bancos de instantâneos devolvem ESP_ERR_NOT_SUPPORTED em vez de reportar silenciosamente um período inválido.

  • rbamp_set_ct_model_ch devolve ESP_ERR_NOT_SUPPORTED em módulos STD cujo mapa de canais não é gravável.

  • rbamp_err_to_str cobre ESP_ERR_NOT_FOUND, ESP_ERR_NOT_FINISHED e ESP_ERR_INVALID_CRC.

  • rbamp_period_snapshot_t e rbamp_std_health_t ganharam campos (compatível com o código-fonte; recompile os dependentes).

  • O componente passa a exigir esp_driver_gpio (componente incorporado do IDF).

1.5.0 — Modelo de TC por canal em todos os canais (2026-09-04)

Adicionado

  • rbamp_set_ct_model_ch / rbamp_read_ct_model_ch / rbamp_configure_channels aceitam qualquer canal até ao número de canais detetado (canais 3+ através da janela de canais).

  • Os códigos de modelo e os descritores vêm do rbamp_sensor_models.h gerado (rbamp_sensor_model_lookup); os códigos desconhecidos são rejeitados pelo módulo e devolvidos ao chamador.

Fixo

  • A classe de sensor e o modelo de TC passam a persistir nos módulos de produção: a gravação anterior não persistia em flash no firmware de produção, pelo que a associação ficava apenas em RAM e perdia-se no reinício seguinte. Sem alteração na API; o mesmo tempo de estabilização de ~700 ms.

1.4.0 — Módulos de cinco e sete canais

Adicionado

  • Topologia FIVE_CH / SEVEN_CH, variantes UI5 / UI7, RBAMP_MAX_CHANNELS = 7; rbamp_read_channel, rbamp_read_all_channels, rbamp_read_commit_seq. O instantâneo de período integra todos os canais.

1.3.0 (2026-06-16) — Versão pública

Primeira versão pública do componente rbamp para ESP-IDF v5.x.

Principais funcionalidades

  • Gestor de frota: gere um grupo de módulos num único barramento I²C através de um único handle rbamp_fleet_t. Descoberta com deteção de conflitos e canário de bloqueio de Nível 2, _poll_all resistente a falhas (MISS), agregação de potência total / energia total / erros, difusão de latch para sincronismo apertado. Ver o capítulo 09 · Referência da API, secção "Gestor de frota".

  • Provisionamento: rbamp_provision — um fluxo de chamada única para reatribuir um módulo virgem ao seu endereço de trabalho, com gravação opcional da configuração na flash. Disciplina: um virgem de cada vez no barramento (um DEVE normativo).

  • Configuração multicanal: rbamp_configure_channels — configuração atómica por canal dos modelos de CT numa única operação, com um único ciclo final de escrita em flash (amigável para a flash).

  • Modelo de erro v1.3: separa o resultado da última escrita (REG_ERROR (0x02) — canal síncrono, validado pelos setters) do sinal assíncrono durável (EVENT_FLAGS.bit3 — pegajoso, para factos em tempo de execução). As funções correspondentes são rbamp_read_last_error, rbamp_has_error, rbamp_clear_error, rbamp_read_event_flags.

  • Identidade / deteção de funcionalidades: rbamp_read_variant, rbamp_read_capability (mapa de funcionalidades), rbamp_has_voltage, rbamp_read_product_id, rbamp_read_uid, rbamp_is_provisioned.

Cânone refletido na documentação

  • A topologia multi-módulo é o modo de funcionamento principal da biblioteca. O cenário "um módulo no barramento" é o caso mínimo, não o canónico. A implementação canónica é um módulo de rede na entrada de serviço mais N módulos em cargas individuais, todos num único barramento I²C sob um só handle de frota.

  • SKUs suportados no hardware atual: UI1 (contador da rede: tensão + corrente + potência + PF + energia), I1 / I2 / I3 (submedidores: apenas corrente, por canal). UI2 / UI3 seguem em firmware posterior.

  • A energia e a potência só são calculadas nas variantes UI (que têm front-end de tensão). Nas variantes I, rbamp_read_power / _power_factor devolvem 0.0f; a agregação da frota de potência total / energia soma corretamente e ignora as contribuições nulas.

  • A associação de TC é apenas preparação (cânone v1.3): escrever REG_CT_MODEL NÃO aplica o valor automaticamente; a associação é feita pelo CMD_SET_CT_MODEL_CHn por canal. A ordem de associação é arbitrária (as anacronias de "ordem ascendente/descendente" anteriores à v1.3 foram removidas).

  • A alteração de endereço é compatível com produção: commit em duas fases + magic + reinício funciona em produção (não é preciso modo de fábrica).

  • Relógio de parede do master = base de tempo canónica para Wh: o temporizador de software do chip PERIOD_LATCH_MS (0xEC) é apenas de diagnóstico; não o use para energia. O master usa o seu próprio esp_timer_get_time() ou relógio de parede.

Documentação — capítulos novos / reformulados

  • 01_overview — introdução reformulada para ser primeiro multi-módulo; acrescentado um diagrama ASCII do cenário dos 80%.

  • 03_sensor_selection — varrimento da ordem dos TC; nova secção "Módulos multicanal — I2 e I3 (apenas corrente)" com um padrão de desagregação UI1+I3.

  • 04_hardware — a secção "Barramento multi-módulo — topologia principal" promovida a modo de funcionamento principal; requisito explícito de pull-ups externos de ~4.7 kΩ no barramento da frota; fluxo de provisionamento via rbamp_provision.

  • 09_api_reference — secções acrescentadas: "Identificação e provisionamento", "Modelo de erros v1.3", "Configuração multicanal", "Gestor de frota — gerir vários módulos", "Configuração de frota por dispositivo".

  • 10_troubleshooting — secções acrescentadas "IDF i2c_master bloqueia num barramento marginal — mitigação em três camadas" (com uma tabela de taxas de bloqueio validada em HW), "Frota: um módulo acabou excluído", "Frota: rbamp_fleet_scan devolveu INVALID_STATE", "Frota: rbamp_provision devolveu um erro".

  • 11_changelog — este ficheiro.


Fonte e problemas: rb-amp/rbamp-esp-idf · esta página no repositório: docs/11_changelog.md (v1.7.3)