Documentação

Contadores definidos pelo utilizador

Nota: O cFos Charging Manager pode ler a maioria dos inversores solares usando SunSpec (tipo de dispositivo "SunSpec Solar Inverter / Medidor"). Neste caso, não precisa de criar a sua própria definição de contador.

O Gestor de Carregamento cFos permite-lhe criar as suas próprias definições de contadores para suportar contadores que não se encontram no repertório padrão. Existem actualmente três tipos: Contadores Modbus, contadores HTTP/JSON e contadores MQTT/JSON. Os ficheiros de definição para estes contadores são muito semelhantes. Os contadores Modbus lêem os seus dados via Modbus a partir de registos específicos, enquanto os contadores HTTP/JSON vão buscar os seus dados via pedido HTTP e analisam JSON como resposta. Para os contadores MQTT/JSON, o cFos Charging Manager subscreve os tópicos MQTT e as mensagens de parses publicadas sob o tópico como JSON. Para a análise, o Gestor de Carregamento cFos utiliza uma pequena "linguagem de consulta". Aqui está a documentação das capacidades do MQTT no Gestor de Carregamento cFos.

Além de um número de variáveis predefinidas, tais como corrente e tensão, os contadores definidos pelo utilizador também podem ler em variáveis desconhecidas definidas pelo utilizador, consultar entradas e definir saídas. A leitura em variáveis e a definição de outputs permite a avaliação de fórmulas. Em combinação com as variáveis do Gestor de Carregamento e os resultados globais do Gestor de Carregamento descritos abaixo, esta é uma característica poderosa e permite mesmo certas tarefas de domótica e o controlo de dispositivos externos, tais como o armazenamento de baterias. Se realizar tarefas de controlo com isto, por favor dê-nos o seu feedback. Estamos muito interessados no que as pessoas controlam com o Gestor de Carregamento cFos e isso ajuda-nos a desenvolver ainda mais o Gestor de Carregamento de acordo com as necessidades do cliente.

Aqui está uma simples definição de exemplo para Modbus que lê um único registo para poder activo. Pode facilmente modificar o número de registo para a sua aplicação específica:
Definição de exemplo para um único registo.

Aqui está uma definição de exemplo para Modbus e uma para HTTP/JSON:
Descarregar definição de amostra para o medidor Modbus
Descarregar definição de amostra para o medidor HTTP/JSON

O Gestor de Carregamento já vem com alguns destes ficheiros, mas pode carregar os seus próprios ficheiros em "Configuração do sistema" e também apagá-los novamente.
Aqui encontrará a maior parte das definições dos contadores que fornecemos:
Descarregar as definições dos contadores fornecidos

Se criou o seu próprio ficheiro de contador e este pode ser relevante para outros utilizadores, ficar-lhe-íamos muito gratos se o pudesse colocar à nossa disposição. Então entregá-lo-emos com futuras versões do Gestor de Carregamento.

Descarregar definições de contadores para contadores adicionais

Estrutura de um ficheiro de definição:

As definições do contador são ficheiros JSON com um objeto JSON global que tem propriedades e sub-objectos. "rtype" determina o tipo de operação de leitura: 0 = Modbus, 1 = HTTP/JSON, 2 = MQTT/JSON. "mtype" determina o tipo de dispositivo: 0 = Outro dispositivo, 1 = Contador, 2 = Inversor, 4 = Armazenamento de bateria.

Pode especificar números em decimal ou hexadecimal com o prefixo 0x. Comentários de uma linha usando // também são permitidos.

Recomendamos que passe os seus ficheiros de definição por um validador JSON5, por exemplo, este validador JSON5 Deve ter lido o capítulo Fórmulas para compreender quais os valores que podem ser utilizados nas fórmulas da referência seguinte.

As definições de Modbus têm um objecto 'rtu' com as seguintes propriedades:

silence_period, em msec. determinado, a duração da pausa antes de um acesso Modbus RTU, para que o dispositivo reconheça o início de uma mensagem.
silence_same_slave, true: A pausa também é observada com vários acessos ao mesmo dispositivo.
retries: O número de retries se o dispositivo não responder.
rcv_timeout: em msec. o tempo máximo de espera por acesso até que o dispositivo responda.

