Deteccao de Calcada

A deteccao de calcada e a camada no veiculo do Levy Vision. Usa hardware de visao computacional de um fornecedor terceiro (Drover AI ou Luna Systems) instalado em seus scooters e bikes. Quando o modelo a bordo decide que o piloto esta em uma calcada, o fornecedor nos envia um evento e nossa engine de politicas decide o que fazer — avisar, reduzir ou cortar a aceleracao.

Este artigo explica a pipeline de ponta a ponta. Para a escada real de corte de aceleracao, veja Politica de corte de aceleracao. Para os passos de onboarding do fornecedor, veja Configuracao do fornecedor — Drover & Luna.

O que voce precisa

• Hardware do fornecedor instalado nos veiculos que voce quer cobrir. Hoje integramos com Drover AI PathPilot e Luna Systems. Captur.ai e suportado apenas para pose de estacionamento, nao deteccao de calcada.
• Dispositivos provisionados em Safety > Vendor devices, com cada serial de dispositivo do fornecedor mapeado para um UUID de veiculo Levy.
• Um secret de webhook assinado armazenado contra seu subaccount para que possamos verificar eventos recebidos.
• O interruptor de Sidewalk detection ativado em Safety > Safety settings.

Se qualquer um desses estiver faltando, os eventos de calcada nao entrarao no painel.

Como funciona a pipeline de eventos

Cam no veiculo → Modelo do fornecedor → Webhook do fornecedor
   → POST /api/webhooks/drover/events (ou /luna/events)
   → Assinatura HMAC verificada
   → Payload normalizado em uma linha cv_events
   → Engine de politicas (sidewalk-policy.ts) decide acao
   → Controlador de aceleracao despacha para o caminho de comando IoT
   → Piloto ve aviso / reducao de velocidade / corte no telefone

A latencia da deteccao no veiculo ate a notificacao do piloto e tipicamente 2–4 segundos, dependendo das condicoes celulares no modulo do fornecedor. A linha de evento no painel aparece na mesma janela.

Configurando deteccao

Abra Dashboard > Safety > Safety settings. A secao Sidewalk detection tem estes controles.

Sidewalk detection enabled

Interruptor principal. Desligado significa que eventos do fornecedor ainda chegam aos nossos webhooks (nao os descartamos — eles sao registrados), mas nenhuma acao de politica e executada e o piloto nao ve nada.

Vendor

Escolha Drover ou Luna. Voce pode misturar fornecedores entre subaccounts mas nao dentro do mesmo subaccount — o mapeamento do fornecedor e por subaccount.

Escada de limiares

Os tres limiares controlam quando cada passo de aplicacao entra. Cada um e uma contagem de eventos de calcada dentro da viagem atual.

Recomendamos fortemente deixar throttle cut desativado no seu primeiro mes. Observe os eventos fluindo no painel, ajuste a lista de permissao de geocerca (abaixo) e ative o corte quando falsos positivos estiverem abaixo de 2%.

Lista de permissao por geocerca

Algumas superficies com formato de calcada nao deveriam disparar aplicacao — ciclovias protegidas que parecem calcadas para o modelo, caminhos a beira-mar que sua cidade permitiu explicitamente, atalhos de praca que o operador autorizou.

Para adicionar um poligono de lista de permissao:

1. Abra Safety > Sidewalk hotspots (visao de mapa).
2. Clique com o botao direito no mapa para desenhar um poligono, ou cole um poligono GeoJSON no dialogo de importacao.
3. Marque o poligono como kind=allow e salve.

Qualquer evento de calcada cuja localizacao caia dentro de um poligono de lista de permissao e registrado mas nao dispara uma acao de politica. A linha do evento mostra o nome do poligono na coluna de efeitos colaterais.

Lendo eventos de calcada

Va para Safety > Events e filtre o tipo de evento por sidewalk_entry (o evento principal) ou sidewalk_exit (evento complementar quando o piloto retorna a estrada).

Cada linha mostra:

• Piloto, viagem, veiculo
• Origem do fornecedor (drover ou luna)
• Confianca (definida pelo modelo do fornecedor)
• Lat/lng, com link "View on map"
• Coluna de efeitos colaterais — quais passos de politica disparou (warn, speed_reduce, throttle_cut)

Para a visao geografica, abra Safety > Sidewalk hotspots. Os eventos se agrupam em um heatmap para que voce possa identificar padroes — a maioria das frotas encontra um ou dois cruzamentos repetidores que respondem pela maior parte dos eventos. Adicione um poligono de lista de permissao se for um falso positivo conhecido, ou compartilhe o heatmap com seu contato na cidade como prova de onde voce esta aplicando.

Confiabilidade do fornecedor e modos de falha

O webhook do fornecedor e o elo mais fraco desta pipeline. Nos monitoramos para voce, mas eis o que acontece quando algo da errado:

• Sem eventos por mais de 5 minutos durante horario de pico — alerta do Sentry dispara, aplicacao e auto-desativada para a frota afetada ate eventos fluirem novamente
• Evento tardio (>30s de atraso) — evento ainda registrado, mas sem aplicacao em tempo real; piloto recebe um push de aviso a posteriori
• Ataque de replay — verificacao de assinatura de webhook rejeita payloads duplicados usando o ID de evento do fornecedor e nosso indice cv_events.external_event_id
• Mismatch de assinatura do fornecedor — webhook retorna 401, evento nao e registrado; verifique o secret de assinatura em Safety > Vendor devices

Se algum dia voce suspeitar que a pipeline esta silenciosamente quebrada (por exemplo, voce sabe que um piloto estava na calcada mas nenhum evento apareceu), verifique o artigo Solucao de problemas — a arvore de diagnostico "sem eventos de calcada" esta la.

Compatibilidade de OEM

O corte de aceleracao depende do que seu protocolo IoT suporta. Nem todo OEM aceita uma limitacao de velocidade no meio da viagem, entao a engine de politicas cai graciosamente:

Se o tipo IoT de um veiculo nao suporta o passo configurado, a engine de politicas registra uma acao skipped e prossegue para o proximo passo. Voce nao precisa configurar isso por OEM — e automatico.

O que o piloto ve

No primeiro evento de uma viagem, o app do piloto mostra o Sidewalk warning modal — uma sobreposicao em tela cheia com um mapa pequeno mostrando sua ultima localizacao conhecida vs. a geometria de calcada detectada, alem de um CTA "Move to the road".

Em reducao de velocidade, o modal atualiza para dizer "Speed reduced — return to the road". Em corte de aceleracao, ele ve a Throttle restore screen com contagem regressiva de 30 segundos e botao "I'm back on the road". Veja Politica de corte de aceleracao para o fluxo de restauracao.

Indo para GA

Recomendamos este caminho de rollout para seu piloto de calcada:

1. Semana 1–2 — dispositivos instalados, deteccao ativada, sem corte de aceleracao. Observe o feed de eventos.
2. Semana 3 — adicione poligonos de lista de permissao de geocerca para hotspots obvios de falsos positivos.
3. Semana 4 — ative o corte de aceleracao. Monitore reclamacoes de pilotos (abaixo de 2 por 1k viagens e a meta).
4. Continuamente — revise o mapa Safety > Sidewalk hotspots semanalmente e compartilhe com seu contato na cidade.