# As ferramentas, área por área

> O que cada ferramenta que um agente pode chamar faz, agrupada pelo interruptor de capacidade que a anuncia, e as ferramentas de ajuda que não precisam de nenhum.

Os nomes de ferramenta são identificadores estáveis em snake_case. Os erros são estruturados e acionáveis: uma
chamada que falha devolve o que deu errado mais uma dica nomeando a ferramenta ou o passo que resolve, para
que um agente se corrija sozinho em vez de adivinhar. O servidor instrui todo agente a ler a ajuda com
`help_search` e `help_read` antes de responder a uma pergunta sobre como a aplicação funciona e, quando a área
Backups (gerenciar) está ligada, a criar um backup de configuração antes de fazer mudanças de configuração.
Qual dessas listas um agente de fato vê está em [o que cada área libera](agent-areas), mais as ferramentas de
ajuda, que não precisam de área nenhuma.

## Ajuda {#help}

As duas ferramentas de ajuda leem esta documentação como a instalação a traz: os mesmos artigos que o [painel
de ajuda](app-window#contextual-help) abre, escritos para a versão instalada na estação. Elas vêm com o
endpoint sempre que o interruptor mestre está ligado, não importa o que digam os interruptores das áreas,
porque o texto é a documentação pública e não mostra nada da estação. As duas continuam funcionando com o
runtime parado.

| Ferramenta | O que faz |
| --- | --- |
| `help_search` | Encontra artigos pelas palavras de uma pergunta e devolve de cada um o slug, o título, o resumo e as seções que as palavras tocam, a melhor correspondência primeiro (10 por padrão, até 50). Maiúsculas e acentos são ignorados. Sem consulta, lista todos os artigos. |
| `help_read` | Lê um artigo inteiro pelo slug como texto simples: o título, o resumo, a lista de seções e o corpo, com cada seção numa linha de título e as tabelas com uma linha da tabela por linha de texto, mais os slugs dos artigos para os quais ele aponta. |

As duas leem por padrão o idioma da interface da estação, para que as páginas, os botões e os campos que uma
resposta nomeia sejam os que estão na tela. Qualquer uma aceita um `culture` que nomeia outro idioma que a
ajuda instalada traz; um idioma que ela não traz é recusado com a lista dos que ela traz, e nenhum outro
idioma responde no lugar dele. Uma instalação cuja ajuda está faltando ou não pode ser lida responde cada
chamada com o motivo em vez de artigos.

## Connector: leitura {#connector--read}

| Ferramenta | O que faz |
| --- | --- |
| `connector_browse` | Lista a árvore que a página Connector desenha, com a saúde ao vivo: todo driver acrescentado à estação, inclusive um sem nada abaixo dele, e um driver que tem um dispositivo, uma linha serial ou um broker está sempre acrescentado; o Modbus RTU como driver, linha serial, dispositivo, tag; o MQTT como driver, broker (com o estado da sessão), dispositivo, tag; todo outro driver como driver, dispositivo, tag, com a pasta de cada dispositivo ao lado. O Generic serial and TCP lista as linhas seriais dele como o Modbus RTU e os dispositivos de rede como qualquer outro driver, com o transporte de cada dispositivo. O SCPI instruments lista as linhas seriais e os outros dispositivos dele do mesmo jeito. Um dispositivo File traz a pasta, o nome do arquivo, como lê (um arquivo ou uma pasta de entrada) e o formato. Um dispositivo Database traz o tipo de banco de dados (`databaseKind`). Cada dispositivo traz `error`, a única frase que a página dele mostra, no idioma da estação: uma frase que aponta para a linha serial ou o broker dele quando o erro é daquele nível, senão o erro do próprio dispositivo (não conecta, a conexão é recusada, o driver avisa), senão o resumo das tags dele cuja leitura é recusada, e o motivo de cada tag é o `readFailure` do `tag_read`. Fica `null` quando o dispositivo não tem nenhum; a frase que o `tag_read` dá para uma tag cujo dispositivo não está conectado leva até aqui. Revela os apelidos de tag (`Driver.Folders….Device.Tag`) que o `tag_read`, o `tag_write` e as expressões da Logic usam. Os apelidos são nulos enquanto o Connector está parado. |
| `tag_read` | Lê os valores ao vivo de uma tag pelo apelido: `valueRaw`, o valor do próprio dispositivo antes de qualquer estágio, `value`, o valor de engenharia depois de todos os estágios da cadeia de conversão, o de Decimais incluído (um Double que o dispositivo informa como 2,718281828459 lê 2,72 com Decimais em 2), a qualidade, os dois carimbos de tempo e `substitution`, que diz se o valor é um substituto configurado em vez do que o dispositivo informou: `None` (uma medição, ou nenhum valor), `NaNReplaced` (a leitura foi NaN e o número declarado tomou o lugar dela), `LastGoodHeld` (a leitura falhou e a última leitura que chegou fica mantida, com o valor bruto e os carimbos dela) ou `ReadFailureReplaced` (a leitura falhou e o número declarado é apresentado). Um substituto conta como valor, então a qualidade continua boa, a não ser que uma falha de limite apareça, mas ele nunca é uma medição. `communicating` diz se o dispositivo ainda está respondendo: falso quando a última leitura falhou ou nada foi lido ainda. Uma leitura que passou do intervalo de leitura da tag, mais uma pequena margem, sem leitura nova vale como uma leitura que falhou: o valor, a qualidade e `substitution` respondem como para uma (sem valor e qualidade ruim no padrão, a leitura mantida ou o número declarado onde a tag pede), `communicating` é falso e os carimbos de tempo datam a última leitura que chegou. Um valor fora dos limites da tag não é falha de conexão: a qualidade fica ruim enquanto `communicating` continua verdadeiro. `readFailure` diz por que uma leitura não chegou, na única frase que o painel da tag mostra, no idioma da estação: o motivo que o dispositivo ou o driver deu quando a leitura da própria tag foi recusada, ou uma frase que aponta para o dispositivo da tag quando ele não está conectado. Fica `null` enquanto a tag lê e quando uma leitura que não chegou ainda não tem motivo registrado. |
| `modbus_server_status` | Informa sobre o [servidor Modbus](connector-modbus-server) da própria estação: se está ligado (`enabled`), a `port`, o `status` (Off, Listening, PortInUse, Failed com as palavras do sistema em `failure`, ou RuntimeStopped), os clientes conectados agora (no máximo `maximumClients` ao mesmo tempo) e cada linha do mapa de registradores: a `registerClass`, o `register` contado a partir de 0 e o `lastRegister`, o tipo e a disposição, o `access` (ReadOnly ou ReadAndWrite), a origem (uma tag ou uma variável, por endereço e id) e o que um cliente lê ali agora, `value` e `good`, ou o `gap` (NoSource, SourceRemoved, NoGoodValue, NotRepresentable) pelo qual um cliente recebe a exceção 04. Continua funcionando com o runtime parado. |
| `station_broker_status` | Informa sobre o [broker MQTT](connector-mqtt-broker) da própria estação, aquele em que os dispositivos publicam, nunca um dos brokers que a estação lê: se está ligado (`enabled`), a `port`, o `status` (Off, Listening, PortInUse, Failed com as palavras do sistema em `failure`, ou RuntimeStopped), a `authentication` (Anonymous ou UsernamePassword, com `username` e `hasPassword`, nunca a senha), os dispositivos conectados agora (no máximo `maximumClients` ao mesmo tempo) e `thisStationEntry`, o broker Esta estação do driver MQTT pelo qual a estação o lê. Continua funcionando com o runtime parado. |
| `mqtt_publish_list` | Lista o que a estação publica em cada broker MQTT que ela lê, o [cartão Publicar](driver-mqtt#the-publish-card) de cada um: o `publishTopicPrefix` do broker e se ele publica, e cada linha com a origem (pelo endereço, `removed` quando a origem foi excluída), o `topic` e a mensagem (`value` ou `alarm`), com as duas mensagens descritas em `payloads`. Continua funcionando com o runtime parado. Uma linha com `access` `ReadAndWrite` aceita valores no `writeTopic` dela (o tópico seguido de `/set`), escritos na origem e registrados no diário como `MQTT <nome do broker>`; `payloads.write` diz o que esse tópico aceita. Cada broker diz o `publishFormat` dele; um broker em Sparkplug B acrescenta `sparkplug` (o grupo, o ID do nó de borda da estação e os dispositivos), cada linha dele diz o dispositivo e a métrica como os quais é publicada, e `payloads.sparkplug` diz como o Sparkplug B sai ([Publicação em Sparkplug B](driver-mqtt#publishing-in-sparkplug-b)). |
| `remote_access_devices` | Informa quem abre as telas da estação pela rede: os navegadores conectados de outro computador ou tablet neste momento (endereço, navegador e sistema, página, usuário, desde quando e o dispositivo configurado que cada um é) e os dispositivos configurados com o jeito como cada um abre (tela inicial, trava, como quem entra, os minutos depois dos quais volta, somente visualização, e por que abre de outro jeito quando o usuário fixo ou a tela inicial mudou). Nunca traz uma chave nem o hash dela. Continua funcionando com o runtime parado. |
| `server_status` | Relata a saúde do [servidor OPC UA](connector-opcua-server) embutido: se ele está ligado (`enabled`), se está rodando, o tempo no ar, a URL do endpoint e as sessões de cliente conectadas, e o tamanho do espaço de endereços configurado; `available` diz se o runtime do Connector lê, o que ele faz também enquanto o servidor está desligado ou parado, e `serverError` por que a última partida do servidor falhou. `list` é o que o servidor serve, e tudo o que ele serve: uma linha por tag, variável da Logic, alarme ou comando de dispositivo, cada uma com o `access` e o `node` com que um cliente é configurado; enquanto ela está vazia, `servesNothing` é verdadeiro. |

## Connector: configuração {#connector--configure}

| Ferramenta | O que faz |
| --- | --- |
| `driver_capabilities` | Lista todo driver que a aplicação consegue atender, com os campos de conexão de que um dispositivo precisa, o modelo de endereçamento de tag (endereço em texto livre e/ou campos tipados), o suporte e os parâmetros de descoberta, as faixas de tempo e os tipos de valor suportados, com `defaultPort`, a porta em que é chamado um dispositivo que não informa nenhuma. `added` diz se o driver está acrescentado à estação, que é o que o desenha na árvore do Connector; criar um dispositivo, uma linha serial ou um broker com `device_upsert`, `serial_line_upsert` ou `mqtt_broker_upsert` acrescenta o driver dele. O AVEVA PI e o HTTP chamam a porta do transporte que o dispositivo usa, então também dão `defaultPortByTransport`: 443 por HTTPS, o padrão deles, e 80 em claro. O Generic serial and TCP acrescenta `genericSerialTcp`: os transportes, como os bytes são digitados, como as mensagens terminam, os checksums, os modos de tag, os filtros e as extrações, como os valores são lidos e escritos, e dois exemplos completos. O Omron acrescenta `omron`: os dois protocolos com os campos de dispositivo, as formas de endereço e os tipos de dado de cada um, os transportes e as faixas FINS, as escritas e a descoberta. O SCPI instruments acrescenta `scpi`: os transportes, se este computador tem VISA (`visa.installed`), os terminadores, as confirmações de escrita, os comandos de preparação, como se escrevem consultas e comandos de escrita e como as respostas são lidas, a descoberta e dois exemplos completos. O NI-DAQmx acrescenta `niDaqmx`: para cada medição, um canal de exemplo, a unidade, os campos e os tipos de dado e acessos que ela permite. Um driver cujos dispositivos precisam de algo que o produto não pode distribuir acrescenta `prerequisite` (Fluke NetDAQ: o runtime Visual C++ 2005; OPC DA: os OPC Core Components, OpcEnum e o proxy e stub do OPC DA; NI-DAQmx: o NI-DAQmx da National Instruments; SCPI: um VISA de 64 bits, NI-VISA ou Keysight IO Libraries Suite, só para os dispositivos VISA, com as duas páginas; Database: um driver ODBC de 64 bits ou uma origem de dados para um dispositivo ODBC, julgado por dispositivo (`perDevice` true), de modo que `installed` fica null e o erro do próprio dispositivo diz o que falta): se este computador o tem (`installed`, para um driver adicionado à estação), a página oficial de download, o arquivo, como instalar, o tropeço conhecido e o que acontece depois. O SNMP acrescenta `snmp`: as versões e as credenciais que cada uma recebe, os níveis de segurança e os protocolos SNMPv3, os tipos por espécie de valor, todo objeto padrão que o driver conhece pelo nome com o seu OID, como leituras e escritas se comportam, a descoberta e dois exemplos completos. File acrescenta `file`: o caminho simples, a pasta e o confinamento a ela, as formas do nome do arquivo, um arquivo ou uma pasta de entrada, os formatos com a gramática de endereço de cada um, o que uma tag lê e os tipos, as configurações de texto, como leituras e escritas se comportam, a descoberta e três exemplos completos. Database acrescenta `database`: cada banco de dados com os campos e a porta própria, a criptografia, os dois jeitos de uma tag ler e os dois de escrever, a regra de que um valor só entra numa instrução como `@value` ou `@now`, os tempos de espera, o conselho sobre o usuário do banco de dados, a descoberta e quatro exemplos completos. O mapa que um agente lê antes do `device_upsert` ou do `tag_upsert`. |
| `serial_line_list` | Lista toda linha serial persistida, incluídas as desabilitadas e as vazias, com o id estável e o driver dela; uma linha Modbus RTU também com o modo e os valores de tempo configurado, automático e efetivo. |
| `serial_line_upsert` | Cria uma linha serial ou atualiza uma pelo id estável. `driver` nomeia o driver a que ela pertence, `ModbusRtu` (o padrão), `GenericSerialTcp`, `Scpi` ou `Omron`, fixo na criação; uma linha do driver genérico, do driver SCPI ou do driver Omron recusa `mode`, `responseTimeoutMs` e `minimumTransactionIntervalMs`. O nome e o estado de habilitação mudam a qualquer momento; o intervalo mínimo entre transações também muda com a linha habilitada; porta serial, velocidade em baud, formato serial, modo de transmissão e timeout de resposta só mudam enquanto a linha persistida está desabilitada. |
| `serial_line_delete` | Exclui uma linha pelo id estável. Uma linha que ainda contém dispositivos é recusada, a menos que a chamada autorize explicitamente excluir todo dispositivo filho e as tags deles. |
| `mqtt_broker_list` | Lista todo broker MQTT persistido, incluindo os desabilitados e os vazios, com o id estável, onde ele responde, o transporte, o usuário, o ID do cliente, o keep-alive, o prefixo de tópico e a contagem de dispositivos. Diz se há uma senha guardada e nunca a devolve. Mostra também o formato da publicação (`publishFormat`) e o grupo Sparkplug B (`sparkplugGroupId`). |
| `mqtt_broker_upsert` | Cria um broker MQTT ou atualiza um pelo id estável: nome, estado habilitado, host (um endereço `mqtt://` ou `mqtts://` inteiro é desmembrado), porta, TLS, usuário, senha, ID do cliente, keep-alive e o prefixo sob o qual o cartão Publicar sugere tópicos (`publishTopicPrefix`, uma string vazia volta ao padrão). Só os parâmetros informados mudam; um broker só é habilitado com host, e um ID do cliente que outro broker usa é recusado. Uma mudança salva na conexão reconecta a sessão que todo dispositivo abaixo do broker compartilha. `publishFormat` (`Json` ou `SparkplugB`) escolhe como o cartão Publicar sai, e `sparkplugGroupId` o grupo Sparkplug B do nó de borda da estação (uma string vazia volta a `GanterLab`; um grupo com `/`, `+` ou `#` é recusado). |
| `mqtt_broker_delete` | Exclui um broker pelo id estável. Um broker que ainda contém dispositivos é recusado, a menos que a chamada autorize explicitamente excluir todo dispositivo filho e as tags deles. |
| `mqtt_publish_upsert` | Cria uma linha do [cartão Publicar](driver-mqtt#the-publish-card) de um broker (`brokerId` e `source`: uma tag, `Connector.` e o alias dela, uma variável, `Variables.` e o caminho dela, ou um alarme, `Alarms.` e o caminho dele) ou edita uma pelo `id`. `topic` é opcional: omitido, a linha recebe o sugerido pelo nome da origem sob o prefixo do broker, e uma string vazia o recebe de novo. Um broker publica uma origem uma vez e um tópico uma vez; um tópico não tem + nem # e não começa com $. Uma linha nunca muda de broker. `access` é `ReadOnly`, o padrão, ou `ReadAndWrite`, que só uma tag com acesso de escrita num driver que escreve, ou uma variável de memória, aceita: a estação então escreve o que é publicado no tópico da linha seguido de `/set` ([Escrita de volta](driver-mqtt#writing-back)). O tópico de uma linha não pode ser o tópico de outra seguido de `/set`. Num broker em Sparkplug B a linha é publicada como uma métrica (`row.sparkplug`), e `ReadAndWrite` aceita os valores que os comandos Sparkplug B enviam a ela. |
| `mqtt_publish_delete` | Exclui uma linha de um cartão Publicar pelo `id`. A estação para de publicá-la; a tag, a variável ou o alarme não é tocado. |
| `device_upsert` | Cria ou atualiza um dispositivo por driver + nome (o driver é imutável depois da criação). Só os parâmetros fornecidos mudam; os campos de conexão são por driver; mover um dispositivo para uma pasta reescreve toda referência aos endereços antigos das tags dele. Um dispositivo do Generic serial and TCP recebe `transport` e os campos dos cartões Mensagens e Soma de verificação, e `serialLineId` só de uma linha do próprio driver; um dispositivo de linha recusa host, porta e pasta. Um dispositivo Omron aceita `omronProtocol` (`Fins` ou `NjNx`) e, por FINS, os campos `fins*` do cartão FINS dele; um dispositivo lido por nome de tag recusa porta. Um dispositivo SCPI aceita `transport` (`Tcp`, `Visa`, ou `SerialLine` com o `serialLineId` de uma linha do próprio driver), `visaResource`, `terminator`, `responseTimeoutMs`, `writeCheck` e `setupCommands`. Um dispositivo NI-DAQmx aceita `daqmxDevice`, o nome que o NI MAX lhe dá. Um dispositivo SNMP aceita `snmpVersion`, `snmpCommunity` (SNMPv1, SNMPv2c), `username`, `password`, `snmpSecurityLevel`, `snmpAuthProtocol`, `snmpPrivacyProtocol` e `snmpPrivacyPassword` (SNMPv3), `responseTimeoutMs` e `snmpRetries`; devolve se cada segredo está definido, nunca o segredo. Um dispositivo File aceita `fileFolder`, `fileName`, `fileMode` (`SingleFile` ou `Inbox`), `fileFormat`, `fileEncoding`, `fileSeparator`, `fileDecimal`, `fileHeaderRow` e `fileWrites`, com `fileHeaderText` e `fileLineEnd` quando a escrita está ligada; devolve `file.fileStatus`, o arquivo que o driver em execução lê e o que leu dele. Um dispositivo Database aceita `databaseKind`, e para um servidor `host`, `port` e `databaseName` (no SQL Server também `databaseInstance`, `databaseWindowsSignIn` e `databaseEncryption`), `databaseFile` para o SQLite ou `databaseOdbc` para o ODBC, com `username` e `password`; devolve `database`, o endereço e se o dispositivo ainda aguarda o usuário, nunca a senha. Uma porta fora de 0 a 65535 é recusada; 0 quer dizer a porta que o driver usa. A mudança é reconciliada no servidor em execução na hora. |
| `device_delete` | Exclui um dispositivo e todas as tags dele; reconciliado no servidor em execução na hora. |
| `tag_upsert` | Cria ou atualiza uma tag num dispositivo. O endereçamento é específico do driver (endereço em texto livre e/ou campos tipados; no Generic serial and TCP, o modo de leitura, a requisição, o filtro, a extração e os campos de escrita; no SCPI instruments, a consulta como `address`, o `valueField` e o `writeTemplate`; no NI-DAQmx, o canal físico como `address` e os campos `daqmx*` da medição; no SNMP, o OID como `address`, em números ou pelo nome padrão; no File, a coluna ou o caminho como `address`, `fileSource`, `fileRow` e os campos dele, `fileWriteMode` e `fileLineTemplate`, um valor de texto livre usando os campos `value*` do driver genérico, e uma tag nova nascendo somente leitura; no Database, a coluna do valor como `address`, `databaseSource`, `databaseTable`, `databaseRow` e os campos dele ou `databaseQuery`, e quando a tag escreve `databaseWriteMode` e `databaseCommand`, uma tag nova nascendo também somente leitura); a resposta ecoa o endereço de barramento montado e o apelido para o `tag_read`. Inclui os estágios de leitura inválida: a ação de NaN em tags numéricas, e a apresentação de falha de leitura em toda tag que a estação lê, em que só o `Replace` é limitado a tags numéricas e booleanas. Um `Replace` já guardado que o novo tipo da tag não aceita é gravado como o padrão: a ação de NaN passa a `PassThrough` quando o tipo deixa de ser numérico, e a apresentação de falha de leitura passa a `ShowError` quando o tipo é String, DateTime, Guid ou ByteString. |
| `tag_delete` | Exclui uma tag; reconciliado na hora. |
| `server_start` | Liga o servidor OPC UA embutido e o inicia, como faz o Habilitar na linha dele: ele serve a lista dele, e continua ligado através dos reinícios até o `server_stop`. Não faz nada quando ele já está rodando; quando o próprio Connector não está rodando, ele é iniciado antes, materializando a configuração atual. |
| `server_stop` | Desliga o servidor e o para com elegância, como faz o Desabilitar: os clientes OPC UA caem e nada é publicado até o `server_start` ligá-lo de novo. O Connector continua lendo, e as leituras de tag, a Logic e as gravações continuam. |
| `server_restart` | Parar e então iniciar só o servidor, enquanto ele está ligado; o Connector lê o tempo todo. Um servidor desligado é recusado, já que é o `server_start` que o liga. Mudanças de dispositivos e tags se aplicam com o `connector_refresh`. |
| `server_list_upsert` | Cria uma linha da [lista](connector-opcua-served-nodes) do servidor OPC UA, ou atualiza uma pelo `id`. `source` nomeia uma tag (`Connector.` e o alias), uma variável (`Variables.` e o caminho), um alarme (`Alarms.` e o caminho) ou um comando de dispositivo (o endereço do dispositivo, um ponto, o nome do comando e `()`); uma origem entra na lista uma vez só. `access` é ReadOnly, o padrão de toda linha nova, ou ReadAndWrite, que só uma tag com acesso de escrita ou uma variável de memória aceita; a escrita de um cliente passa então pelo funil de escrita da Logic e fica no diário com a sessão do cliente. A resposta traz a linha com o `node` dela. |
| `server_list_delete` | Exclui uma linha da lista pelo `id`. Um cliente deixa de encontrar o nó dela; a origem que ela servia não é tocada. |
| `modbus_server_configure` | Liga ou desliga o servidor Modbus (`enabled`) ou o move para outra `port`, de 1 a 65535, como faz a página dele. A porta do servidor web, do acesso de agente ou do servidor OPC UA, e uma porta que outro programa segura, são recusadas; o Firewall do Windows nunca é alterado. Ligado, ele deixa qualquer máquina que alcance a porta ler o que o mapa serve. Responde com o servidor inteiro, como `modbus_server_status`. |
| `station_broker_configure` | Liga ou desliga o broker MQTT da própria estação (`enabled`), o move para outra `port` e muda a `authentication`, o `username` e a `password` dele, como faz a página dele, nesta ordem: porta, autenticação, depois ligar ou desligar. A porta do servidor web, do acesso de agente, do servidor OPC UA ou do servidor Modbus, e uma porta que outro programa segura, são recusadas; o Firewall do Windows nunca é alterado. Ligado, ele adiciona o broker Esta estação ao driver MQTT. Responde com o broker inteiro, como `station_broker_status`. |
| `modbus_map_upsert` | Cria uma linha do mapa de registradores do servidor Modbus, ou atualiza uma pelo `id`. `source` nomeia uma tag pelo endereço (`Connector.` e o alias, como `connector_browse` o lista) uma variável (`Variables.` e o caminho) ou um alarme (`Alarms.` e o caminho, sempre ReadOnly, servindo o estado que `alarmValue` indica: Active, Acked ou State); `registerClass` (HoldingRegister por padrão), `register` (começando em 0), `type` (Float por padrão, Boolean numa coil ou numa entrada discreta), `length` para um String, `mostSignificantByte` e `mostSignificantWord` seguem os campos e as regras de uma tag Modbus. `access` é ReadOnly, o padrão de toda linha nova, ou ReadAndWrite, que só um holding register ou uma coil aceita, de uma origem que aceita escrita (uma tag com acesso de escrita, uma variável de memória). Uma linha nova precisa do `register` e da `source`; uma linha que o mapa recusa é respondida com o motivo e uma dica. |
| `modbus_map_delete` | Exclui uma linha do mapa de registradores pelo `id`. Um cliente que lê os registradores dela recebe a exceção 02 daí em diante; a tag ou a variável que ela servia não é tocada. |
| `remote_access_device_update` | Muda o nome de um dispositivo configurado, a tela inicial (um dashboard por id ou nome, ou vazio para tirá-la, o que também o destrava), a trava, os minutos parado (0 para nunca) e o somente visualização, como faz a linha dele na página Acesso remoto. Como quem o dispositivo entra não muda aqui: isso exige uma pessoa com Gerenciar usuários locais. Um dispositivo é configurado e esquecido na tela da estação, nunca por uma ferramenta. Responde com o dispositivo como `remote_access_devices` o lista. |

## Connector: operação {#connector--operate}

| Ferramenta | O que faz |
| --- | --- |
| `connector_refresh` | Reconcilia incrementalmente o servidor em execução com os dispositivos configurados (acrescenta, remove, recria) sem um reinício completo; o jeito mais leve de aplicar mudanças. |
| `device_discover` | Roda a varredura de descoberta de dispositivos de um driver e devolve candidatos com as tags deles, sem persistir nada. Só participam drivers cujo protocolo suporta uma varredura de verdade; candidatos que já existem são marcados como tal. Uma varredura SNMP percorre ou `target` com `snmpCommunity`, ou `snmpDevice`, um dispositivo configurado, que é como um agente SNMPv3 é varrido. Uma varredura File lê ou `fileDevice`, um dispositivo configurado, ou `fileFolder`, `fileName`, `fileMode` e `fileFormat` digitados para a varredura. Uma varredura Database lê `databaseDevice`, um dispositivo configurado, e opcionalmente `databaseTables`, um nome de tabela ou um padrão com `*`. Um `target` que o cartão Escopo da varredura do driver recusaria, ou nenhum onde a varredura precisa de um, é recusado com o que ele tem de ser. Uma varredura Database, File ou SNMP parada no seu limite de valores, tabelas ou objetos diz isso em `cut`, com o que passar para ver o resto; uma lista inteira não tem `cut`. |

## Logic: leitura {#logic--read}

| Ferramenta | O que faz |
| --- | --- |
| `logic_browse` | Navega o espaço de endereços enraizado da Logic, a mesma árvore com pontos que toda expressão lê: System, Server, Connector, Variables, Alarms, Process e Assets. As pastas do operador são níveis de endereço de verdade; os pontos filhos incluem o valor ao vivo e a qualidade deles, e um ponto de tag do Connector traz também o `substitution` e o `communicating`, como o `logic_read` os informa. |
| `logic_read` | Lê um ponto pelo endereço com pontos dele (por exemplo `Variables.Setpoint`) e devolve o valor ao vivo e a qualidade. Um ponto de tag do Connector traz também o `substitution` e o `communicating`, como o `tag_read` os informa, que é o que distingue um substituto, ou a leitura de um dispositivo que parou de responder, de uma medição ao vivo; os outros pontos não trazem nenhum dos dois. Uma leitura que calou aparece ali como uma leitura que falhou. |

## Logic: configuração {#logic--configure}

As inserções e atualizações são parciais (os parâmetros omitidos mantêm o valor deles) e todo rascunho fundido passa
pela mesma validação que os editores da [Logic](logic) aplicam; um rascunho inválido é rejeitado e
nada fica aplicado pela metade.

| Ferramenta | O que faz |
| --- | --- |
| `variable_upsert` | Cria ou atualiza uma variável: Expressão (uma única expressão JavaScript somente leitura sobre o espaço de endereços) ou Memória (um valor gravável, opcionalmente retentivo). O nome é a chave e, higienizado, o endereço; o parâmetro de pasta a arquiva, reescrevendo toda referência ao endereço antigo. |
| `variable_delete` | Exclui uma variável pelo caminho, com o valor retido dela. Os canais vinculados a ela perdem a origem. |
| `action_upsert` | Cria ou atualiza uma ação: um bloco de instruções JavaScript com exatamente dois verbos de escrita, a atribuição a variável de memória e a escrita de tag em valor de engenharia. Validada estaticamente, nunca executada no momento de salvar. |
| `action_delete` | Exclui uma ação pelo nome. Os gatilhos ligados a ela ficam ociosos. |
| `trigger_upsert` | Cria ou atualiza um gatilho de intervalo: a cada `intervalMs` (mínimo 100) a ação ligada dispara na faixa das ações; um disparo durante uma execução pendente é pulado. A ligação com a ação é frouxa e por nome. |
| `trigger_delete` | Exclui um gatilho; a ação ligada fica intocada. |
| `alarm_upsert` | Cria ou atualiza um alarme: uma expressão de condição booleana, a prioridade (Crítica/Alta/Média/Baixa), os atrasos para ligar e para desligar, se o reconhecimento é exigido, e o estilo de anunciação. Salvar uma condição ou um tempo alterado repõe a máquina de estados em execução. |
| `alarm_delete` | Exclui um alarme pelo caminho; uma anunciação ativa é encerrada primeiro. |
| `logic_folder_upsert` | Cria, renomeia ou rearquiva uma pasta organizadora de uma seção (Variables, Alarms, Actions, Triggers; no máximo três níveis). Em Variables e Alarms, o caminho da pasta faz parte do endereço, então renomeações e movimentações reescrevem toda expressão, script, condição e vínculo de dashboard abaixo dela. |
| `logic_folder_delete` | Exclui uma pasta. Nada do que ela continha é destruído: itens e subpastas são rearquivados um nível acima e as referências são reescritas; uma colisão de nome no destino recusa a exclusão. |

## Logic: operação {#logic--operate}

Todas estas pegam o mesmo funil de escrita da Lógica que as páginas pegam e são registradas com a origem **MCP**. Uma escrita sai da Lógica para a fila de entrega do próprio equipamento, e quem espera a resposta é a chamada da ferramenta, então o que volta é o que aconteceu com o valor, e não apenas que ele foi enviado.

| Ferramenta | O que faz |
| --- | --- |
| `variable_write` | Escreve um valor numa variável de Memória (convertido para o tipo de saída dela, retido quando ela é retentiva). Variáveis de expressão são calculadas e recusam escritas. |
| `tag_write` | Escreve um valor de engenharia numa tag gravável: revertido pela cadeia de conversão da tag, convertido para o tipo do dispositivo e escrito no equipamento. A resposta traz o que a tag apresenta depois que a escrita passa: o valor, a qualidade, o `substitution` e o `communicating`, como o `tag_read` os informa, então um dispositivo que aceitou a escrita mas parou de responder às leituras não se confunde com um que ainda responde. Tags somente leitura e drivers somente leitura são recusados com o motivo. |
| `action_run` | Executa uma ação na faixa das ações e devolve o resultado e a duração dela. Uma ação desabilitada falha sem rodar. |
| `alarm_ack` | Reconhece um alarme, a resposta do operador; não faz nada quando nada está pendente. |
| `alarm_ack_all` | Reconhece todo alarme que aguarda uma resposta, como um item só da fila da lógica, com cada transição registrada. |

## Logs: leitura {#logs--read}

| Ferramenta | O que faz |
| --- | --- |
| `logs_read` | Lê o feed de log ao vivo de todo o programa (o mesmo do Console de [Eventos](events)), filtrado por severidade mínima (Debug/Information/Warning/Error, padrão Information), área (App/Server/Connector/Logic/Process/Dashboard/Agent/Licensing), componente e um trecho de texto contextual; devolve os acertos mais novos (padrão 100, no máximo 500). As ações de agente são registradas sob a área Agent. |
| `event_history_read` | Lê a linha do tempo persistente de eventos operacionais, que sobrevive a reinícios: transições de alarme, de ocorrência e de intertravamento. Filtre por tipo (Alarm/Occurrence/Interlock), por um período UTC inclusivo e por um nível (prioridade de alarme, severidade de ocorrência ou transição de intertravamento); do mais novo para o mais velho, padrão 100, no máximo 500. Estritamente somente leitura: nada consegue limpar nem excluir entradas do diário. |

## Process: leitura {#process--read}

| Ferramenta | O que faz |
| --- | --- |
| `process_models` | Lista os modelos do [Process](process) por inteiro: canais, grupos compartilhados, unidades com a ligação resolvida e o estado de execução, procedimentos, painéis, receitas, avaliações, ocorrências, mais a biblioteca global de modelos de documento de relatório. O mapa que um agente lê antes de iniciar qualquer coisa. |
| `process_runs` | Lista execuções, da mais recente para a mais antiga: id, nome, estado, veredito, o que rodou, quem a iniciou (Estação/Usuário/Automação/Agente), tempos e progresso de ciclos. Pode ser restrita às execuções ativas, buscada por um trecho do nome ou de qualquer valor dos metadados (um número de série, um lote) e limitada (padrão 50). |
| `process_run` | Lê o registro congelado completo de uma execução pelo id: instantâneo, metadados, critérios julgados com contagens de amostras, episódios e eventos de ocorrência, escritas de receita como executadas, comentários, e os artefatos congelados de relatório e etiqueta com as tentativas de impressão deles. Opcionalmente calcula a contagem de linhas e a faixa de tempo do datalog. |
| `process_samples` | Lê as amostras que uma execução gravou, enquanto grava ou depois de terminar. Um trecho de até 500 amostras vem como foi gravado: um ponto por amostra, com um valor por canal. Um mais longo vem resumido: a duração dele é dividida em 500 fatias iguais, e cada fatia traz o mínimo, o máximo e a média de cada canal, de modo que um pico sobrevive no máximo. A resposta diz qual dos dois casos é e, resumida, quanto dura cada fatia e quantas amostras cada uma junta. `fromUtc` e `toUtc` estreitam o trecho, e um trecho estreito o bastante volta como foi gravado; `channels` lê só os canais que nomeia. |
| `unit_status` | Relata o estado ao vivo de uma unidade: se ela está em execução (com a execução ativa) e o valor de engenharia atual atrás de cada canal, lido sem gravar. |

## Process: configuração {#process--configure}

| Ferramenta | O que faz |
| --- | --- |
| `process_view_configure` | Configura exatamente um painel de um modelo: o ícone desenhado ao lado dele e se ele fica na página View. Nada mais do agregado do Process é gravável por MCP; o resto é editado na página Process. |

## Process: operação {#process--operate}

Execuções iniciadas, encerradas ou comentadas por um agente gravam **Agente** como o autor, nunca o
operador que por acaso está autenticado na bancada.

| Ferramenta | O que faz |
| --- | --- |
| `process_snapshot` | Captura uma linha de datalog numa unidade fora de um procedimento. Toda chamada cria uma execução Instantânea nova e já concluída nos [Históricos](histories), sem avaliação (veredito None). |
| `process_evaluate` | Captura uma linha de datalog e a julga com uma avaliação; cria uma execução Instantânea concluída e devolve o veredito dela. |
| `process_recipe_apply` | Aplica uma receita Instantânea uma vez numa unidade, pelo funil de escrita e pelas travas de origem do Process. Comanda equipamento; não cria execução (as escritas são registradas). Receitas temporizadas são recusadas. |
| `process_start` | Inicia uma execução de procedimento numa unidade, com um objeto JSON para os campos de metadados que o procedimento pede. Todo valor enviado fica gravado, ou nada começa: um campo que o procedimento não pede, um valor para um campo sequencial (o aplicativo o compõe na partida) ou um campo nomeado duas vezes recusam a partida, assim como metadados obrigatórios ausentes ou inválidos, uma unidade já em execução ou um conflito de trava de canal compartilhado. Devolve o id da execução nova. |
| `process_stop` | Encerra uma execução em andamento: bloco de finalização, instantâneo congelado no histórico, veredito calculado. |
| `process_hold` | Pausa o perfil temporizado de uma execução no último setpoint; o datalog continua gravando. |
| `process_resume` | Retoma o perfil temporizado de uma execução pausada. |
| `process_abort` | Aborta uma execução a partir de Em execução ou Pausada: a finalização roda, o instantâneo é escrito, o estado vira Abortada e o veredito, NOK. |
| `process_comment` | Acrescenta um comentário com carimbo de tempo no arquivo de uma execução: uma nota na linha do tempo enquanto ela está ativa, uma nota pós-execução depois. |
| `process_report` | Gera (ou regera) o relatório em PDF de uma execução terminada e devolve o caminho do arquivo dele. Um modelo de documento nomeado, vindo da biblioteca global, prevalece sobre o configurado no procedimento; sem nenhum dos dois, vale o layout padrão com todas as seções. Recusada enquanto a execução está ativa. |
| `process_run_delete` | Exclui permanentemente uma execução gravada: o ponteiro dela no índice do histórico e o arquivo de banco por execução. Recusada enquanto ela está ativa; a configuração fica intocada. |

## Dashboard: configuração {#dashboard--configure}

Os nomes de papel que estas ferramentas leem e devolvem são em inglês em qualquer estação:
`Not signed in`, `Viewer`, `Operator`, `Maintainer` e `Developer`, quaisquer que sejam as
palavras que o operador lê na tela. `Admin` não entra na lista: ele sempre vê todos os
dashboards. Um papel que o administrador renomeou é nomeado pelo que ele digitou.

| Ferramenta | O que faz |
| --- | --- |
| `dashboard_list` | Lista dashboards (ou, nomeando um modelo, as telas daquele modelo): tamanho da grade, pasta, ícone, sinalizador de inicialização, visibilidade por papel e todo componente com a posição, a camada e o JSON de propriedades dele, mais toda rede de ligações persistida. Também devolve o catálogo de tipos de componente, com o tamanho padrão e o conjunto de propriedades padrão de cada tipo. |
| `dashboard_upsert` | Cria ou atualiza um dashboard pelo nome: tamanho da grade (um encolhimento que deixaria um componente órfão é rejeitado), pasta e ícone na coluna Visualização da página View, sinalizador de inicialização, visibilidade da barra de status em tela cheia, e visibilidade por papel. Nomear um modelo endereça as telas daquele modelo em vez disso. As páginas de dashboard abertas refletem a mudança ao vivo. |
| `dashboard_delete` | Exclui um dashboard e os componentes dele pelo nome; nomear um modelo exclui a tela daquele modelo em vez disso. |
| `component_upsert` | Acrescenta um componente por tipo (colocado na primeira célula livre, com o tamanho padrão do tipo, salvo instrução em contrário) ou atualiza um pelo id. A colocação precisa ficar dentro da grade; a sobreposição é permitida, com a camada z decidindo a ordem de desenho; o JSON de propriedades é o conjunto tipado do tipo. Nomear um modelo endereça as telas daquele modelo em vez disso, então uma tela criada lá pode ser diagramada aqui. |
| `component_delete` | Remove um componente pelo id; nomear um modelo endereça as telas daquele modelo em vez disso. |
| `connection_upsert` | Liga dois terminais de Símbolo com uma rede de ligações tipada, resolvendo tipo, papel e direção pelo catálogo de símbolos exatamente como o editor de canvas faz. Pontas que resolvem para tipos diferentes falham, a menos que uma ligação indefinida seja explicitamente permitida; um ancoradouro que já carrega uma ligação é rejeitado. Nomear um modelo endereça as telas daquele modelo em vez disso. |
| `connection_delete` | Remove uma rede de ligações pelo id e pela revisão esperada, então uma exclusão desatualizada é rejeitada em vez de atropelar uma edição mais nova; nomear um modelo endereça as telas daquele modelo em vez disso. |

## Interface: automatizar {#ui--automate}

Estas ferramentas conduzem a janela real da aplicação; elas existem para que um agente consiga verificar a
interface que o operador vê, e não uma simulação dela. As interações são despachadas ao
shell ao vivo, então a conduta pretendida é seguir cada gesto com um `ui_screenshot` e
observar o efeito, e acertos ambíguos voltam como listas de candidatos, em vez de um
clique adivinhado.

| Ferramenta | O que faz |
| --- | --- |
| `ui_state` | Relata o estado do shell: página ativa, páginas disponíveis, tema, tamanho e visibilidade da janela, e o endereço de loopback em que esta instância serve a interface dela. A chamada de orientação, antes de qualquer outra coisa. |
| `ui_navigate` | Ativa uma página do shell pelo nome estável dela, que é inglês em toda estação: `View`, `Process`, `Logic`, `Connector`, `Users`, `Validation`, `Events`, `Agent`, `Settings`, `Account`. O rótulo que o trilho de navegação desenha na língua da estação também é aceito. |
| `ui_screenshot` | Captura a janela como ela aparece na tela num arquivo PNG e devolve o caminho absoluto dele; restaura a janela primeiro quando ela está escondida na área de notificação. Pode capturar uma região de tela nomeada (uma área `data-doc-region` única e visível) em vez da janela inteira, e uma região ausente, escondida ou ambígua falha listando as regiões visíveis, em vez de cair em silêncio para uma captura completa. |
| `ui_scroll` | Rola a região de rolagem principal da página ativa até o topo, até o fim ou por páginas de viewport, devolvendo os deslocamentos, para que uma página longa possa ser varrida. |
| `ui_set_theme` | Aplica o tema da estação (Sistema, Claro ou Escuro): o tema em que a janela da estação desenha e que todo navegador que não escolheu o seu acompanha; um navegador que escolheu o seu fica com ele. Isso persiste exatamente como uma escolha feita pelas teclas de tema na janela da estação, então um agente bem-comportado restaura o valor original ao terminar. |
| `ui_resize` | Redimensiona a janela restaurada em unidades independentes de dispositivo, aparada no mínimo da janela; útil para auditar layouts compactos. |
| `ui_click` | Clica no botão, hiperlink, caixa de seleção ou interruptor visível cujo texto casa; caixas de seleção e interruptores são achados pelo rótulo do campo deles, e o resultado relata o estado em que ficaram. A ambiguidade devolve os candidatos, em vez de escolher um. |
| `ui_set_text` | Escreve um valor numa caixa de texto identificada pelo rótulo do campo dela, confirmando o vínculo como digitar faria. |
| `ui_select` | Seleciona um item pelo texto visível: um caminho separado por barras percorre uma árvore, expandindo pelo caminho; um segmento único também casa com itens de lista, de aba e de lista suspensa e com linhas de grade da página atual. |

## Backups: gerenciar {#backups--manage}

| Ferramenta | O que faz |
| --- | --- |
| `backup_create` | Cria um instantâneo online do banco de configuração na pasta de backups, com uma nota opcional. As execuções gravadas vivem fora da configuração e nunca são tocadas por backup nem por restauração. |
| `backup_list` | Lista os backups de configuração (nome do arquivo, hora de criação, tamanho, nota) mais qualquer restauração já agendada. |

Deliberadamente **não existe ferramenta de excluir backup**: a retenção é só do operador, na
página [Backups](settings-backups).

## Backups: restaurar {#backups--restore}

| Ferramenta | O que faz |
| --- | --- |
| `backup_restore` | Agenda um backup para substituir a configuração atual no **próximo** início da aplicação. Nada muda na aplicação em execução e a ferramenta nunca a reinicia; a configuração que será substituída recebe um instantâneo automático antes, e o operador pode cancelar a restauração pendente pelas Configurações até o reinício. Recusada enquanto uma gravação está ativa. |

## Configurações: gerenciar {#settings--manage}

| Ferramenta | O que faz |
| --- | --- |
| `settings_read` | Lê as preferências de exibição e de ciclo de vida da estação: formatos de data, hora e número, casas decimais, tema, e os sinalizadores de fechar para a área de notificação e de relatório de falha. |
| `localization_set` | Atualiza as preferências de exibição (parcial: os parâmetros omitidos ficam). Só exibição: o armazenamento, a entrada e saída dos drivers e as gravações usam sempre o formato invariante. |
| `asset_list` | Lista os recursos do usuário (imagens, ícones, cores) com ids, valores e caminhos. |
| `asset_import` | Importa um PNG ou JPG de um caminho de arquivo local para a biblioteca de recursos que a aplicação é dona e devolve o id do recurso novo. Os bytes são copiados, então o arquivo de origem pode ser movido depois. |
| `symbol_validate` | Valida conteúdo de símbolo em linha (SVG cru ou um pacote v2) sem persistir nada: uma execução em seco da importação exata, devolvendo erros, avisos do higienizador e um resumo do que foi reconhecido. A descrição da ferramenta carrega o [contrato de símbolo portátil](ganter-symbols) completo. |
| `symbol_import` | Importa conteúdo de símbolo em linha como um recurso de símbolo de usuário novo e devolve o id dele e a referência `user:<guid>`. Sempre cria um recurso novo; um nome que colide recebe sufixo automático. |

## Relatos: rascunho {#reports--draft}

| Ferramenta | O que faz |
| --- | --- |
| `report_draft` | Abre o [formulário de relato](account-feedback#a-report-drafted-by-an-agent) na janela da estação, já preenchido com o que o agente escreveu: `kind` (`DriverRequest`, `Bug` ou `Suggestion`), `summary` (uma linha de no máximo 120 caracteres; uma mais longa é recusada, não cortada) e `details` (opcional). Como o botão de relatar da barra de título, primeiro captura a janela e oferece a captura com o relato, marcada. Responde na hora que o formulário está aberto e que nada foi enviado. |

A ferramenta nunca envia. A pessoa na estação lê o relato, corrige se quiser e pressiona Enviar; o desfecho aparece na barra de status da estação e não volta para o agente. Enquanto esta área está ligada, o servidor pede a todo agente que ofereça um relato quando a pessoa precisa de um driver que o Ganter Lab não tem, quando uma chamada falha de um jeito que parece defeito do programa, ou quando a pessoa pede uma melhoria, e as descrições de `driver_capabilities`, `device_upsert` e `device_discover` dizem o mesmo.

Ela recusa com um `reason`, e então não abre nem captura nada:

| `reason` | Quando |
| --- | --- |
| `not_permitted` | O papel autenticado na estação não tem Enviar relatos à Ganter. |
| `no_station_window` | A estação não tem janela própria onde abrir o formulário: um host que serve suas páginas só para navegadores. |
| `no_credential` | A sessão não consegue enviar: o perfil de demonstração, conectado ou não, ou uma entrada na conta Ganter da estação que não guarda credencial. |
| `form_busy` | O formulário de relato está aberto na estação, ou um relato está sendo capturado ou enviado. |
| `draft_in_progress` | O formulário tem um relato que uma pessoa está escrevendo. Já um rascunho anterior do agente que ninguém mudou é substituído. |

Uma estação que não está conectada a uma conta Ganter não é recusada: o formulário abre e diz que o
relato vai sem conta, então a Ganter não tem como responder.

Como toda ferramenta que muda alguma coisa, ela responde `Runtime stopped` enquanto o runtime está parado.