Monitor dos Rios — Alto Paraíba do Sul (SP)

Painéis em tempo real do nível e da chuva de cada rio, com histórico, avisos e modo TV. Um mesmo código atende várias bacias; cada uma tem sua pasta com configuração e histórico.

Bacia	Cidade de referência	Painel
Rio Paraitinga (e afluentes)	São Luiz do Paraitinga	https://dimasdecampos.github.io/monitora-rio/paraitinga/
Rio Paraibuna	Natividade da Serra	https://dimasdecampos.github.io/monitora-rio/paraibuna/
Rio Ribeira de Iguape	Eldorado	https://dimasdecampos.github.io/monitora-rio/ribeira/ (fora da página inicial)

Uma bacia com "oculta": true em public/bacias.json tem painel publicado, histórico e avisos como as outras, mas não aparece na página inicial nem nos atalhos do app (só por link direto).

Página inicial: https://dimasdecampos.github.io/monitora-rio/

Idealização e criação: Dimas de Campos. Desenvolvido em parceria com IA (Claude, da Anthropic).

⚠️ Aviso importante. Este é um projeto independente. Os dados, cotas, impactos e previsões NÃO foram validados pela Defesa Civil nem por nenhum órgão oficial. As informações vêm de fontes públicas e de cálculos próprios, podem conter erros, atrasos ou falhas de transmissão. Qualquer uso é de responsabilidade própria. Em situação de risco, siga sempre as orientações da Defesa Civil (199) e dos Bombeiros (193).

---

Sumário

0. Bacias e como adicionar um rio
1. O que o painel mostra
2. Fontes de dados
3. Cotas e classificação do nível
4. Réguas da cidade: conversão e preenchimento
5. Qualidade dos dados (filtros)
6. Previsão de cheias (experimental)
7. Rio acima e chuva na bacia
8. O que alaga, memória e estatísticas
9. Avisos
10. Atualização automática
11. Estrutura do projeto
12. Rodar e atualizar

---

Bacias e como adicionar um rio

Cada bacia é uma pasta em public/ listada em public/bacias.json. O painel e o modo TV são os mesmos para todas (pasta modelos/); o que muda é o config.json da bacia. Cartões sem dados para a bacia (previsão, mapa do que alaga, represamento) somem sozinhos.

O Paraitinga nasce na Serra da Bocaina (Areias); o Paraibuna, no sul de Cunha (Serra do Mar). Os dois se encontram na represa de Paraibuna e formam o Paraíba do Sul.

	Paraitinga	Paraibuna
Régua principal	Passarela (SP Águas), cotas oficiais	Fazenda Palmeiras, Natividade (ANA), cotas provisórias
Rio acima	Cunha, Lagoinha ×2, Estrada do Ribeira (3 a 20 h)	Ponte Alta, na serra (~4 h, de 3 a 7 h)
Outras réguas	ANA e CESP na cidade, Jacuí, Chapéu ×2	— (a represa fica muito abaixo de Natividade e não entra)
Previsão de cheias	sim (modelo próprio)	sim (com Ponte Alta; bom só para poucas horas)
O que alaga / memória	sim	ainda não
Chuva na bacia (regiões)	Cunha, Lagoinha, cidade, Chapéu	Cabeceiras em Cunha (só previsão), serra, Natividade
Chuva × subida do rio	sim (ERA5 desde 2018)	sim (ERA5 desde 2015)
Modo TV: chuva prevista	Serra da Bocaina e São Luiz	Cunha e Natividade
Histórico	desde 2018 (Passarela)	desde 2015 (Natividade)

Para adicionar um rio:

