05 — Referência Completa da API REST, IPC & WebSocket Unificado
Este documento cobre as camadas de comunicação do sistema:
- Hub WebSocket Unificado Embarcado (
ws://127.0.0.1:8765@60 Hz) + IPC Unix DGRAM (/run/zenith/*.sock) no Zenith AutoOS Buildroot. - Canal gRPC
:50051& WebSocket Protobuf Binário (ws://127.0.0.1:8766) (Fases 71–90, proto/zenith_telemetry.proto). - Backend FastAPI (
http://127.0.0.1:8000) para a Central Multimídia (frontend/) e Cluster (cluster-ui/).
🏠 README · 📚 Documentação · ⬅️ 04 · Bluetooth/OBD · 06 · Instalação ➡️
📑 Neste guia — 9 seções · ~18 min de leitura
- 🗺️ Visão geral em diagrama
- 1. Hub WebSocket Unificado & gRPC/Protobuf (Fases 4–100)
- 2. Backend FastAPI (http://127.0.0.1:8000) — WebSockets
- 3. Endpoints REST (Backend FastAPI :8000)
- 4. API & WebSockets do Simulador Multi-Janela + DevTools God Mode (:8000 — Fases 112–116)
- 5. Endpoints de Internacionalização, Unidades & Bridge gRPC (Fase 117)
- 6. Central Settings (zenith_settings.yaml), Configurador de Garagem & Catálogo Offline SQLite (Fases 118–119)
- 7. API Unificada das Fases 120–138 (backend/app/routers/features.py & zenith_simulator_core.py)
- 8. API Offline de Copiloto LLM, Voz Neural & Mapa 3D MapLibre + Valhalla (routers/ai.py, routers/nav.py & Simulador)
Consumidores: central, cluster, HMI Godot e simulador compartilham o mesmo contrato.
🗺️ Visão geral em diagrama
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:#C8A951Como 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 emws://127.0.0.1:8765para 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 comandosprofile_*(biometria/PaaK/perfis) esecurity_*(Valet PIN, Geo-Fence, Imobilizador)./run/zenith/v2v_cmd.sock: recebe alertas locais (ex: frenagem<= -0.75Gdo Track Day IMU) para broadcast imediato LoRa915 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 Vem Deep Sleep) e do rollback OTA Watchdog 3s para envio imediato no tópico MQTTcarro/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/ ESP322Mbaud→ zenith_grpc_hub.py), comandos de scanner bidirecional UDS0x2F(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çãohomelink./run/zenith/plugin_cmd.sock(zenith_plugin_sandbox.py): instalação auditada e execução em jaula LXC/chrootde plugins USB e.pck./run/zenith/sentry_cmd.sock(zenith_sentry_guard.py): dispara captura estacionária de 2 minutos no pendrive apósEVENT: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)
{
"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)
{"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:8765aceita pacotes binários ProtobufColorSyncRpcempacotados com0xAA 0x55 + len_u16 + proto3 + CRC16-CCITT, despachando imediatamente para/run/zenith/esp32_proto.sock. O payload JSON broadcast em 60 Hz inclui as chavesbrightness,ambient_light,truetone,themeegarage.
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 standalonews://0.0.0.0:8765em adas_coral_yolo.py) — Stream dedicado com objetos 3D detectados para o cliente web egodot_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 impactoMPU6050.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, flagrtl, unidades (speed_unit,temp_unit,pressure_unit,distance_unit,short_distance_unit), escala do velocímetro (speed_scale_max:240ou160), 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: aceitaSetLocaleRequest(locale, overrides opcionais de unidade estt_engine), executasend_grpc_set_locale()rumo ao serviço gRPCZenithTelemetryService/SetLocale(127.0.0.1:50051com fallback automático para/run/zenith/grpc_cmd.socke 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 retornaspeedometer_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+ tamanhou16LE +LocaleConfigRequestProtobuf + CRC32 IEEE) enviados diretamente por ZenithMaster.gd via ProtobufWire.gd ou JSON{"cmd":"set_locale","locale":...}via adas_radar.py, retornandoLocaleConfigAckbinário no mesmo socket sem reiniciar os daemons.
- Quadros
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 (
:8765Embarcado /:8000Simulador):{"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 blocossettings,settings_persistence,vehicle_dbevehicle_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