Sensores e unidades

O RBgrid mede através de duas camadas:

• Sensores — os canais físicos que o hub consegue ver. Numa versão v1.1.x do hub, são os canais dos módulos I²C rbAmp: uma entrada de tensão e um ou mais canais de corrente por módulo. Não existe ADC integrado; os módulos medem e o hub lê-os por I²C.
• Unidades — os pontos de medição que cria ao associar um canal. Uma unidade tem a sua própria identidade, nome, função, estatísticas e histórico. Mover uma unidade para outro canal (rebind) mantém o seu id, nome, histórico e posição no histórico.

Não escreve código nenhum para acrescentar um sensor ou uma unidade. Os canais aparecem sozinhos quando um módulo é ligado; transforma um canal numa unidade a partir da aplicação web ou da API REST, em tempo de execução.

Sensores — os canais físicos

Cada canal de um módulo ligado aparece na lista, esteja ou não em uso. Um canal que não está associado a uma unidade está simplesmente free: não produz dados, não é somado e não gera alertas. Um módulo pode ser usado com qualquer subconjunto dos seus canais, por qualquer ordem.

Cada canal tem:

• ch_label — o canal tal como impresso na caixa do módulo: I0, I1, … para canais de corrente (numerados a partir de 0), V para a entrada de tensão do módulo, e L1–L3 num módulo sensível à fase.
• Modelo do CT — para um canal de corrente, o modelo do transformador de corrente em uso (ct_code / ct_name legível, por exemplo SCT-013-050, 50 A; ct_name fica de fora quando o modelo é desconhecido) e os limites do módulo para ele. Na aplicação, corresponde ao Current sensor do ponto. Num módulo que aceita um CT de pinça à sua escolha, define o modelo (veja Escolher o modelo do CT abaixo); num módulo cujo CT vem emparelhado com o canal de fábrica, o modelo é fixo.
• Estado da correção — se o módulo aplicou a sua correção para o modelo de CT escolhido. Se não o fez (readings not corrected), a interface mostra um aviso e o motivo (o canal não está calibrado · o seu ganho não corresponde ao modelo de CT · o módulo não conhece este modelo de CT). Enquanto a correção não for aplicada, as leituras podem diferir das reais.

Os próprios módulos vêm da configuração de módulos do hub; um módulo no endereço predefinido (0x50) é encontrado sem qualquer configuração (veja Get started). As famílias de módulos rbAmp, a sua composição de canais e a gama de CT estão documentadas com os módulos — veja a rbAmp module docs.

Unidades — os pontos de medição

Uma unidade é criada ao associar um canal a um ponto. Tem:

Na aplicação, as funções têm os nomes Appliance, Load, Breaker, Generation, Storage, Charging station, Heating/cooling, Smart appliance, e, para as funções de alimentação, Grid input e Backup input.

Duas unidades são unidades de alimentação especiais — a alimentação principal (a ligação à rede) e uma alimentação alternativa opcional (geração interna). A aplicação nunca oferece as funções de alimentação ao associar e não permite alterá-las, e o hub bloqueia ambas: um patch que toque em qualquer função de alimentação é recusado (HTTP 409). Estas transportam o controlo económico do local. O barramento de tensão (a entrada V do módulo) e a entrada principal não podem ser eliminados.

Configurar em tempo de execução — aplicação web ou REST

Tudo é configurado no hub em funcionamento. Nada é definido em código C.

Aplicação web — Points → Free sensors → Bind transforma um canal livre numa unidade; os campos da unidade são editados nas suas definições.

REST — as mesmas operações estão disponíveis por HTTP:

As operações de escrita usam o admin token do hub quando existe um; defina-o com POST /api/system/token e envie-o nas escritas; é recomendado. Até definir um token, as escritas ficam abertas na rede local.

Associar um canal, por exemplo:

POST /api/v1/units
{
  "sensor": { "iface": "i2c", "bus": 0, "module": 0, "ch": 1 },
  "name": "Kitchen", "point": "kitchen",
  "role": "ZONE_LOAD", "stat_class": "1HOUR", "location": "ground floor"
}

A resposta devolve o novo unit_id. Os novos ids são atribuídos a partir de 0100 para cima. Mudar o nome de um ponto retira o slug antigo, para que um sistema externo não passe a obter silenciosamente um ponto diferente com a mesma chave.

