v11.0 · 151 Fases
API & Dados Fases 4–138 Implementado · ~25 min (4.715 palavras) FastAPIWebSocketgRPCProtobuf
📄 docs/05-api-backend-websocket.md ↗

05 — Referência Completa da API REST, IPC & WebSocket Unificado

Este documento cobre as camadas de comunicação do sistema:

  1. Hub WebSocket Unificado Embarcado (ws://127.0.0.1:8765 @ 60 Hz) + IPC Unix DGRAM (/run/zenith/*.sock) no Zenith AutoOS Buildroot.
  2. Canal gRPC :50051 & WebSocket Protobuf Binário (ws://127.0.0.1:8766) (Fases 71–90, proto/zenith_telemetry.proto).
  3. Backend FastAPI (http://127.0.0.1:8000) para a Central Multimídia (frontend/) e Cluster (cluster-ui/).

Zenith AutoOS: 11.0.0 Fases: 151 Guias: 33 Idioma: PT-BR

Categoria: API & Dados Fases: 4–138 Status: Implementado FastAPI: stack WebSocket: stack gRPC: stack Protobuf: stack

🏠 README · 📚 Documentação · ⬅️ 04 · Bluetooth/OBD · 06 · Instalação ➡️

📑 Neste guia — 9 seções · ~18 min de leitura

Frontends consumindo a API e o WebSocket
Consumidores: central, cluster, HMI Godot e simulador compartilham o mesmo contrato.


🗺️ Visão geral em diagrama

Diagrama Mermaid
flowchart TB
    subgraph CLIENTS["Clientes"]
        FE["frontend React"]
        CL["cluster-ui"]
        GD["Godot HMI"]
        SIM["Simulador / DevTools"]
    end

    subgraph API["Camada de API"]
        REST["FastAPI REST :8000"]
        WS["WebSocket JSON :8765"]
        WSP["WebSocket Protobuf :8766"]
        GRPC["gRPC :50051"]
    end

    subgraph CORE["Serviços embarcados"]
        HUB["Hub 60 Hz"]
        SOCK["Sockets /run/zenith/*.sock"]
        CAN["SocketCAN / ESP32"]
    end

    FE --> REST
    FE --> WS
    CL --> WS
    GD --> WS
    SIM --> REST
    REST --> SOCK
    WS --> HUB
    WSP --> HUB
    GRPC --> CAN
    HUB --> SOCK

    style API fill:#1F6FEB,color:#fff,stroke:#93C5FD
    style CORE fill:#0A5C36,color:#fff,stroke:#C8A951

Como ler: o diagrama resume o fluxo principal deste guia; os detalhes, pinagens, endpoints e trechos de código aparecem nas seções abaixo.

1. Hub WebSocket Unificado & gRPC/Protobuf (Fases 4–100)

Executado por adas_radar.py (zenith-adas.service).

Fluxo IPC Interno

  • /run/zenith/hub_ingest.sock (AF_UNIX, SOCK_DGRAM): recebe atualizações JSON assíncronas de telemetria ("telemetry"), mídia AVRCP 1.6 ("media"), navegação ("gps"), DMS/FaceID ("dms"), saúde/CPU ("health"), voz ("voice"), Sensor Fusion EKF ("fusion"), perfil biométrico ("profile"), IMU Track Day ("track"), Edge ML Preditivo ("prognostics"), rádio LoRa V2V ("v2v"), Valet/Antifurto ("security"), Bluetooth Multiponto/Watchdog ("bluetooth"), Codec Audiófilo ("bluetooth_audio"), RGB BLE ("rgb"), Chamadas HFP/AEC ("call"), RSE Dual A2DP ("rse"), TPMS ("tpms"), PaaK ("paak"), brilho ("brightness"), sensor óptico VEML7700 ("ambient_light"), True Tone ("truetone"), Tema UI ("theme") e Gêmeo Digital ("garage").
  • /run/zenith/esp32_cmd.sock: comandos JSON de carroceria/conforto/BLE Gateway para zenith_power_daemon.py → /dev/ttyUSB0 → ESP32.
  • /run/zenith/esp32_proto.sock (Fase 91): socket prioritário de quadros binários Protobuf (0xAA 0x55 + ColorSyncRpc + CRC16) encaminhados diretamente da Godot HMI via frames WebSocket binários em ws://127.0.0.1:8765 para o ESP32 em < 10 ms.
  • /run/zenith/brightness_cmd.sock (Fases 92 & 97): controle direto do Master Dimmer logarítmico (ddcutil + LED) e modo True Tone em zenith_brightness_sync.py.
  • /run/zenith/bt_cmd.sock, /run/zenith/bt_mgr.sock, /run/zenith/call_cmd.sock, /run/zenith/rgb_cmd.sock, /run/zenith/tpms_ingest.sock, /run/zenith/rse_cmd.sock: canais dedicados às Fases 61–70 (SWC reverso + retomada AVRCP, reconexão multiponto/status Watchdog, atendimento HFP/AEC, modo Music Sync/cor BLE, ingestão TPMS do ESP32 BLE Gateway e volumes/roteamento RSE).
  • /run/zenith/profile_cmd.sock & /run/zenith/security_cmd.sock: roteiam comandos profile_* (biometria/PaaK/perfis) e security_* (Valet PIN, Geo-Fence, Imobilizador).
  • /run/zenith/v2v_cmd.sock: recebe alertas locais (ex: frenagem <= -0.75G do Track Day IMU) para broadcast imediato LoRa 915 MHz.
  • /run/zenith/sweetspot_cmd.sock, /run/zenith/dsp_safety.sock & /run/zenith/asd_state.sock: ocupação do banco passageiro (GPIO 34 / DMS), termistor do amplificador Sub (GPIO 35 >= 75°C) e telemetria para o sintetizador Active Sound Design (zenith_asd_synth).
  • /run/zenith/mqtt_alert.sock: canal urgente do ULP (< 11.9 V em Deep Sleep) e do rollback OTA Watchdog 3s para envio imediato no tópico MQTT carro/freelander/alerts.
  • /run/zenith/can_proto.sock, /run/zenith/diag_cmd.sock & /run/zenith/ecu_flash_cmd.sock: transporte binário Protobuf+CRC32 (zenith_can_bridge / ESP32 2Mbaud → zenith_grpc_hub.py), comandos de scanner bidirecional UDS 0x2F (zenith_active_diag.py) e remapeamento/backup ECU (zenith_ecu_flasher.py).
  • Sockets Fases 101–110:
    • /run/zenith/llm_cmd.sock (zenith_llm_ncm.py): consultas RAG/GGUF offline com manuais Land Rover & Toyota + disparo de intenção homelink.
    • /run/zenith/plugin_cmd.sock (zenith_plugin_sandbox.py): instalação auditada e execução em jaula LXC/chroot de plugins USB e .pck.
    • /run/zenith/sentry_cmd.sock (zenith_sentry_guard.py): dispara captura estacionária de 2 minutos no pendrive após EVENT:SENTRY_TRIGGER.
    • /run/zenith/maint_cmd.sock (zenith_maintenance_db.py): leitura/reset de intervalos preventivos e saúde da bateria SQLite WAL.
    • /run/zenith/chime_cmd.sock (zenith_spatial_chime.py): dispara gongo PipeWire 6 canais isolado por porta aberta (fl/fr/rl/rr).

Payload Broadcast (60 Hz, Servidor → Godot HMI)

json
{
  "timestamp_ms": 1731780000000,
  "tpu_active": true,
  "inference_fps": 42.5,
  "cameras_active": 8,
  "objects": [
    {
      "id": "trk_1",
      "obj_class": "Carro",
      "camera": "front_center",
      "pos_x": 0.42,
      "pos_y": 0.0,
      "pos_z": 11.85,
      "distance_m": 11.86,
      "yaw_rad": 0.035,
      "confidence": 0.91
    }
  ],
  "telemetry": {
    "obd_connected": true,
    "protocol": "ISO 9141-2",
    "rpm": 2150,
    "speed_kmh": 64.0,
    "coolant_temp_c": 88.5,
    "engine_load_pct": 34.2,
    "voltage_v": 14.1,
    "tpms": {
      "fl": { "psi": 33.2, "temp_c": 29.0, "battery_pct": 95, "low_alert": false },
      "fr": { "psi": 33.0, "temp_c": 29.5, "battery_pct": 94, "low_alert": false },
      "rl": { "psi": 32.8, "temp_c": 28.0, "battery_pct": 92, "low_alert": false },
      "rr": { "psi": 26.5, "temp_c": 31.0, "battery_pct": 90, "low_alert": true }
    }
  },
  "media": {
    "bt_connected": true,
    "device_name": "Pixel 9 Pro",
    "device_mac": "11:22:33:44:55:66",
    "status": "playing",
    "title": "Midnight City",
    "artist": "M83",
    "album": "Hurry Up, We're Dreaming",
    "genre": "Synthpop",
    "track_number": 2,
    "number_of_tracks": 10,
    "duration_ms": 243000,
    "position_ms": 84000,
    "img_handle": "0000001",
    "album_art_hash": "a1b2c3d4e5f6",
    "album_art_b64": "/9j/4AAQSkZJRg..."
  },
  "bluetooth": {
    "adapter_powered": true,
    "multipoint_active": true,
    "esp32_ble_gateway": true,
    "radio_recovering": false,
    "status_banner": ""
  },
  "bluetooth_audio": {
    "active": true,
    "codec": "LDAC",
    "sample_rate": 96000,
    "bit_depth": 24,
    "bitrate_kbps": 990,
    "hires_ldac": true,
    "badge_text": "Hi-Res Audio LDAC",
    "resampling_bypassed": true,
    "dac_clock_hz": 96000
  },
  "rgb": { "r": 0, "g": 210, "b": 255, "hex": "#00D2FF", "brightness": 85, "mode": "static", "music_sync": false, "redline_active": false },
  "call": { "state": "idle", "caller_name": "", "caller_number": "", "aec_active": false, "music_muted": false, "ac_fan_reduced": false },
  "rse": { "active": true, "playing": true, "output": "HDMI-A-3", "hp_volumes": [80, 65], "route_mode": "headphones", "bt_sinks": ["bluez_output.AA_01", "bluez_output.AA_02"] },
  "paak": { "owner_detected": true, "rssi_dbm": -52, "zone": "unlock", "driver_id": "driver_0" },
  "gps": {
    "fix": true,
    "lat": -23.55052,
    "lon": -46.63331,
    "speed_kmh": 64.2,
    "track_deg": 142.0
  },
  "dms": {
    "ear": 0.29,
    "drowsy_alert": false,
    "gesture": "swipe_right"
  },
  "health": {
    "cpu_temp_c": 58.4,
    "thermal_throttle": false,
    "target_fps": 60,
    "nvme_smart_ok": true
  },
  "voice": {
    "ts": 1731780000000,
    "transcript": "ligar farol",
    "intent": "ligar farol"
  },
  "fusion": {
    "lidar_active": true,
    "mmwave_active": true,
    "fused_objects": [
      { "id": "trk_1", "obj_class": "Carro", "pos_x": 0.40, "pos_z": 14.322, "vel_x": 0.0, "vel_z": -1.2, "laser_distance_m": 14.322, "laser_validated": true, "radar_validated": true }
    ],
    "point_cloud": [[0.40, 0.35, 14.32], [-1.20, 0.35, 9.80]]
  },
  "profile": { "active_id": "driver_0", "driver_name": "Lucas (Titular)", "ac_temp_c": 20, "sweet_spot_ms": 0.45 },
  "track": { "imu_hz": 100.0, "lat_g": 0.62, "lon_g": -0.35, "roll_deg": 2.1, "pitch_deg": -1.4, "yaw_deg": 142.0, "peak_lat_g": 0.85, "peak_brake_g": -0.92, "lap_time_s": 68.42, "best_lap_s": 67.90 },
  "prognostics": { "health_score": 100, "battery_cca_pct": 94, "alternator_ripple_mv": 14.2, "iforest_score": 0.412, "alerts": [] },
  "v2v": { "mesh_active": true, "rssi_dbm": -78, "hazard": "", "distance_km": 0.0, "ts": 1731780000 },
  "security": { "mode": "normal", "locked": false, "valet_rpm_limit": 2500, "valet_speed_limit_kmh": 40, "soft_cut_active": false, "immobilized": false, "theft_alert": false },
  "rta": { "bands": [-42.1, -38.4, -31.0], "peak_db": -12.4, "sample_rate": 48000 },
  "energy": { "i2c_active": true, "bus_v": 14.1, "pc_w": 15.0, "audio_w": 45.0, "cameras_w": 6.5, "total_load_w": 66.5, "alternator_w": 220.0, "net_balance_w": 153.5, "net_a": 10.9 },
  "hardware": { "reverse": false, "steering_angle_deg": -12.0, "turn_left": false, "turn_right": false, "headlights": true, "ac_enabled": false, "solar_w": 24.0, "continuous": true, "sentry_motion": false, "failsafe_oled_active": false },
  "ptp": { "ptp_synced": true, "offset_ns": 5000, "path_delay_ns": 50000, "brake_reaction_ms": 37.5 },
  "v2x": { "intersection_id": "SP-AV-PAULISTA", "phase": "RED", "remaining_sec": 12.0, "glosa_speed_kmh": 45.0, "start_stop_hold": true },
  "terrain": { "active": true, "hazard_type": "Buraco", "wheel_side": "Roda Direita", "distance_m": 9.0, "tti_ms": 450.0, "message": "Impacto Iminente - Roda Direita", "pre_tensioner_armed": true },
  "bio": { "hr_bpm": 114, "calming_active": true, "target_ac_temp_c": 20.0 },
  "topo_energy": { "elevation_m": 760.0, "grade_pct": 5.3, "upcoming_regen_wh": 820.0, "strategy": "PREEMPT_DISCHARGE_CLIMB" },
  "climate_zones": { "driver_pct": 100, "passenger_pct": 0, "rear_pct": 0, "solo_driver_focus": true },
  "k3s_cluster": { "cluster_healthy": true, "active_video_node": "optiplex-master", "offloaded_to_rpi": false },
  "tribology": { "viscosity_grade": "5W-40", "oil_life_pct": 34.2, "high_rpm_cycles": 14, "recommendation": "Vida útil do 5W-40: 34.2%..." },
  "boot_dag": { "all_ready": true, "boot_elapsed_ms": 2840.0, "active_phases": 90, "clean_flash_triggered": true },
  "mdns_mesh": { "peer_count": 2, "peers": [] },
  "diag_report": { "actuator": "cut_injector_3", "fault_detected": true, "delta_rpm": 15.0, "verdict": "FALHA NO CILINDRO 3..." }
}

Comandos HMI/Remotos (ws://127.0.0.1:8765 ou WebRTC → ESP32 / Perfis / Antifurto)

json
{"cmd": "window_front_left", "action": "down"}
{"cmd": "window_front_right", "action": "up"}
{"cmd": "window_rear_left", "action": "stop"}
{"cmd": "trunk", "action": "unlock"}
{"cmd": "sunroof", "action": "open"}
{"cmd": "rgb_zone", "zone": 0, "r": 0, "g": 180, "b": 255}
{"cmd": "ac", "action": "set", "enabled": true, "blower_pct": 65}
{"cmd": "lights", "action": "on"}
{"cmd": "seat_vibrate", "action": "pulse", "duration_ms": 1500}
{"cmd": "usb_port_cycle", "action": "cycle", "port": 0}
{"cmd": "jump_start", "action": "pulse"}
{"cmd": "sub_amp_cut", "enabled": true}
{"cmd": "profile_select", "driver_id": "driver_0"}
{"cmd": "security_valet", "action": "enable"}
{"cmd": "security_arm_geofence"}
{"cmd": "security_immobilize"}
{"cmd": "security_unlock", "pin": "2026"}
{"cmd": "bt_media_control", "action": "NEXT_TRACK"}
{"cmd": "call_answer", "action": "answer"}
{"cmd": "call_hangup", "action": "hangup"}
{"cmd": "rse_hp_volume", "index": 0, "delta": 5}
{"cmd": "rse_route_mode", "action": "toggle"}
{"cmd": "rgb_music_sync", "action": "toggle"}
{"cmd": "diag_override", "action": "run", "actuator": "cut_injector_3", "enable": true}
{"cmd": "ecu_backup_rom", "action": "start"}
{"cmd": "ecu_flash_tune", "action": "apply", "ignition_advance_deg": 2.0}
{"cmd": "pretensioner", "side": "right", "duty_pct": 85, "duration_ms": 450}
{"cmd": "hvac_vents", "driver_pct": 100, "passenger_pct": 0, "rear_pct": 0}
{"cmd": "master_dimmer", "pct": 45.0}
{"cmd": "theme_set", "theme_id": "cyberpunk_neon"}
{"cmd": "palette_sync", "primary_hex": "#00F5FF", "accent_hex": "#FF00AA", "master_dimmer_pct": 80}
{"cmd": "truetone_set", "enabled": true, "kelvin": 3800}
{"cmd": "garage_update", "paint_hex": "#0E2E20", "clearcoat": 0.92, "metallic": 0.78, "roughness": 0.16, "flake_intensity": 0.55, "wheel_rim_inches": 19.0}
{"cmd": "maintenance_reset", "item_id": "oil_change"}
{"cmd": "homelink", "action": "open", "channel": 0}
{"cmd": "rse_control", "action": "toggle_play", "target": "both", "brightness": 85}
{"cmd": "devtools_patch", "patch": {"rpm": 4200, "turn_right": true, "primary_hex": "#FF6B00"}}

Frames WebSocket Binários (Fase 91): Além de texto JSON, ws://127.0.0.1:8765 aceita pacotes binários Protobuf ColorSyncRpc empacotados com 0xAA 0x55 + len_u16 + proto3 + CRC16-CCITT, despachando imediatamente para /run/zenith/esp32_proto.sock. O payload JSON broadcast em 60 Hz inclui as chaves brightness, ambient_light, truetone, theme e garage.


2. Backend FastAPI (http://127.0.0.1:8000) — WebSockets

  • WS /ws/telemetry — Envia quadros JSON continuamente (telemetry, hardware, tpms, trip, adas).
  • WS /ws/adas (e standalone ws://0.0.0.0:8765 em adas_coral_yolo.py) — Stream dedicado com objetos 3D detectados para o cliente web e godot_adas/.

3. Endpoints REST (Backend FastAPI :8000)

Saúde, Perfis & ADAS 360°

Método Rota Descrição
GET /api/health Status do servidor e ID do veículo ativo
GET /api/adas/objects Snapshot atual das detecções 3D (Carros, Motos, Pessoas)
GET /api/profiles Lista todos os perfis (freelander_2006, lexus_es300_1998)
GET /api/profiles/active Retorna o perfil ativo completo
POST /api/profiles/active Troca o veículo ativo ({"profile_id": "..."})

OBD-II (ELM327)

Método Rota Descrição
GET /api/obd/telemetry Leitura instantânea de telemetria
GET /api/obd/dtc Lista códigos de falha DTC
DELETE /api/obd/dtc Limpa códigos de falha DTC na ECU
GET /api/obd/ports Escaneia portas seriais disponíveis
POST /api/obd/connect Conecta ao ELM327 ({"port": "/dev/ttyUSB0"})

Hardware, Elétrica, Clima, Áudio, TPMS & RGB

Método Rota Descrição
GET /api/hardware/state Estado atual do ESP32 + PC817 + sensores
POST /api/hardware/simulate Simula ign, rev, illum, brake_pedal, steering_angle_deg, swc
POST /api/hardware/steering/zero Zera o sensor de ângulo da coluna de direção (0°)
POST /api/hardware/body Controla headlights, interior_dimmer_pct, windows (up/down), sunroof (open/close/tilt)
POST /api/hardware/lights Controla canal independente (headlight_left, headlight_right, fog_left, fog_right, strobe)
POST /api/hardware/climate Ajusta Ar-Condicionado Digital (temp_c, fan_speed, auto_mode, ac_compressor, recirculate)
POST /api/hardware/seats Ajusta aquecimento dos bancos (seat: driver/passenger, level: 0..3)
POST /api/hardware/trunk Abre porta-malas (trava de segurança exige speed_kmh == 0)
POST /api/hardware/start-stop Pulso Start/Stop (trava exige brake_pedal == true e rpm <= 100)
GET /api/hardware/rgb Lista zonas RGB BLE (starlight_roof, cabin_strips)
POST /api/hardware/rgb/{zone_id} Atualiza power, color_hex, brightness, effect
GET /api/hardware/audio Estado completo da placa SB1095 e DSP 6 canais
POST /api/hardware/audio Ajusta volume, muted, eq_preset, eq_bands (10 bandas), output_mode
POST /api/hardware/audio/dsp/channel/{id} Ajusta gain_db, muted, phase_180, hpf_hz, lpf_hz, slope, distance_cm
POST /api/hardware/audio/dsp/matrix Ajusta matriz Mid/Side (enabled, center_extract_pct, stereo_width_pct, limiter_db)
POST /api/hardware/audio/dsp/sweetspot Atualiza posição da bolinha (listener_x, listener_y) e dimensões da cabine (cm)
POST /api/hardware/audio/dsp/presets Salva preset personalizado de Time Alignment ({"name": "..."})
POST /api/hardware/audio/dsp/presets/{id} Aplica preset de Time Alignment salvo
GET /api/hardware/audio/dsp/export Exporta configuração YAML completa para CamillaDSP
GET /api/hardware/tpms Leituras dos 4 pneus TPMS
POST /api/hardware/tpms/simulate Simula pressão de um pneu (position, psi)

Centrafuse (Trip Computer, SVC, Rádio, Telefone & Manutenção)

Método Rota Descrição
POST /api/centrafuse/trip/reset Zera distância, tempo e velocidade máxima da viagem
POST /api/centrafuse/svc Ativa/desativa Volume Automático por Velocidade ({"enabled": true})
GET /api/centrafuse/radio Estado atual do sintonizador FM/RDS e presets
POST /api/centrafuse/radio/tune Sintoniza frequência FM (87.5–108.0 MHz)
GET /api/centrafuse/phone Status Bluetooth HFP e chamadas recentes
POST /api/centrafuse/phone/dial Inicia chamada viva-voz ({"number": "..."})
POST /api/centrafuse/phone/hangup Encerra chamada ativa
GET /api/centrafuse/maintenance Lista alertas de manutenção preventiva (óleo, freios, etc.)
POST /api/centrafuse/maintenance/reset/{id} Reseta intervalo de um item de manutenção

Mídia Local & Apps

Método Rota Descrição
GET /api/media/browse?path=... Navega pastas e músicas em media/ (ou CARPC_MEDIA_DIR)
GET /api/media/stream/{file_path} Streaming de áudio com suporte a seek
GET /api/apps Lista URLs configuradas (spotify, deezer, waze, chrome, email)
POST /api/apps/launch Abre o aplicativo no navegador/modo kiosk

Tema UI, Color-Sync, Master Dimmer, True Tone & Garagem 3D (Fases 91–97)

Método Rota Descrição
GET /api/theme/state Estado atual de tema, paleta Hex, dimmer, VFSX e True Tone
GET /api/theme/profiles Lista perfis JSON (glassmorphism, cyberpunk_neon, minimalist_oled)
POST /api/theme/palette Sincroniza primary_hex, accent_hex e dispara Protobuf Color-Sync (0xAA 0x55)
POST /api/theme/dimmer Ajusta master_dimmer_pct (0–100%) em DDC/CI, Shader UI e PWM logarítmico ESP32/BLE
POST /api/theme/profile Ativa perfil JSON via theme_id
POST /api/theme/truetone Atualiza ambient_lux, ambient_kelvin, enabled e solar_elev_deg
GET /api/garage/config Configuração PBR do Gêmeo Digital 3D (paint_hex, clearcoat, metallic, wheel_rim_inches)
POST /api/garage/config Atualiza pintura, flakes, modelo .OBJ/.GLB e aro das rodas no Gêmeo Digital 3D

Chaves de Telemetria Adicionais no JSON :8765 / :8000 (Fases 101–116)

Além do payload base, o hub embarcado (zenith_grpc_hub.py) e o simulador (zenith_simulator_core.py) publicam os blocos:

  • cognition: último diagnóstico/consulta LLM offline (question, answer, sources, intent).
  • plugins: lista de plugins .pck / Python sandboxed instalados via USB e status de isolamento.
  • welcome_mode: estado do Welcome Mode 3m BLE (active, driver_id, rssi_dbm).
  • remote_clima & follow_me_home: estado do pré-condicionamento MQTT e temporizador de 30s pós-trava.
  • sentry: estado da captura estacionária 2 min após impacto MPU6050.
  • bsw: alertas direcionais de ponto cego (left_alert, right_alert, active, side) sincronizados às setas (hardware.turn_left / hardware.turn_right).
  • maintenance: itens de manutenção preventiva (oil_change, filters, tires, brake_fluid), odômetro e diagnóstico de tensão da bateria.
  • doors: mapa {"fl": bool, "fr": bool, "rl": bool, "rr": bool} usado pelo Spatial Chime 6 canais.
  • homelink: canais RF/SSR e flag de proximidade geofencing <= 30 m.

4. API & WebSockets do Simulador Multi-Janela + DevTools God Mode (:8000 — Fases 112–116)

Quando executado em desktop com python zenith_simulator_core.py ou python start_demo.py, o servidor FastAPI expõe as mesmas rotas WebSocket em JSON ou binário Protobuf+CRC32 (?format=protobuf):

Canal / Método Rota Função
WS /, /ws, /ws/telemetry, /ws/adas, /ws/hmi Stream completo a 60Hz (ou frames binários Protobuf VehicleTelemetryFrame + CRC32) e recepção de comandos HMI (devtools_patch, rse_control, maintenance_reset, homelink, theme_set)
GET /devtools Console web God Mode (devtools.html) com sliders, toggles (portas, setas, buraco, Welcome, Clima, Follow Me Home, Sentry, Geofence 30m) e Color Picker RGB < 10 ms
GET /sim/{window_mode} Telas desktop HTML5 (cluster, central, rse-left, rse-right via sim_windows.html)
GET /branding/{asset_name} Entrega assets oficiais de branding (logo.png, zenith-logo.png, zenith-mark.png, favicon.png) para DevTools e Simulador
GET /api/health Status de saúde do simulador
GET / POST /api/devtools/state Lê ou injeta overrides parciais do estado do veículo no loop fantasma
POST /api/simulator/yolo Recebe Bounding Boxes 3D de zenith_fake_v4l2.py
POST / GET /api/simulator/cam/{cam_name} Ingestão e visualização de frames JPEG das câmeras virtuais
POST /api/simulator/rse Espelha comandos RSE (play/pause, faixa, brilho) nas janelas traseiras
POST /api/llm/query Testa perguntas mecânicas offline usando zenith_llm_ncm.py
GET /api/maintenance Retorna saúde da bateria e progresso dos itens de revisão
POST /api/maintenance/reset/{item_id} Zera contador de manutenção preventiva (oil_change, filters, tires, brake_fluid)
POST /api/homelink/trigger Dispara abertura/aprendizado HomeLink no estado simulado

5. Endpoints de Internacionalização, Unidades & Bridge gRPC (Fase 117)

Além dos fluxos principais, o backend FastAPI expõe o domínio /api/locale (routers/locale.py, services/locale_service.py) e propaga o estado locale (LocaleState) em /ws/telemetry:

  • GET /api/locale/supported: lista as 10 variantes em 7 idiomas (pt_BR, pt_PT, en_US, en_GB, es_419, es_ES, de_DE, ja_JP, zh_CN, ar).
  • GET /api/locale/state: retorna idioma ativo, flag rtl, unidades (speed_unit, temp_unit, pressure_unit, distance_unit, short_distance_unit), escala do velocímetro (speed_scale_max: 240 ou 160), modelos ativos (whisper_model_path, vosk_model_dir, llm_model_path, tts_voice, active_stt_engine) e status de transporte gRPC (grpc_transport, grpc_accepted).
  • POST /api/locale/set: aceita SetLocaleRequest (locale, overrides opcionais de unidade e stt_engine), executa send_grpc_set_locale() rumo ao serviço gRPC ZenithTelemetryService/SetLocale (127.0.0.1:50051 com fallback automático para /run/zenith/grpc_cmd.sock e despachos direto /run/zenith/voice_cmd.sock + /run/zenith/llm_cmd.sock) e atualiza /ws/telemetry.
  • POST /api/locale/convert: converte velocidade (km/h <-> mph), temperatura (°C <-> °F), pressão TPMS (Bar <-> PSI) e retorna speedometer_scale (max_speed, major_step, ticks).
  • Canal Protobuf Binário ws://127.0.0.1:8766 (Hub Embarcado zenith_grpc_hub.py):
    • Quadros ZL (0x5A 0x4C + tamanho u16 LE + LocaleConfigRequest Protobuf + CRC32 IEEE) enviados diretamente por ZenithMaster.gd via ProtobufWire.gd ou JSON {"cmd":"set_locale","locale":...} via adas_radar.py, retornando LocaleConfigAck binário no mesmo socket sem reiniciar os daemons.

6. Central Settings (zenith_settings.yaml), Configurador de Garagem & Catálogo Offline SQLite (Fases 118–119)

Tanto o Backend FastAPI (routers/settings.py) quanto o Simulador Core (zenith_simulator_core.py) expõem rotas unificadas para persistência criptografada em tempo real e seleção dinâmica de veículo via zenith_settings_manager.py:

Canal / Método Rota Descrição
GET /api/settings Retorna as 7 seções (vehicle, audio_dsp, adas_cameras, lighting_rgb, connectivity, displays_themes, system), persistence (cipher, boot_load_ms, path), árvore vehicle_db e vehicle_autoconfig
POST /api/settings Atualiza toggles, sliders ou seletores em tempo real ({"section", "key", "value"}, aninhado por aba ou atalhos flat), gravando atomicamente em zenith_settings.yaml
GET /api/garage/vehicles Retorna árvore encadeada Marca → Modelo → Ano, amostra paginada (limit/offset) de zenith_vehicle_db.sqlite / zenith_vehicle_db.json, stats offline e autoconfig ativo
GET /api/garage/brands Lista marcas distintas do catálogo offline SQLite/JSON (?limit=...) + métricas de inventário
GET /api/garage/models Lista modelos disponíveis offline para a marca (?brand=Lexus)
GET /api/garage/years Lista anos descendentes disponíveis offline (?brand=Lexus&model=ES 300)
GET /api/garage/search Busca offline indexada no catálogo global (q, brand, model, year, enriched_only, limit, offset)
GET /api/garage/specs/{vehicle_id} Retorna o dicionário completo de 6 domínios (specs_dictionary) de um veículo específico pelo vehicle_id
POST /api/garage/select Seleciona veículo via brand + model + year (+ wheel_rim_inches opcional) ou vehicle_id, injetando peso ADAS, PIDs CAN/K-Line, calibração de rodas, specs_dictionary e caminho .glb
  • Comandos WebSocket (:8765 Embarcado / :8000 Simulador):
    • {"cmd": "settings_patch", "section": "...", "key": "...", "value": ...} — persiste configuração instantaneamente e sincroniza UI/daemons (yolo_sensitivity, master_dimmer_pct, theme_id, etc.).
    • {"cmd": "vehicle_select", "brand": "...", "model": "...", "year": 2006} — dispara autoconfiguração global e propaga nos frames os blocos settings, settings_persistence, vehicle_db e vehicle_autoconfig (adas_physics, wheel_calibration, can_kline_config, model_3d).

7. API Unificada das Fases 120–138 (backend/app/routers/features.py & zenith_simulator_core.py)

O WebSocket /ws/telemetry passa a incluir o objeto "features" completo (além de "trip" enriquecido com liters_used, cost_brl, refuel_prompt_pending, driving_score, driving_tips e "hardware" com locked, windows_closed, ambient_lux, park_sensors_cm, bulb_currents_a), sincronizado pelas seguintes rotas REST espelhadas entre Backend FastAPI e Simulador:

Método Rota Fase Descrição
GET /api/features/state 120–138 Snapshot completo das 19 funcionalidades em tempo real
POST /api/adas/safety/evaluate 120–123 Avalia Safe Exit, Lead Departure, Placa/Laranja e Saída de Faixa LDW
POST /api/adas/speed-limit 122 Define/simula limite de velocidade reconhecido na câmera/mapa
GET / POST /api/nav/radars, /api/nav/radars/import, /api/nav/gps/simulate 124 Lista radares offline SQLite, importa CSV e simula coordenadas GPS
POST /api/dvr/crash/trigger 125 Simula impacto G, trava clipes em /data/dvr/locked/ e envia SOS Telegram
POST /api/hardware/lock 129 Tranca/destranca e dispara fechamento de conforto dos vidros (comfort_close)
POST /api/hardware/auto-headlights 126 Configura e simula leitura de Lux (VEML7700) para farol automático
GET / POST /api/hardware/bulbs, /api/hardware/bulbs/simulate 128 Monitora corrente (INA219) e emite alertas PT-BR de lâmpada queimada
POST /api/hardware/park-sensors 130 Atualiza sensores ultrassônicos (fl/fr/rl/rr cm) com áudio direcional DSP 6ch
GET /api/cameras/360/meta, /api/cameras/360/frame 131 Metadados e quadro JPEG/PNG costurado em Bird's-Eye 360° (Homografia OpenCV)
GET /api/obd/dtc/explain, /api/obd/dtc/explain/{code} 132 Explicação PT-BR de DTCs (o que é, gravidade, pode_seguir_viagem)
GET / POST /api/trips, /api/trips/step, /api/trips/finish, /api/trips/refuel, /api/trips/export.csv 133–135 Diário de bordo SQLite, detecção de abastecimento R$/L, nota e CSV para reembolso
GET / POST /api/carplay/status, /api/carplay/start, /stop, /action 136 Controle da projeção embutida OpenAuto / AASDK / Carlinkit (Waze, Spotify, SWC)
GET / POST /api/telegram/config, /api/telegram/command 137 Whitelist allowed_chat_ids e despacho de comandos /status, /bateria, /onde, /clima, /portao, /trancar
GET / POST /api/sync/garage/status, /config, /wifi, /approve, /dismiss 138 Política de sincronização Wi-Fi da garagem (auto, ask, never), NAS, mídias offline e OTA
  • Comandos WebSocket adicionais: lock_vehicle, speed_limit, park_sensors, crash_trigger, garage_wifi, garage_approve, garage_dismiss, carplay_action.

8. API Offline de Copiloto LLM, Voz Neural & Mapa 3D MapLibre + Valhalla (routers/ai.py, routers/nav.py & Simulador)

Endpoints unificados expostos simultaneamente pelo Backend FastAPI (main.py) e pelo Simulador Core (zenith_simulator_core.py), utilizando modelos e mapas locais sem depender da nuvem:

Método Rota Serviço / Módulo Descrição
GET /api/llm/status ai.py Status do GGUF local (Qwen2.5-1.5B), llama-cli/llama-server, STT e TTS
POST /api/llm/query llm_voice_service.py Executa intenção de cabine ou consulta LLM/RAG + DTC (P0xxx), retornando answer, sources e ui_actions
GET /api/voice/status ai.py Inventário offline de Whisper (ggml-base.bin), Vosk (vosk-model-small-pt-0.3) e Piper ONNX
POST /api/voice/command ai.py Despacha comando textual de voz e retorna intent + ui_actions
POST /api/voice/transcribe ai.py Recebe áudio (multipart/form-data WAV/PCM), reamostra para 16 kHz mono, transcreve via Whisper.cpp/Vosk e opcionalmente executa o comando
POST /api/voice/tts ai.py Sintetiza fala offline (audio/wav) via Piper Neural (pt_BR-faber-medium.onnx) ou fallback pyttsx3/espeak-ng
GET /api/nav/status nav.py Saúde da base offline (osm_vector.mbtiles, glifos, places.sqlite FTS5 e Valhalla)
GET /api/nav/style.json offline_nav_service.py Retorna Style JSON MapLibre v8 tematizado (glassmorphism, cyberpunk_neon, minimalist_oled) com extrusão 3D (osm-buildings-3d)
GET /api/nav/vector-tiles/{z}/{x}/{y}.pbf offline_nav_service.py Entrega Vector Tiles MVT comprimidos em gzip (buildings, roads, landuse, water, pois)
GET /api/nav/glyphs/{fontstack}/{range_pbf} offline_nav_service.py Serve glifos locais .pbf (Noto Sans Regular/Medium/Italic)
GET /api/nav/search nav.py Busca FTS5 offline em places.sqlite por ruas, avenidas e pontos de interesse (?q=...&limit=10)
POST /api/nav/route nav.py Calcula rota turn-by-turn offline via Valhalla C++ (valhalla.Actor), retornando GeoJSON LineString, distância e manobras
GET /api/nav/live-objects nav.py Projeta carros, motos, pedestres e buracos do ADAS sobre GPS (project_adas_objects_to_gps)
GET /api/adas/objects zenith_simulator_core.py Snapshot de objetos ADAS espelhado no simulador para compatibilidade com a UI web

⬅️ 04 · Bluetooth/OBD · ⬆️ Topo · 📚 Índice · 06 · Instalação ➡️

Zenith AutoOS 11.0 · Documentação técnica · Novembro de 2026 · README principal