Estas propriedades globais aplicam-se ao Modbus TCP e RTU:

modbus_read: O número de função do comando de leitura Modbus, normalmente 3 ou 4.
modbus_read_max_registers: O número máximo de registos que podem ser lidos de cada vez.
modbus_allow_gaps: true = áreas de registo não utilizadas podem ser lidas numa operação de leitura.

Para Modbus TCP e HTTP/JSON existe um objecto 'tcp' com as seguintes propriedades:

connect_timeout: é msec. o tempo máximo de espera para uma ligação TCP.
delay_after_connect: em msec. Pausa após a ligação ser estabelecida antes de enviar o primeiro comando.

Ambos os tipos de definição (Modbus e HTTP/JSON) têm as seguintes propriedades adicionais:

upd_delay: em msec. determina o intervalo em que um dispositivo pode ser lido. Alguns dispositivos ficam sobrecarregados se forem consultados com demasiada frequência.
manufacturer: String, nome do fabricante. Este é apresentado nas informações alargadas do mosaico.
delay_accumulated: true = Os valores acumulados (kWh) só são consultados a cada 3 segundos ou se houver energia suficiente. false = Estes valores são sempre consultados.
ui_addr: URL, se diferente do endereço do dispositivo para chamar a interface Web.
reserved: Matriz com valores que são interpretados como 0 (útil se o dispositivo suportar determinados valores consoante o modelo).

Se omitir as propriedades acima indicadas, o cFos Charging Manager assume valores predefinidos que funcionam bem na maioria dos casos.

Na definição JSON, o passo seguinte é a definição das variáveis que o aparelho utiliza para ler ou calcular os valores de corrente, tensão, etc. As seguintes variáveis são utilizadas pelo Gestor de carregamento. O Gestor de carregamento conhece as seguintes variáveis:
type_designation, version, firmware_version, serial: Estas formam o nome do modelo, como se mostra na informação alargada do mosaico. São consultadas uma vez ao configurar ou repor o aparelho.
voltage_l1..voltage_l3, current_l1..current_l3, power_w, power_var, power_va, power_w_l1..power_w_l3: O gestor de carregamento cFos tenta calcular os valores para voltage_l1..l3, signed current_l1..l3, power_w e power_va a partir destes. Não é necessário especificar todas as variáveis. O gestor de carregamento cFos tenta calcular os valores a partir das variáveis existentes.
import_wh, export_wh: O gestor de carregamento utiliza estas variáveis para apresentar import_wh e export_wh. Para contadores unidireccionais (por exemplo, inversores), deve definir sempre apenas import_wh. Export_wh só deve ser definido para contadores bidireccionais (como tanques de armazenamento ou contadores de referência da rede).

soc: Se disponível, o Estado de Carga de um tanque de armazenamento de bateria é apresentado em % no mosaico.
Além disso, é possível definir outras variáveis com nomes diferentes que são lidas em cada atualização ou calculadas através de fórmulas. Se definir variáveis que comecem por CM., por exemplo, CM._set_price, os valores atribuídos são armazenados nas variáveis globais do Gestor de Carregamento (ver abaixo) e podem ser consultados em conformidade.
Variáveis com *: Se definir variáveis que comecem por *, estas são apresentadas na IU no mosaico do contador sob a informação alargada, por exemplo, a temperatura de um armazenamento de bateria.

Definição de uma variável:


O objeto tem o mesmo nome que o nome da variável acima indicada e tem as seguintes propriedades: fixed: Cadeia de caracteres com um valor fixo.

Útil se, por exemplo, não for possível determinar qualquer valor, por exemplo, para type_designation ou tensão. expr: Cadeia de caracteres, a variável não é lida, mas avaliada como uma fórmula. type: Se não for fixed ou expr, o tipo de variável: int16, uint16, int32, uint32, float, int64, string. Isto é importante para o Modbus, a fim de ler os registos no formato correto. uint16 e uint32 são tipos que só podem aceitar números positivos.
Com JSON/HTTP, pode normalmente utilizar float. resolução: float, o valor lido é multiplicado por 'resolução'. Os valores da tensão devem ser em volts, as correntes em miliamperes, a potência em watts, a energia em watt-hora (Wh).