1. Crie public/<id>/config.json (copie o do Paraibuna, que é o mais simples). Campos principais: id (igual ao nome da pasta), rio, cidade, principal (régua de referência), reguas_cidade, rios[].estacoes[] (código, fonte spaguas ou ana, id_nivel/id_chuva da SP Águas, coordenadas, cotas_cm, curto, rio_acima com ordem e horas_ate_cidade) e regioes_chuva. Opcionais: reserva, conversoes, previsao, impactos, represamento, estatisticas, textos, avisos, pluviometros (estações só de chuva, com id_chuva), pontos_chuva (lugares sem pluviômetro, com codigo pt-…: uma região de chuva com esse código mostra só a previsão), tv_chuva (até 2 pontos com a chuva prevista no modo TV) e chuva_era5.
2. Acrescente a bacia em public/bacias.json.
3. Baixe o histórico: python scripts/coletar.py --bacia <id> --desde 2024-01, a chuva estimada nos pontos (python scripts/baixar_chuva_era5.py --bacia <id>) e depois python scripts/estatisticas.py --bacia <id>.
4. Confira com python scripts/montar_site.py (aponta erros no config) e python server.py. Ao enviar ao GitHub, o site e os avisos passam a incluir a bacia.

Os ids das réguas da SP Águas estão em https://cth.daee.sp.gov.br/sibh/api/v2/stations (campo id; o station_type diz se é régua ou pluviômetro).

O que o painel mostra

Uma única página, pensada primeiro para o celular:

Parte	O que mostra
Nível agora	Última leitura da régua escolhida, situação (normal, atenção, alerta, emergência, transbordamento), tendência em cm/h e comparação com o normal da época
Números rápidos	Chuva 24 h e 7 dias, vazão, pico do ano, dias acima da atenção
Gráfico "Últimos dias"	Nível medido + linha de previsão de 7 dias com faixa de 8 em 10 chances, nível típico da época, chuva medida e prevista (na régua ou na bacia, por região); zoom e rolagem pela barra de navegação
Gráfico "Comparar anos"	Um ano por linha no período escolhido (ano, chuvoso, verão, hidrológico), mediana e faixa dos anos completos
Rio acima	Réguas de Cunha → Lagoinha → Estrada do Ribeira → cidade, com tempo típico de chegada da água e indicador de represamento pelo Ribeirão do Chapéu
Previsão 48 h	Chance de chegar a cada cota oficial, pico provável e chuva prevista por dia
O que alaga	Escada de níveis com impactos registrados e mapa do centro
Ano a ano, maiores cheias, mapa mensal	Histórico por ano e mês
Visões extras (fechadas)	Chuva × subida do rio, quando o rio enche, tempo para baixar, permanência, memória das cheias
Situação das fontes	Se cada fonte está transmitindo

Modo TV (tv.html): tela cheia para televisão ou monitor (Defesa Civil, prefeitura, comércio). Mostra o nível em letras grandes com a cor da situação, a régua com as cotas, as últimas 48 h, as réguas rio acima e a chuva medida e prevista. Atualiza sozinho a cada 5 min, mantém a tela acesa e esconde o cursor. Tecla F liga a tela cheia; tv.html?tema=light usa o tema claro.

Cartões menos usados começam fechados para economizar espaço; o navegador lembra o que cada visitante abriu.

Fontes de dados

Fonte	O que vem	Frequência	Acesso
SP Águas — SIBH	Nível e chuva das réguas da SP Águas (Passarela, Estrada do Ribeira, Lagoinha ×2, Cunha, Rio Jacuí, Ribeirão do Chapéu ×2, Ponte Alta) e cotas oficiais	10 min	API pública, direto no navegador (máx. 10 estações por chamada)
ANA — telemetria	Réguas da cidade (58040000), CESP (58041000) e Fazenda Palmeiras (58068000)	15 min	Web service público, direto no navegador
Open-Meteo	Chuva prevista (8 dias), 31 cenários GFS, chuva histórica ERA5 e previsões arquivadas	horária	API pública
OpenStreetMap	Mapa e coordenadas das ruas	—	Tiles públicos
Relatório SGB/CPRM 2022 e notícias	Cheias históricas e impactos	—	Links no painel

A estação padrão é a Passarela (SP Águas), no centro, que tem cotas oficiais.

Cotas e classificação do nível

Definição oficial, segundo o Manual de Operação das Salas de Situação do Estado de São Paulo (ANA/ProGestão):