Eliminar (ou desassociar) uma unidade apaga o seu histórico guardado para sempre; o seu canal volta a ficar livre. O ID de um ponto removido pode ser reutilizado de propósito: a aplicação oferece-o ao associar (Bind with the previous ID). O hub começa então o histórico do zero, mas o Home Assistant e o MQTT continuam a série antiga como um único ponto.

Parâmetros como name, role, phase, rated_power_w, max_current_a e o modelo do CT são alterados em tempo real através do endpoint de patch e mantêm-se após um reinício. A referência completa dos campos está na units & sensors API.

Escolher o modelo do CT

Num canal cujo módulo aceita um CT de pinça à sua escolha (série SCT), defina o modelo do CT como a pinça realmente instalada: o Current sensor do ponto nas suas definições, ou ct_code através do endpoint de patch. O modelo é gravado no módulo juntamente com a sua calibração de tipo, e fica associado à identidade desse módulo, por isso outro módulo no mesmo slot mantém o seu próprio modelo guardado.

Altere-o apenas se estiver realmente instalada uma pinça diferente. Gravar o modelo substitui a calibração de fábrica do canal, e essa calibração não pode ser restaurada. Num canal emparelhado de fábrica (série CT), o modelo é fixo: o hub recusa a alteração. Num módulo não calibrado, o modelo não pode ser escolhido.

Fase

phase indica a que linha de alimentação pertence um canal. Numa alimentação monofásica, todos os canais usam o predefinido (1P / L1). Alimentações monofásicas e trifásicas são suportadas. A potência e a energia monofásicas são validadas em hardware. A potência e a energia trifásicas também são verificadas em hardware, com as três entradas de tensão numa mesma fase de bancada; a rede trifásica real a 120° não esteve na bancada. Uma entrada trifásica é um único STD-U3I3, e o cartão do módulo é onde escolhe se a entrada é medida como um ponto com as fases líquidas ou como um ponto por fase, cada fase com a sua própria importação e exportação. Os sistemas de alimentação validados no seu hub estão listados em GET /api/v1/schema → enums.grid_system_validated.

phase é apenas um rótulo. O hub nunca multiplica nem divide os valores de uma unidade pelo número de fases: uma unidade com um transformador de corrente reporta o que esse único condutor transporta, seja qual for o seu phase. Uma unidade definida como 3 phases numa carga trifásica é a energia medida de uma perna — não a divida nem a multiplique por três.

Estatísticas

Cada unidade mantém dados de 3 segundos e de 15 minutos apenas em RAM; não têm histórico guardado. O histórico guardado começa ao nível horário: o hub guarda registos horários na sua própria flash, que sobrevivem a um reinício, e constrói dias, semanas, meses e anos a partir deles. É igual para todas as unidades, seja qual for o seu stat_class. O histórico é mantido para até 12 unidades; as unidades além das doze mostram apenas valores em tempo real. Uma unidade acrescentada enquanto o hub está a correr começa o seu histórico após o reinício seguinte. Os totais de energia acumulada desde sempre são guardados separadamente do histórico.

Quando um canal está perto do limite

Um ponto assinala o seu estado no cartão da Overview, em Load lines, na tabela de pontos e em Needs attention; a página do ponto mostra um alerta:

• clipping — a corrente atingiu o ponto de corte do sensor (a sua corrente de escala completa, que está acima do seu valor nominal). Acima dele, a leitura é subcontada, e o módulo não o consegue detetar por si. As definições do ponto também avisam antecipadamente quando o disjuntor da linha está acima do limite do sensor, e as linhas do History assinalam o clipping.
• sensor limit — a corrente está perto da corrente de corte do sensor: o hub assinala-a a cerca de 90 % dessa corrente. Para pinças SCT-013, a corrente de corte é cerca de 116 % do valor nominal (58 A num SCT-013-050), por isso o aviso surge a cerca de 104 % do valor nominal (52 A). Até à corrente de corte, as leituras estão corretas. Os sensores próprios dos módulos STD não têm estes avisos; leem corretamente até cerca de 130 % do seu valor nominal.
• Um CT invertido num módulo BASIC: o ponto mostra sensor reversed — not metered. Um módulo BASIC mede apenas o fluxo no sentido direto, por isso a carga não é medida até rodar a pinça.

O registo de eventos recebe uma linha quando o estado muda: "near its limit", "clipping" ou "back within range". Apenas clipping marca o registo da hora (uma marca de qualidade para fora de gama); "near its limit" fica apenas no registo. Veja The Overview e Points para saber onde estes aparecem.