Com uma "resolução" negativa, pode inverter um valor se este tiver o sinal oposto. once: bool (verdadeiro ou falso); se for verdadeiro, o valor só é lido uma vez quando o dispositivo é inicializado; caso contrário, é lido periodicamente. address: número (Modbus) ou cadeia de caracteres (HTTP/JSON), o número de registo Modbus ou o URL HTTP do valor a ler. query:
String, para HTTP JSON, a especificação na linguagem de consulta do gestor de carregamento com a qual encontra o valor a ler na resposta JSON. order: String, para Modbus, a ordem dos bytes, "hl" ou "lh", em que o valor está presente. length: número, para Modbus, o comprimento de uma cadeia em registos. Para as variáveis "version" e "firmware_version", "length" é utilizado para transformar versões numéricas em cadeias com pontos. São permitidos valores de 2 ou 4 para "length", que resultam nos formatos de versão a.b, e a.b.c.d. Com 'length' 2 e tipo 'int16' ou 'uint16', o gestor de carregamento separa o byte baixo e o byte alto com um ponto, com 'int32' ou 'uint32' a palavra baixa e a palavra alta, com 'int64' a palavra baixa e a palavra alta. Para 'lenth' 4 e 'int32' ou 'uint32', o gestor de carregamento divide o valor em 4 bytes separados por um ponto.
No caso de 'int64', as 4 palavras são as mesmas. regex: Cadeia de caracteres. Se for especificada uma expressão regular, a resposta do contador não precisa de estar em JSON. A correspondência completa da expressão regular ou o primeiro grupo é avaliado como o resultado. Utilize esta opção apenas se o dispositivo não devolver JSON.

Aqui está a lista de características das nossas expressões regulares: qualquer caractere: . classes nomeadas:



\d \s \w \D \S \W classes anónimas: [a-z0-9_], [^0-9], [^\d] grupos com alternativas: (ab|cd|ef) grupos não capturados: (?:ab|cd) (greedy) uma vez ou nenhuma: a?, a???
(guloso) muitos ou nenhum: a*, a*?


(greedy ) uma ou mais vezes: a+, a+? início da cadeia: ^ fim da cadeia: $

Definição de inputs:

O Gestor de Carregamento pode consultar até 32 valores de entrada de diferentes registos ou elementos JSON por dispositivo. A propriedade "Inputs" é um conjunto JSON. Deve definir as seguintes propriedades para cada entrada:
endereço: Endereço: Endereço (registo Modbus ou URL).
contar: Número de bits de entrada que serão lidos com este pedido.
consulta: Para HTTP/JSON, consulte a linguagem de consulta para encontrar o valor na resposta.

O cFos Charging Manager lê todos os inputs definidos desta forma com cada actualização e coloca os bits internamente numa matriz, que pode então ser consultada em fórmulas, Input1...InputN...

Definição dos resultados:

O gestor de carregamento pode comutar até 32 saídas por equipamento. As saídas são definidas em "outputs" como uma matriz JSON de objectos de saída. Todas as saídas são comutadas no final de cada ciclo de atualização se o estado da respectiva saída tiver mudado.
Para cada saída, é necessário definir as seguintes propriedades no objeto de saída:
address: URL HTTP com método HTTP opcional, por exemplo, GET http://www.example.com?output1=${var1}. Para definir os registos Modbus, pode utilizar a API HTTP do Gestor de Carregamento cFos. O Charging Manager detecta os acessos correspondentes no localhost e redirecciona o pedido para o manipulador interno, pelo que não é necessária autorização, como acontece com os acessos externos à API HTTP. Se o URL estiver vazio após todas as substituições, não é definida qualquer saída. Por exemplo, só é possível mudar as mensagens se existirem determinadas variáveis (ver fórmulas: função exists()). No endereço, pode especificar adicionalmente ${address} e ${id}. Este é o endereço atual do dispositivo e o ID Modbus, tal como definido nas definições. O endereço e o id são utilizados principalmente para utilizar a API Modbus (ver abaixo).
body: Corpo HTTP opcional para POST ou PUT.
No URL e no corpo, é possível utilizar fórmulas ${expr} que fazem referência a variáveis globais do Charging Manager ou do respetivo contador. A fórmula "expr" é avaliada ao definir a saída e substituída no texto do URL ou do corpo. Se, no exemplo acima, http://www.example.com?output1=1 define a saída e http://www.example.com?output1=0 a elimina, pode definir uma variável 'var1' e defini-la para 1 ou 0 conforme pretendido. Desta forma, também é possível escrever valores numéricos para controlar o desempenho da memória nos registos Modbus que foram previamente armazenados numa variável utilizando uma fórmula.
Se, em vez de passar um valor numérico no URL, precisar de substituir um texto por outro, dependendo da fórmula, tal como acontece com as tomadas Shelly WLAN, pode escrevê-lo assim: ${if expr`text1`text2}. O 'apóstrofo' é um backtick (código ASCII 96). Se o 'expr' != 0, é inserido texto1, caso contrário texto2. Para a tomada WLAN da Shelly, o URL tem o seguinte aspeto: http://<ip-addr>/relay/0?turn=${if expr`on`off}, ou seja, se expr != 0, o gestor de carregamento chama http://<ip-addr>/relay/0?turn=on, caso contrário http://<ip-addr>/relay/0?turn=off.

Se introduzir um caminho relativo como URL, o gestor de carregamento utiliza o endereço configurado para o respetivo aparelho. Se introduzir "localhost" como domínio, o gestor de carregamento utiliza o endereço do aparelho no qual está a ser executado. Se detetar um acesso à sua própria API, utiliza o manipulador interno em vez de executar um acesso HTTP completo, para que não seja necessário guardar um nome de utilizador e uma palavra-passe na definição do contador. Um URL que comece por um * fará com que o gestor de carregamento efectue sempre um acesso HTTP completo.

Repor as saídas: Para além de uma matriz "outputs", também pode definir uma matriz denominada "resets" que está estruturada como a matriz "outputs". Esta pode ser utilizada para repor as saídas nos seus valores iniciais quando o dispositivo é desativado. Com isto, em combinação com variáveis definidas pelo utilizador e "once": true, é possível repor a unidade no seu estado inicial.
Escrever as saídas periodicamente: Para alguns dispositivos, as saídas têm de ser escritas periodicamente, caso contrário o dispositivo repõe os valores para "predefinição". Por exemplo, a memória Kostal utiliza novamente as suas regras por defeito se o controlo da memória não tiver sido escrito ativamente durante algum tempo. Para definir as saídas periodicamente, pode prefixar o endereço com #xxx#, em que xxx indica de quantos em quantos segundos a saída é reescrita, mesmo que o valor a ser escrito tenha permanecido o mesmo. Por exemplo, se o endereço for /cnf?cmd=set_cm_vars&name=test&val=42, pode utilizar #30#/cnf?cmd=set_cm_vars&name=test&val=42 para garantir que este valor é escrito de 30 em 30 segundos.

Definição de langage de consulta:

Actualmente, os nomes dos membros e dos operadores "." e "[]" podem ser utilizados nas expressões de pesquisa "consulta", exemplos:

testeElemento denominado "teste"
nome1.nome2Elemento chamado "nome2" no objecto infantil "nome1
nome[idx]Elemento "idx" do elemento objecto "nome". "idx" pode ser um número, por exemplo, para arrays ou um fio
nome["u2"]O elemento "u2" do elemento objecto "nome", corresponde a "name.u2"
nome[{"el1": "v1", "el2": 3}].valorSeleccionar o elemento da matriz que preenche a condição da notação do objecto e avaliar o elemento denominado 'valor'. Aqui, por exemplo, na matriz 'nome', é seleccionado o elemento que tem como elemento objecto 'el1' com valor 'v1' e 'el2' com valor 3 e depois o valor do elemento 'valor' é devolvido a partir deste objecto.

Variáveis do Gestor de Carregamento Global:

Pode criar variáveis na configuração do Gestor de Carregamento. Pode usar um valor fixo ou uma fórmula como valor. No final de cada ciclo de actualização, o Gestor de Carregamento recalcula o valor destas variáveis, se necessário. Pode então utilizá-los em (certos) parâmetros do Gestor de Carregamento, Regras de Carregamento ou para controlar as saídas. Também pode escrever Ex.member ou Mx.member como variáveis. Aqui, Exe Mxsão a identificação do dispositivo de uma caixa de parede ou contador configurado no Gestor de Carregamento. membro é uma variável "definida pelo utilizador" que é armazenada no dispositivo correspondente. Algumas das variáveis podem ter um significado especial: Para KEBA "out1" é uma saída de comutação, para ABB B23 metros "out1" e "out2" são saídas de comutação (para modelos que suportam isto). Um 1 desliga a saída, um 0 desliga-a novamente.

Se tiver aparelhos que têm de ser ligados em determinadas condições, mas que depois funcionam durante algum tempo (por exemplo, máquina de lavar roupa, máquina de lavar louça), pode também definir a variável como um "accionador". Assim, a fórmula da variável é a condição em que a variável é definida como 1. Após um período de tempo ajustável, é novamente definida para 0. Uma "condição de retractação" permite que o tempo até à desactivação (ou seja, colocar a variável a 0) seja repetidamente prolongado, desde que a condição seja cumprida.

Para efeitos de teste, pode apresentar as variáveis do gestor de carregamento e do contador, por exemplo, os preços actuais do Awattar:


                        Visualização da imagem do ecrã das variáveis do contador

Saídas do Gestor de Carregamento Global:

Na configuração do Gestor de Carregamento, é possível configurar as saídas globais como descrito acima na definição do contador em 'Saídas'. Estes são definidos no final de cada ciclo de actualização, se o seu estado tiver mudado. Se quiser controlar as saídas de comutação em dispositivos definidos pelo utilizador, recomenda-se a convenção acima (ver Variáveis do Gestor de Carregamento): Definem-se variáveis com nomes "out1", "out2", etc. no contador definido pelo utilizador e configuram-se saídas no contador definido pelo utilizador que mudam a saída dependendo do valor destas variáveis.

Global Modbus API do Gestor de Carregamento:

O Modbus API do Gestor de Carregamento é utilizado para controlar dispositivos Modbus que tenham qualquer endereço Modbus RTU ou TCP (acessível através do Gestor de Carregamento). Para Modbus RTU, introduzir COMx,bd,8,p,s como endereço, onde x é o número da porta COM, bd é a taxa de baud, p é a paridade ('N', 'E' ou 'O') e s é o número de bits de paragem (1 ou 2), como na configuração dos dispositivos individuais. Para Modbus TCP, o destinatário é o endereço IP do dispositivo na rede do Gestor de Carregamento, incluindo o número da porta.
O URL (para HTTP GET) do Modbus API é:
/cnf?cmd=modbus_get ou /cnf?cmd=modbus_set
O cFos Charging Manager suporta os seguintes parâmetros de consulta adicionais:
address: O endereço do dispositivo Modbus RTU ou TCP acima mencionado.
func: Número da função Modbus, por exemplo para leitura 3 ou 4, para escrever 6 ou 16.
id: ID do dispositivo Modbus.
reg: O número de registo do Modbus. O valor pode ser dado em decimal ou hexagonal (com prefixo 0x).
val: número, valor a ser inscrito no registo. Omitir ao ler.
tipo: 'w' 16bit (por defeito), d = 32bit, f = float, q = 64bit, s = string.
cnt: número, o comprimento máximo da corda nos registos, omitir para outros tipos ou definir para 1.
ordem: corda, a ordem do byte, ou "hl" ou "lh".

Nota: Se o seu 'contador' tiver principalmente tarefas de controlo, pode assinalar a opção 'Ocultar dispositivo' nas definições deste azulejo para que este dispositivo não apareça na página inicial.

Nota: Alguns contadores que são lidos via HTTP requerem um nome de utilizador/palavra-passe como autorização. Pode especificá-lo no endereço para acesso HTTP, por exemplo com _COPY2@192.168.2.111. Se o seu nome de utilizador ou palavra-chave contiver um "@", deve substituí-lo por "%40".