diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..af665e9 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,111 @@ +# AGENTS.md: Epifah + +Contexto do projeto para qualquer LLM/agente (Claude, ChatGPT, Cursor, etc.) ou pessoa nova. +Lê isto primeiro. Plano completo em `docs/PROJECT.md`. + +## Resumo em 3 linhas + +**Epifah** é o nome do projeto (slug `epifah`, package id `pt.ruifpb.epifah`, domínio `ruifpb.pt`). + +Projeto de reverse engineering de interoperabilidade: perceber como a app **Aha Radio** +(Harman, serviço cloud morto) comunica com o **MediaNav Evolution** de um **Renault Clio IV** +e escrever uma app Android moderna que fale o mesmo protocolo, para mostrar e controlar +conteúdo atual (rádios web, podcasts, biblioteca local, etc.) no ecrã do carro. + +## Ambiente do dono (preencher/atualizar) + +- Carro: Renault Clio IV, MediaNav Evolution, sem Android Auto/CarPlay na unidade +- Versão hardware/software do MediaNav: `TODO` +- Telemóvel / versão Android: `TODO` +- Versão do APK Aha Radio (instalado à força): `TODO` +- Ligação testada: Bluetooth. USB: nunca testado +- Sistema de trabalho (SO, ferramentas instaladas): `TODO` +- Gitea self-hosted: `TODO url` (domínio do dono: `ruifpb.pt`) + +## Estado atual + +Fase 0 (ver `docs/PROJECT.md`). Atualizar esta secção no fim de cada sessão de trabalho. + +- Descobertas confirmadas: nenhuma ainda +- Em curso: `TODO` +- Próximo passo: análise do manifest e strings do APK (UUIDs RFCOMM, classes de comunicação) + +## Hipóteses de trabalho (NÃO são factos) + +1. Controlo via Bluetooth RFCOMM/SPP com UUID próprio; áudio via A2DP separado. + (Baseado em manuais Kenwood e Kia da plataforma Aha, não no MediaNav em si.) +2. O carro mostra um template fixo (estações, now playing, presets). +3. Protocolo binário com framing; autenticação desconhecida. + +## Regras para o agente + +1. **Não inventes detalhes de protocolo.** Se não há evidência (captura, hook, código lido), + diz "não sei" e propõe como descobrir. Distingue sempre *confirmado*, *hipótese* e *desconhecido*. +2. **Toda a afirmação sobre o protocolo** deve apontar para evidência: ficheiro de captura + offset/frame, + ou classe/método do APK. Sem evidência, entra como hipótese. +3. **Legal:** nunca pedir nem produzir cópias do APK/código da Harman nem texto descompilado extenso. + Escrever implementação de raiz e documentação nas nossas palavras. Não ajudar a contornar + DRM de conteúdo nem a aceder a serviços de terceiros sem autorização. +4. **Privacidade:** capturas e logs têm de ser sanitizados (MAC, tokens, credenciais, localização) antes de commit. +5. **Âmbito:** só equipamento do próprio dono, só interoperabilidade. Sem alterar firmware/ECUs do carro. +6. Prefere o caminho mais simples que dê resultado (ex.: confirmar se AVRCP browsing resolve parte do problema + antes de investir em reimplementar o protocolo). +7. Não dar passos destrutivos sem avisar (flash, `adb` com root, alterações ao carro). +8. Se uma informação for sobre versões, preços ou estado atual de serviços/SDKs, verificar online + em vez de confiar na memória. + +## Marca e nomes + +- Nome: Epifah. Descrição oficial: "Reimplementação independente do protocolo da app legada Aha Radio. + Não afiliada à Harman nem à Renault." +- Nunca usar Aha, Harman, Renault, Clio, MediaNav, R-Link em nomes de pacotes, classes + públicas, app, ícone ou repo. Só em documentação, de forma descritiva. +- Sem logótipos nem cores que lembrem essas marcas. + +## Convenções + +- Idioma: **português de Portugal** em docs, issues e commits. Código e identificadores em inglês. +- Commits: Conventional Commits (`feat:`, `fix:`, `docs:`, `chore:`). +- Descobertas: uma nota por tema em `docs/findings/` (modelo em `docs/PROJECT.md`, secção 9). +- Decisões importantes: ADR curto em `docs/decisions/`. +- Android: Kotlin, `minSdk` a definir com base no telemóvel do dono. +- Protótipos de protocolo em Python (`prototype/`), com testes sobre capturas reais. + +## Estrutura do repo + +``` +docs/PROJECT.md plano, riscos, fases +docs/findings/ notas de descobertas +docs/protocol/ especificação do protocolo (SPEC.md, handshake.md) +docs/captures/ capturas SANITIZADAS + README de cenários +docs/decisions/ ADRs +tools/ scripts Frida e helpers de análise +prototype/ PoC Python +app/ app Android +``` + +Nunca commitar: `*.apk`, `jadx-out/`, `apktool-out/`, capturas não sanitizadas. + +## Contexto técnico útil + +- Ferramentas previstas: jadx, apktool, Wireshark (RFCOMM/SDP), Frida (hook de `BluetoothSocket` + input/output streams), mitmproxy (dependências de rede), adb. +- Captura BT em Android: ativar *Bluetooth HCI snoop log* nas opções de programador e extrair `btsnoop_hci.log`. +- Fonte de conteúdo gratuita para testes: radio-browser.info (rádios web). +- Projetos relacionados (inspiração, não resolvem este problema): `ddt4all`, projetos Hackaday sobre o + protocolo CAN do display Renault. Não existe, até à data da pesquisa, nenhum projeto público que + documente o protocolo Aha. + +## Perguntas em aberto + +- O carro inicia a ligação RFCOMM ou é o telemóvel? +- Há autenticação/assinatura no handshake? +- Há código nativo (`.so`) no caminho do protocolo? +- O MediaNav suporta AVRCP 1.4 com browsing? +- Existe atualização de firmware oficial que ative Android Auto nesta unidade? +- A app Aha precisa da cloud para o carro funcionar (login, listas de estações)? + +## Como retomar uma sessão + +Ao começar uma nova conversa: lê este ficheiro e `docs/PROJECT.md`, resume o estado em 5 linhas, +confirma o próximo passo comigo e pede-me só o que falta (ficheiros, outputs de comandos, capturas). diff --git a/PROJECT.md b/PROJECT.md new file mode 100644 index 0000000..a1be1fb --- /dev/null +++ b/PROJECT.md @@ -0,0 +1,233 @@ +# Epifah + +Reimplementação moderna do lado "telemóvel" do protocolo Aha Radio, para +usar o MediaNav Evolution de um Renault Clio IV como ecrã/controlo de uma +app de media atual (rádios web, podcasts, biblioteca local, etc.). + +> *Epifah* é o nome do projeto. Reimplementação independente, **não afiliada à Harman +> nem à Renault**. "Aha Radio" é referida apenas para descrever a compatibilidade. + +> Estado: **fase 0, ainda sem nenhuma descoberta confirmada.** +> Tudo o que está marcado como *hipótese* tem de ser validado com capturas reais. + +--- + +## Identidade do projeto + +| Item | Valor | +|---|---| +| Nome | Epifah | +| Slug do repositório | `epifah` | +| Package id Android | `pt.ruifpb.epifah` | +| Domínio | `ruifpb.pt` (ex.: `epifah.ruifpb.pt` para docs/site, opcional) | +| Descrição curta | Reimplementação independente do protocolo da app legada Aha Radio, para usar o MediaNav Evolution com apps de media atuais. Não afiliada à Harman nem à Renault. | + +Regras de marca: +- Não usar "Aha", "Harman", "Renault", "Clio", "MediaNav", "R-Link" no nome, slug, + package id, ícone ou nome da app. Só na documentação, de forma descritiva. +- Sem logótipos, cores ou grafismo que lembrem a Aha, a Harman ou a Renault. +- Manter o aviso de "não afiliado" no README e na página da app. +- Antes de publicar (Play Store, GitHub público): pesquisar "Epifah" e variantes (Epifa, Epiphah) + no EUIPO TMview, GitHub e Google Play. + +--- + +## 1. Objetivo + +- Fazer o MediaNav Evolution voltar a mostrar e controlar conteúdo vindo do + telemóvel através do mesmo mecanismo que a app Aha Radio usava. +- Recuperar funcionalidades que o streaming Bluetooth genérico (A2DP/AVRCP) não dá + (navegar listas/estações no ecrã do carro, presets, escolher conteúdo sem mexer no telemóvel). +- Aprender: é um projeto de reverse engineering por interesse próprio. + +**Não-objetivos** + +- Android Auto / CarPlay completos (o ecrã do carro é um template fixo). +- Redistribuir código, APK ou serviços da Harman. +- Mexer no firmware ou nas ECUs do carro. + +--- + +## 2. Contexto + +| Item | Valor | +|---|---| +| Carro | Renault Clio IV | +| Head unit | MediaNav Evolution (sem Android Auto / CarPlay na unidade em causa) | +| App original | Aha Radio (Harman). Serviço cloud praticamente morto | +| Estado da app | APK instalado à força, funciona "minimamente" | +| Ligação testada | Bluetooth. USB nunca testado | + +### Pistas externas (pesquisa feita) + +- A Aha foi adquirida pela Harman em 2010, ligava-se aos carros por + Bluetooth ou USB, e o serviço está hoje inativo. +- Manuais da Kenwood e da Kia indicam que em **Android** a ligação à head unit + usa **Bluetooth SPP (Serial Port Profile) + A2DP**, e que em **iOS** usa **USB**. + Isto sugere fortemente: *dados/controlo por RFCOMM, áudio por A2DP*. + (Continua a ser hipótese para o MediaNav Evolution específico.) +- A mesma plataforma Aha foi usada por Pioneer, Kenwood, Subaru (Fujitsu Ten), Kia e outros. + O protocolo pode ser comum ou quase comum entre eles, o que ajuda se + aparecer documentação de outro fabricante. +- **Não foi encontrado nenhum projeto open source** que documente o + protocolo Aha nem que o reimplemente para Renault. +- Projetos adjacentes (úteis só como inspiração): `ddt4all` (diagnóstico/configuração + de ECUs Renault) e vários projetos no Hackaday sobre o protocolo do display Renault (CAN). + Não são o mesmo problema. + +### Ponto a verificar antes de investir semanas + +A Renault anuncia Android Auto/CarPlay para alguns MediaNav Evolution. +Confirmar **versão exata de hardware e de software** da unidade e se existe +atualização de firmware oficial que o ative. Se existir, o projeto passa a ser +só "por interesse", o que continua válido, mas convém saber. + +--- + +## 3. Conhecimento atual + +**Confirmado** +- A unidade integra com a app Aha Radio em Android. +- A app corre no telemóvel do dono (ver `AGENTS.md` para versão). + +**Hipóteses (por validar)** +- H1. Canal de controlo = RFCOMM/SPP com UUID próprio. +- H2. Áudio = A2DP normal, fora do protocolo. +- H3. O carro mostra um template fixo (lista de estações, "now playing", presets). +- H4. O protocolo é binário com framing (cabeçalho + tipo + payload, possivelmente checksum). +- H5. Pode não haver autenticação do lado do carro. Se houver, é o maior risco do projeto. + +**Desconhecido** +- Quem inicia a ligação RFCOMM (carro ou telemóvel). +- Se parte do protocolo está em código nativo (`.so`). +- Se a unidade suporta AVRCP 1.4 com browsing (alternativa muito mais simples). + +--- + +## 4. Riscos + +| Risco | Impacto | Mitigação | +|---|---|---| +| Handshake com autenticação/assinatura | Pode bloquear o projeto | Descobrir cedo (fase 2). Decidir parar ou não | +| Protocolo em código nativo ofuscado | Mais trabalho | Frida a nível de socket em vez de ler o código | +| Template do carro muito limitado | Funcionalidade final reduzida | Definir expectativas na fase 3 | +| Aha app esperar respostas da cloud para o carro funcionar | Precisamos de simular a cloud | Mapear dependências de rede com mitmproxy | +| Limitações de SDKs/APIs de serviços de terceiros | Integrações limitadas ou instáveis | Tratar serviços externos como fontes opcionais e plugáveis, verificar limites atuais | +| Aspetos legais | Exposição | Ver secção 5 | + +--- + +## 5. Legal e ética + +- Análise feita sobre equipamento próprio, para interoperabilidade. Na UE a + diretiva de software prevê exceções para isso, mas **não sou advogado e isto não é aconselhamento legal**. +- **Não commitar** o APK da Harman, código descompilado nem dumps de recursos. +- Código da nova app escrito de raiz. Documentação do protocolo escrita nas nossas palavras. +- Capturas BT/rede: remover endereços MAC, tokens, credenciais antes de commitar. +- Sem afiliação com Harman ou Renault. Marcas só para identificação. + +--- + +## 6. Plano por fases + +Cada checkbox pode virar um issue no Gitea. Sugestão de milestones = fases. + +### Fase 0: Preparação +- [ ] Registar versões: telemóvel/Android, versão do APK Aha, versão de hardware/software do MediaNav +- [ ] Verificar se há atualização de firmware oficial com Android Auto +- [ ] Teste rápido: o MediaNav suporta **AVRCP browsing**? (usar uma app com `MediaBrowserService`, ver se aparece navegação no ecrã) +- [ ] Testar o que a unidade faz por **USB** com o telemóvel (modo storage, iAP, outro) +- [ ] Criar repositório com estrutura da secção 8 +- [ ] Preparar ferramentas: jadx, apktool, Wireshark, Frida, mitmproxy, adb + +### Fase 1: Análise estática do APK +- [ ] Decompilar com jadx/apktool (localmente, não commitar) +- [ ] Ler `AndroidManifest.xml`: permissões, serviços, receivers, `uses-feature` +- [ ] Procurar `UUID.fromString`, `listenUsingRfcomm*`, `createRfcommSocket*`, `BluetoothServerSocket` +- [ ] Listar bibliotecas nativas (`lib/*/*.so`) e perceber o que fazem +- [ ] Identificar classes de framing/serialização +- [ ] Mapear dependências de rede (hosts, endpoints) em `docs/findings/network.md` + +### Fase 2: Captura de tráfego +- [ ] Ativar *Bluetooth HCI snoop log*, repetir cenários e extrair `btsnoop_hci.log` +- [ ] Analisar SDP no Wireshark (UUID do serviço que o carro procura) +- [ ] Frida: hook em `BluetoothSocket` input/output streams para ver frames em claro +- [ ] Cenários padronizados (ver `docs/captures/README.md`): ligar, abrir app, lista de estações, escolher estação, next/prev, presets, desligar +- [ ] Decidir: existe autenticação? Documentar em `docs/protocol/handshake.md` + +### Fase 3: Especificação do protocolo +- [ ] Framing, tipos de mensagem, campos +- [ ] Máquina de estados do handshake +- [ ] O que o carro consegue mostrar (campos, limites de texto, imagens?) +- [ ] Escrever `docs/protocol/SPEC.md` com cada afirmação ligada a uma captura + +### Fase 4: Prova de conceito +- [ ] Cliente de teste (Python ou app Android mínima) que faz o handshake +- [ ] Mostrar uma estação/lista fictícia no ecrã do carro +- [ ] Receber eventos do carro (botões, seleção) + +### Fase 5: App real (MVP) +- [ ] Serviço Android em foreground com o UUID e handshake corretos +- [ ] "Now playing" com metadados, play/pause/next/prev +- [ ] Lista de presets/favoritos no ecrã do carro +- [ ] Fontes de conteúdo plugáveis: rádios web (radio-browser.info), podcasts, biblioteca local +- [ ] Gestão de áudio (A2DP, audio focus) + +### Fase 6: Extras +- [ ] Integrações com serviços de streaming de terceiros (via SDK/API disponíveis na altura, a verificar) +- [ ] Navegação por playlists/álbuns no ecrã do carro +- [ ] UI de configuração no telemóvel +- [ ] Teste de USB se a Fase 0 mostrar algo interessante + +--- + +## 7. Stack proposta (a confirmar) + +- Android, Kotlin, API recente. `BluetoothSocket` clássico (RFCOMM). +- Análise: jadx, apktool, Wireshark (com dissector/Lua se justificar), Frida, mitmproxy. +- Protótipos de protocolo: Python (sockets RFCOMM em Linux, ou `pybluez`/`bleak` consoante o caso). +- Testes de parsing com ficheiros de captura reais (golden files, sanitizados). + +--- + +## 8. Estrutura de repositório sugerida + +``` +/ +├── AGENTS.md # contexto para humanos e LLMs +├── README.md +├── docs/ +│ ├── PROJECT.md # este ficheiro +│ ├── findings/ # notas de descobertas (uma por tema) +│ ├── protocol/ # SPEC.md, handshake.md, mensagens +│ ├── captures/ # README + capturas SANITIZADAS +│ └── decisions/ # ADRs curtos +├── tools/ # scripts Frida, parsers, helpers de análise +├── prototype/ # PoC em Python +└── app/ # app Android final +``` + +`.gitignore` obrigatório para: APKs, `jadx-out/`, `apktool-out/`, `*.apk`, capturas não sanitizadas. + +--- + +## 9. Modelo de nota de descoberta + +```markdown +# +- Data: +- Pergunta: +- Método (ferramenta, ficheiro de captura, hook): +- Evidência (excerto, offset, hash do ficheiro): +- Conclusão: +- Confiança: alta / média / baixa +- Próximo passo: +``` + +## 10. Referências + +- Kenwood: manuais Aha Radio (requisitos Android: SPP + A2DP) +- Kia: página de referência Aha Radio (Android via Bluetooth, iOS via USB) +- Renault: páginas Media Nav Evolution (Android Auto/CarPlay em algumas versões) +- Hackaday: projetos de reverse engineering do protocolo display/rádio Renault (CAN) +- `ddt4all` no GitHub (diagnóstico de ECUs Renault) diff --git a/README.md b/README.md index 82d9ca4..ba729d6 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,56 @@ -# epifah +# Epifah -Reimplementação moderna do lado "telemóvel" do protocolo Aha Radio, para -usar o MediaNav Evolution de um Renault Clio IV como ecrã/controlo de uma -app de media atual (rádios web, podcasts, biblioteca local, etc.). \ No newline at end of file +Reimplementação independente do protocolo usado pela app legada **Aha Radio**, para voltar a usar +o ecrã e os controlos do MediaNav Evolution de um Renault Clio IV com apps de media atuais. + +> Projeto pessoal, em fase inicial (reverse engineering). **Ainda não há nada utilizável.** +> Não afiliado à Harman nem à Renault. + +## Porquê + +A Aha Radio (Harman) está praticamente morta, mas a head unit continua a falar o seu protocolo. +O objetivo é perceber esse protocolo, escrever uma app Android que o fale e usá-lo para mostrar e +controlar conteúdo atual no ecrã do carro, coisas que o streaming Bluetooth genérico não permite. +E, claro, pelo desafio. + +## Estado + +Fase 0: preparação e pesquisa. O plano completo, os riscos e as fases estão em +[`docs/PROJECT.md`](docs/PROJECT.md). + +## Estrutura + +``` +docs/ plano, descobertas, especificação do protocolo, capturas sanitizadas +tools/ scripts de análise +prototype/ prova de conceito +app/ app Android +AGENTS.md contexto do projeto para LLMs e novos colaboradores +``` + +## Uso de IA + +Este projeto é desenvolvido com ajuda de IA, e prefiro ser claro quanto a isso. + +- **Ferramenta:** [Claude](https://claude.ai) (Anthropic), em conversa, para pesquisa, planeamento, + escrita de documentação, escolha do nome e, mais à frente, apoio na análise e no código. +- **Responsabilidade:** as decisões e o que é publicado são meus. A IA não substitui a validação: + qualquer afirmação sobre o protocolo tem de ter evidência (capturas, hooks, código analisado) + e não é aceite só porque um modelo a disse. +- **Limitações:** os modelos podem errar ou inventar detalhes. Por isso as hipóteses estão marcadas + como tal na documentação e o [`AGENTS.md`](AGENTS.md) instrui os agentes a não inventar + informação de protocolo. +- **Transparência:** commits com contributo relevante de IA podem incluir o trailer + `Co-authored-by`. Código e documentação gerados ou assistidos por IA são revistos antes de entrar. + +## Legal + +- Análise feita sobre equipamento próprio, para fins de interoperabilidade. +- Este repositório não contém nem distribui código, APKs ou serviços da Harman. A implementação e + a documentação são originais. +- Todas as marcas pertencem aos respetivos titulares e são usadas apenas para descrever compatibilidade. + +## Contribuir + +Ainda é cedo. Se tiveres um MediaNav Evolution ou documentação do protocolo Aha de outros +fabricantes, abre um issue.