Situação	Significado oficial	Cor
Normal	Abaixo da cota de atenção	verde
Atenção	Risco significativo de evento adverso, mas ainda incerto	amarelo
Alerta	Perigo iminente ou previsível a curto prazo; Defesa Civil de prontidão	laranja
Emergência	Situação crítica que demanda ação imediata	vermelho
Transbordamento (extravasamento)	Rio acima das margens, transbordando	vermelho escuro

Cotas usadas (em metros, na régua de cada estação):

Estação	Atenção	Alerta	Emergência	Transb.	Origem
Passarela (SP Águas)	1,92	2,32	2,72	3,12	Oficiais (SIBH)
Régua da ANA na cidade	2,73	3,16	4,00	4,41	Atenção e alerta oficiais (SIBH); emergência e transbordamento convertidos da Passarela
Régua da CESP	3,04	3,48	3,91	4,35	Convertidas da Passarela (aproximadas)
Lagoinha, Cunha, Rio Jacuí, Chapéu, Ponte Alta	—	—	—	—	Oficiais (SIBH), ver public/<bacia>/config.json
Fazenda Palmeiras (ANA)	2,50	3,50	4,50	—	Provisórias, pelo histórico

As duas tabelas oficiais da cidade não batem entre si: a atenção da régua da ANA (2,73 m) equivale a ~1,48 m na Passarela, cuja atenção oficial é 1,92 m. Confirme com a Defesa Civil qual tabela é usada nas sirenes.

Outras regras de classificação:

• Tendência: variação na última hora — subindo (≥ 2 cm/h), subindo rápido (≥ 10 cm/h), baixando (≤ −2 cm/h), estável.
• Leitura atrasada: acima de 1 h (SP Águas) ou 2 h (ANA) sem leitura nova, o painel avisa e sugere trocar para outra régua da cidade.
• "Acima do normal": comparação com a mediana do nível médio diário nos mesmos ±7 dias do ano, nos anos anteriores.

Réguas da cidade: conversão e preenchimento

As réguas da Passarela, da ANA e da CESP medem o mesmo trecho do rio com zeros diferentes:

• ANA ≈ 123,4 + 1,017 × Passarela (cm), erro típico de 3 a 7 cm (conferido em 2026).
• CESP ≈ 95 + 1,09 × Passarela (cm), com dados de 2026 (antes disso a relação varia).

Quando uma régua da cidade fica sem transmitir, os dias que faltam no histórico são completados com a outra convertida (Passarela ⇄ ANA) e marcados como "completados". Exemplo: a Passarela parou de 10/09 a 15/09/2026 e o preenchimento revelou uma cheia (~2,55 m em 12/09). O gráfico de "Últimos dias" (ao vivo) não é preenchido.

Qualidade dos dados (filtros)

Descartados automaticamente (coletor, painel ao vivo e robô de avisos):

• nível negativo;
• leitura isolada que sobe e desce mais de 1 m entre vizinhas próximas;
• salto de mais de 3 m em até 2 h que volta ao nível anterior (sensor travado);
• valor fixo repetido por 6+ leituras logo depois de um salto de mais de 2 m (régua voltando de falha, ex.: 10,31 m no Ribeirão do Chapéu em jul/2024);
• ao vivo: salto de mais de 3 m em até 6 h;
• chuva negativa, mais de 50 mm em 10 min ou mais de 150 mm/h (inclui o contador acumulado do pluviômetro da Passarela de dez/2021 a out/2023);
• vazão 9999 (código de "sem dado" da ANA).

Anos com falhas aparecem como parciais e podem subestimar picos.

Previsão de cheias (experimental)

Chance de chegar a cada cota em 48 h — regressão logística na régua da Passarela (scripts/modelo_cheias/passarela.py, exportar_passarela.py):

