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.
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
- Bacias e como adicionar um rio
- O que o painel mostra
- Fontes de dados
- Cotas e classificação do nível
- Réguas da cidade: conversão e preenchimento
- Qualidade dos dados (filtros)
- Previsão de cheias (experimental)
- Rio acima e chuva na bacia
- O que alaga, memória e estatísticas
- Avisos
- Atualização automática
- Estrutura do projeto
- 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:
- 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.
- Acrescente a bacia em
public/bacias.json.
- 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>.
- 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.
