Adendo de API e Plataformas OpenSprinklerPro

Este documento contém a descrição técnica de endpoints HTTP adicionais adicionados após as especificações básicas de hardware.

The OpenSprinklerShop firmware, including OpenSprinklerPro, uses its own firmware version numbering independent of upstream OpenSprinkler releases. Current OpenSprinklerShop firmware version: 2.4.0(228).

Correções de Plataforma

Endpoint	Plataformas Suportadas	Notas
`/uc`, `/uu`, `/us`, `/ub`	ESP32, ESP8266	Endpoints de atualizações online (FOTA) e backups completos de configuração. Não disponíveis em builds OSPi/Linux.
`/sx`	ESP32, ESP8266, OSPi	Backups de configurações de sensores.
`/jw`	ESP32, ESP8266, OSPi	Relatórios mensais de consumo e fluxo de água.
`/tg`, `/tl`, `/ta`, `/tc`, `/tx`	ESP32	Gerenciamento de certificados HTTPS e ACME/Let's Encrypt.
`/rk`, `/rp`, `/ru`	ESP32 com `ENABLE_RAINMAKER`	Status e provisionamento na nuvem ESP RainMaker.
`/jm`, `/mm`	ESP32 com `ENABLE_MATTER`	Emparelhamento do protocolo Matter.
`/bd`, `/bs`, `/bc`	ESP32 com `OS_ENABLE_BLE`	Controles de scanners Bluetooth Low Energy (BLE).
`/ir`, `/iw`, `/zj`, `/zs`, `/zg`, `/zd`, `/zo`, `/zc`	ESP32-C5 com suporte Zigbee/IEEE 802.15.4	Chaveamento de rádio e comunicação do gateway/cliente Zigbee.

Atualização Online e Backup

Endpoint	Objetivo
`GET /uc?pw=...`	Verifica o manifesto de atualização e relata se um firmware mais recente está disponível.
`GET /uu?pw=...`	Inicia o processo de atualização do firmware. Parâmetros avançados permitem substituir URLs e hashes: `zu`, `mu`, `fu`, `zs`, `ms`; `vt` seleciona `zigbee` ou `matter`.
`GET /us?pw=...`	Lê o status da atualização e o progresso.
`GET /ub?pw=...`	Exporta a configuração completa do controlador para backup antes da atualização.

Certificados HTTPS e ACME