• entradas: nível atual, chuva média na bacia (São Luiz, Lagoinha, Cunha, cabeceiras) nas últimas 24 h e 72 h, chuva dos 30 dias anteriores (solo encharcado), chuva prevista para 48 h (média de 31 cenários GFS) e, quando transmitem, a subida da régua de Cunha e a chuva medida no pluviômetro de Barro Vermelho (Lagoinha, 2E-050) nas últimas 6, 12, 24 e 72 h. O painel usa a versão mais completa que estiver transmitindo (BP: Cunha + pluviômetro; B; P; A: só nível e chuva estimada);
• o modelo final é a média de 5 treinos (um treino só variava muito, de 7 a 12 cheias avisadas com 12 h, só pelo sorteio);
• treino 2018–2023; teste fev/2024–out/2026 com a previsão do tempo real da época: das 20 vezes em que a Passarela passou da atenção, avisou (chance ≥ 30%) 16 com 6 h de antecedência, 12 com 12 h e 14 com 24 h (com o pluviômetro: 17, 12 e 14). Com Cunha e o pluviômetro transmitindo juntos, avisou 14 de 15 com 6 h, 14 com 12 h e 11 com 24 h (só com Cunha: 13, 11 e 9), com o mesmo número de dias com aviso sem cheia (22 de 56). Correção de 27/10/2026: a contagem anterior ("7 de 8") deixava de fora 2/3 das cheias por um erro no casamento dos horários;
• por que o pluviômetro: a chuva estimada da ERA5 (quadrados de ~30 km) vê metade ou menos dos temporais: em 26/01/2026 Cunha mediu 146 mm em 48 h e a ERA5 deu 24 mm. Testados em out/2026, sem ganho: mais anos (régua da CESP desde 2015), chuva da ERA5 separada por região com o tempo de viagem e chuva da ERA5 em Areias e na nascente. O pluviômetro de Barro Vermelho tem dados desde 2011 (com falhas: 2015 zerado, partes de 2018–2020); o histórico antigo vem de scripts/modelo_cheias/baixar_pluviometro.py;
• o aviso costuma vir 6 a 12 h antes; tempestades localizadas na serra podem escapar.

Paraibuna: previsão de 48 h com a régua de Ponte Alta. O mesmo método, treinado para Natividade (scripts/modelo_cheias/treinar_bacia.py --bacia paraibuna), com a subida de Ponte Alta em 6 h e 12 h (histórico dela desde dez/2015). Teste fev/2024–out/2026 com a previsão do tempo real: das 20 vezes em que Natividade passou da atenção, avisou 13 com 3 h de antecedência, 8 com 6 h, 5 com 12 h e 5 com 24 h; 32 dos 58 dias com aviso não tiveram cheia. Só com nível e chuva eram 7, 6, 7 e 8, com 56 de 76 dias sem cheia. O ganho é nas primeiras horas (a água leva de 4 a 7 h da serra até Natividade); com mais antecedência tudo depende da chuva prevista, que quase não vê os temporais da Serra do Mar (em 21–22/02/2026, 118 mm no pluviômetro de Natividade e ~11 mm na ERA5). Testados em out/2026, sem ganho que valesse: chuva separada por região, pluviômetros (Natividade e Ubatuba) no lugar da ERA5 e chuva estimada e prevista em Ubatuba e Paraty.

Linha de previsão (7 dias) — uma regressão por prazo (6 h a 7 dias) para a variação do nível; a faixa azul é o intervalo de 8 em 10 chances, tirado dos erros do próprio modelo. Erro médio com previsão real: 10 cm em 1 dia, 15 cm em 2 dias, 21 cm em 7 dias ("fica como está": 13, 20 e 29 cm). A faixa acertou 81–87% das vezes. Não acerta bem o tamanho de subidas grandes.

Depois de 7 dias o gráfico não prevê: previsão de chuva para semanas ou meses não é confiável o bastante. O gráfico vai só até o fim da previsão.

Rio acima e chuva na bacia

Tempo típico até a água chegar à Passarela (correlação das subidas, 2024–2026): Estrada do Ribeira 3 h, Lagoinha–Barro Vermelho 9 h, Lagoinha–Jusante do Jacuí 11 h, Cunha ~20 h. O cartão avisa quando alguma régua sobe ≥ 10 cm em 3 h.

Represamento pelo Ribeirão do Chapéu (deságua logo abaixo da cidade; agravou 1996 e 2010): alto quando o Chapéu passa da atenção e a Passarela está em alerta; atenção quando o Chapéu passa da atenção ou sobe rápido com a cidade alta.