Endpoint	Objetivo
`GET /tg?pw=...`	Lê o tipo de certificado ativo, assunto, emissor e validade.
`POST /tl?pw=...`	Envia um certificado personalizado PEM e chave privada. Reinicia em seguida.
`GET /ta?pw=...`	Lê a configuração e o status do ACME (Let's Encrypt).
`POST /tc?pw=...`	Salva as configurações do ACME e solicita um certificado opcionalmente.
`GET /tx?pw=...`	Exclui dados do ACME e retorna para o certificado interno padrão.

RainMaker e Matter

Endpoint	Objetivo
`GET /rk?pw=...`	Lê o status do ESP RainMaker. Parâmetros opcionais `reset_mapping=1` ou `factory_reset=1` realizam ações de manutenção.
`GET /rp?pw=...&uid=...&key=...`	Inicia o provisionamento do RainMaker.
`GET /ru?pw=...`	Desvincula a conta RainMaker e aciona comportamentos de redefinição / reinicialização.
`GET /jm?pw=...`	Lê o estado de comissionamento do Matter, URL do QR Code e código manual de pareamento.
`GET /mm?pw=...&t=300`	Abre a janela de pareamento do Matter; `t` é o tempo limite opcional em segundos, máximo `900`.

Uso de Água e Sensores

Endpoint	Objetivo
`GET /jw?pw=...`	Lê o uso mensal de água: taxa de pulso, mês atual e registros salvos.
`GET /sf?pw=...`	Lista os tipos de sensores suportados pela build atual.
`GET /sx?pw=...`	Exporta ou importa apenas a configuração de sensores.
`GET /mc`, `/ml`, `/mt`	Configura, lista e descobre tipos de monitoramento.

API de sensores expandida (compatível com o firmware oficial 2.2.1(5))

O firmware oficial OpenSprinkler 2.2.1(5) introduziu uma API "Expanded Sensor". O firmware OpenSprinklerShop a partir da versão 2.4.0(228) disponibiliza os mesmos endpoints como fachada sobre o seu próprio sistema de sensores: existe apenas um armazenamento de sensores, o uuid oficial é o número de sensor OpenSprinklerShop nr, e o app oficial OpenSprinkler assim como clientes de terceiros escritos para a API oficial funcionam sem alterações. Os endpoints OpenSprinklerShop (/sl, /sc, /so, /se, ...) continuam a trabalhar sobre os mesmos dados.

Disponível em ESP32, ESP8266 e OSPi. As chaves dos endpoints têm três letras.

Endpoint	Objetivo
`GET /jsn?pw=...`	Lista os sensores com a última leitura (`sn[]`, `count`). Chaves: `uuid`, `name`, `type`, `unit`, `flag`, `status`, `interval` (minutos), `min`, `max`, `value`, `extra`.
`GET /csn?pw=...&uuid=-1&type=...`	Adiciona (`uuid=-1` ou `sid=-1`) ou modifica um sensor. Parâmetros comuns: `name`, `min`, `max`, `interval`, `unit`, `flag`. Parâmetros por tipo: `children`/`action` (Aggregate), `pin`/`subtype`/`scale`/`offset`/`points` (ADS1115), `action` (Weather), `metric` (System Internal), `input` (Onboard Digital), `ntype` (tipo 5, veja abaixo).
`GET /dsn?pw=...&uuid=...`	Exclui um sensor; `uuid=-1` exclui todos os sensores.
`GET /jsd?pw=...`	Descrições de sensores para editores orientados por esquema: `sensors[]` (índice = `type`), `units[]`, `enums`, `as`, `flags`.
`GET /jsl?pw=...`	Log de sensores: `[[uuid,ts,value],...]`; `fmt=csv` ou `fmt=binary`; filtros `uuid`/`sid`, `before`, `after`, `count`, `cursor`; `page=1` ativa a paginação por slot com os cabeçalhos de resposta `X-OS-*`.
`GET /dsl?pw=...&uuid=...`	Exclui os registros de log de um sensor (`uuid=-1`: log inteiro). `page=1` devolve o objeto JSON de progresso; a exclusão termina em uma única requisição (`done=1`).
`GET /jpa?pw=...`	Fatores de ajuste de clima (`wa`), sensor (`sa`) e total (`ta`) por programa, mais `maxrt`.
`GET /jp`	Cada entrada de programa carrega o objeto de ajuste de sensor `{flag,uuid,splits[]}` como 8º elemento (`{}` quando não há).
`GET /cp?...&snadj=flag,uuid,x0,y0,...`	Define o ajuste de sensor do programa; `snadj=0,0` o remove. `v` continua obrigatório.
`GET /mp?...&usa=0\|1`	Início manual de programa com (`1`) ou sem (`0`) o ajuste de sensor. Sem `usa` o comportamento OpenSprinklerShop é mantido e o ajuste é aplicado.

Mapeamento de tipos (/jsn.type, índice de /jsd.sensors):

type	Nome oficial	Sensores OpenSprinklerShop
0	Aggregate	Grupos de sensores MIN/MAX/AVG/SUM e os novos MEDIAN (1004) / RANGE (1005). `children` são os membros do grupo; `scale`/`offset` dos filhos devem ser `1`/`0`.
1	ADS1115	Tipos Analog Sensor Board (10, 11, 12 por partes, 15-18, 30-32, 49) e tipos ADC OSPi (50-53). `pin` 1-16 = endereço da placa 0x48-0x4B x canal 0-3. Subtipos: 0 linear, 1 por partes (novo tipo 12), 10/11 SMT50, 12/13 SMT100 analógico, 15 VH400, 16 THERM200, 17 AquaPlumb. `scale`/`offset` são aplicados após a conversão.
2	Weather	Sensores do serviço meteorológico (101-110); `action` indexa `enums.WeatherAction`.
3	System Internal	Memória livre (`metric` 0), armazenamento livre (1), temperatura da CPU (3).
4	Onboard Digital	Novo tipo 56: estado com debounce de SN1 (`input` 0) ou SN2 (`input` 1).
5	Sensor OpenSprinklerShop	Todos os demais tipos (RS485, MQTT, Zigbee, BLE, FYTA, Gardena, remoto, medidor de fluxo, ...). `extra.ntype` é o tipo OpenSprinklerShop; as configurações específicas do tipo são editadas com `/sc`.

Notas de comportamento:

min/max limitam a saída do sensor quando enviados com /csn (guardados como cmin/cmax/clamp em sensors.json); status reporta os bits 3/4 quando um valor foi limitado. Sensores criados com /sc não são limitados e reportam a sua faixa natural.
interval é em minutos; o ri OpenSprinklerShop é em segundos e é arredondado para minutos inteiros em /jsn.
Subtipos pré-definidos reportam a sua unidade nativa; outra unidade do mesmo grupo (p. ex. Fahrenheit) é rejeitada porque o firmware não converte unidades.
Ajustes de programa: uma curva snadj com dois pontos torna-se um ajuste PROG_LINEAR, um degrau de dois pontos torna-se PROG_DIGITAL_MIN, outras curvas usam o novo tipo de ajuste PROG_PIECEWISE (5). /jp reporta o primeiro ajuste de um programa; ajustes adicionais definidos com /sb continuam a ser aplicados pelo agendador.

A referência legacy completa da API pode ser encontrada em Referência da API do Firmware 2.2.1.