Chuva na bacia (botão no gráfico): barras empilhadas por região — Cunha (Est. de Cunha e Rio Jacuí), Lagoinha (2 réguas), Perto da cidade (Estrada do Ribeira e Passarela) e Ribeirão do Chapéu (2 réguas). Cada região é a média dos seus pluviômetros (SP Águas) e a barra é a soma das regiões; no futuro, previsão Open-Meteo nos mesmos pontos. A legenda (recolhida) lista as regiões da que mais choveu para a que menos; tocar liga ou desliga a região.

O que alaga, memória e estatísticas

• public/paraitinga/impactos.json: níveis da Passarela ligados a impactos registrados (3,95 m: ruas da beira do rio, 2021; ~4,60 m: ruas do centro, 2024 — aproximado; 5,36 m: Praça da Matriz, 2022), pontos no mapa e linha do tempo das cheias desde 1863.
• public/<bacia>/estatisticas.json (gerado por scripts/estatisticas.py, para a régua principal de cada bacia): frequência de cheias por mês, tempo para baixar depois do pico e, no Paraitinga, chuva × subida do rio por umidade do solo.

Avisos

• No aparelho (Web Push): botão "Avisar neste aparelho". O celular se inscreve na bacia (tabela monitora_push no Supabase, projeto estoura; SQL em scripts/supabase/monitora_push.sql) e o robô manda a notificação mesmo com o app fechado. Precisa dos segredos VAPID_PRIVATE_KEY e MONITORA_PUSH_TOKEN no GitHub. Sem suporte a push (ex.: iPhone sem o app instalado), o painel avisa enquanto estiver aberto. Para desligar, use o rodapé.
• Robô de avisos: scripts/alertas.py roda a cada ~10 min (.github/workflows/alertas.yml) para todas as bacias. Avisa quando a régua principal muda de cota, a água sobe ≥ 20 cm em 3 h rio acima (com tempo de chegada), há risco de represamento ou a previsão passa de 30%. Cada tipo de aviso se repete no máximo a cada 6–12 h. Sem nenhum canal configurado, roda em modo de teste e só registra as mensagens. Um aviso só conta como dado quando chega por pelo menos um canal: se todos falharem, ele é tentado de novo na próxima rodada, e a rodada fica vermelha no GitHub (que manda e-mail). No Telegram, as mensagens vão em HTML (nomes com _ ou * não quebram o envio).
• Régua sem dados: se a régua principal ficar sem leitura por mais que o atraso aceitável (atraso_max_horas + 1 h) em duas rodadas seguidas, sai um aviso "régua sem dados" com a última leitura. Ele se repete a cada 24 h, ou a cada 6 h se o rio estava em alguma cota. Quando a régua volta, sai "voltou a transmitir".
• Vigia do robô (healthchecks.io, grátis): avisa por e-mail se o robô parar de rodar ou der erro. Crie uma conta, um check com período de 10 min e tolerância (grace) de 30 min, e copie o endereço de ping (https://hc-ping.com/...) para o segredo HEALTHCHECK_URL no GitHub. A cada rodada o robô faz um ping; se alguma bacia der erro, o ping vai para /fail.
• App ntfy (recomendado): notificação no celular com som de alarme, grátis e sem cadastro. Crie no GitHub o segredo NTFY_TOPIC com um nome difícil de adivinhar (ex.: rio-024906fe); cada bacia avisa no tópico <NTFY_TOPIC>-<bacia> (ex.: rio-024906fe-paraitinga). Instale o app ntfy, toque em + e assine os tópicos das bacias que quiser. Quem souber o nome do tópico recebe os avisos.
• Telegram: crie um bot com @BotFather e um canal por bacia (o bot como administrador). No GitHub, segredo TELEGRAM_TOKEN; no da bacia, (o segundo mostra o botão do canal no painel).

Atualização automática

Workflow	Quando	O que faz
site.yml	todo dia às 06:20 e a cada push	baixa o mês atual e o anterior de todas as bacias (ANA e SP Águas), gera os resumos diários (com preenchimento), atualiza as estatísticas, monta o painel em cada bacia e publica no GitHub Pages
alertas.yml	a cada ~10 min	verifica todas as bacias e envia os avisos (ntfy, Telegram, WhatsApp)

O GitHub pode atrasar tarefas agendadas em alguns minutos.

Estrutura do projeto

modelos/                   painel e modo TV (iguais para todas as bacias)
  painel.html              painel (HTML + CSS + JS, sem build)
  tv.html                  modo TV
  manifest.webmanifest     base do app instalável
public/                    site publicado no GitHub Pages
  index.html               página inicial: escolhe o rio
  manifest.webmanifest     app da Play Store (atalhos atualizados por montar_site.py)
  privacidade.html         política de privacidade (site e app)
  bacias.json              lista das bacias
  sw.js, icones/           app instalável (vale para todas)
  <bacia>/                 paraitinga/, paraibuna/ …
    config.json            estações, cotas, conversões, regiões de chuva, o que a bacia tem
    historico/<estação>/   AAAA-MM.json (leituras) e diario.json (resumo diário)
    estatisticas.json      sazonalidade, recessão (e chuva × subida, se houver)
    modelo_cheias.json     só Paraitinga: pesos da previsão e resultados dos testes
    impactos.json          só Paraitinga: o que alaga, mapa, memória das cheias
    index.html, tv.html, manifest.webmanifest   gerados por montar_site.py (fora do git)
scripts/
  comum.py                 lista de bacias, configuração, consulta à ANA
  coletar.py               coleta ANA + SP Águas, filtros, resumo diário e preenchimento
  estatisticas.py          gera estatisticas.json de cada bacia
  alertas.py               robô de avisos (ntfy, Telegram, WhatsApp)
  montar_site.py           copia os modelos para cada bacia e confere as configurações
  baixar_chuva_era5.py     chuva estimada (ERA5) nos pontos de uma bacia, para chuva × subida
  modelo_cheias/           previsão do Paraitinga: chuva (ERA5, previsões arquivadas), treino e testes
android/                   gera o app Android (app.json + gerar.js), usado pelo workflow app-android.yml
playstore/                 publicar na Play Store: passo a passo (LEIAME.md), textos, imagens
  dominio/                 arquivos do repositório dimasdecampos.github.io (verificação do app)
server.py                  servidor local para testes (serve os modelos direto)

Rodar e atualizar

python server.py                                  # site em http://localhost:8000
python scripts/coletar.py                         # todas as bacias: mês atual e anterior
python scripts/coletar.py --bacia paraitinga --desde 2018-01 --estacao sp664   # recarrega uma estação
python scripts/estatisticas.py                    # recalcula as estatísticas
python scripts/montar_site.py                     # monta as páginas e confere os config.json
python scripts/alertas.py --bacia paraibuna       # testa os avisos (sem canais: só mostra)

Para refazer os modelos, siga a ordem descrita em scripts/modelo_cheias/exportar.py e depois rode baixar_pluviometro.py (uma vez) e exportar_passarela.py (~15 min). Só usa a biblioteca padrão do Python.

Limitações conhecidas

• Cotas, impactos e previsões não validados pela Defesa Civil.
• Previsão testada com poucas cheias recentes (8); aviso de poucas horas.
• Níveis das ruas do centro em 2024 são aproximados; faltam pontos de referência oficiais.
• Lagoinha (Jusante do Jacuí) e Estrada do Ribeira têm menos de 1 ano de histórico.
• Cotas oficiais de Ponte Alta (a partir de 5,20 m) nunca foram atingidas desde 2024.
• Paraibuna: as cotas de Natividade são provisórias (estimadas pelo histórico).
• Fontes podem parar de transmitir (ex.: ANA em 26/10/2026, Passarela em set/2026).
• Horários são exibidos no fuso do aparelho (o painel assume horário de Brasília).

Créditos

• Idealização, criação e coordenação: Dimas de Campos.
• Desenvolvimento em parceria com IA: Claude (Anthropic).
• Dados: SP Águas (SIBH), ANA, Open-Meteo, OpenStreetMap; histórico de cheias do relatório SGB/CPRM (2022) e imprensa regional.

Os dados não foram validados pela Defesa Civil. Qualquer uso é de responsabilidade própria.