Atualização de firmware do periférico via fwupd

Versão: 2.4.3
Última atualização: 23/07/2025

Visão geral

O objetivo deste guia é descrever como configurar atualizações de firmware do fwupd compatíveis com a interface do ChromeOS.

Contexto

O fwupd é um daemon de código aberto que realiza atualizações de firmware de periféricos e outros sistemas em sistemas baseados em Linux. O fwupd é o mecanismo pelo qual o ChromeOS atualiza o firmware de periféricos.

Os payloads de atualização do fwupd consistem em arquivos .cab armazenados no Linux Vendor Firmware Service (LVFS). No Linux, as atualizações do fwupd podem ser disponibilizadas depois que são enviadas para o LVFS. No entanto, para que as atualizações sejam disponibilizadas no ChromeOS, a equipe do ChromeOS vai verificar e adicionar à lista de permissões separadamente as novas atualizações para garantir a melhor experiência do usuário.

Processo fwupd

O seguinte se aplica apenas a periféricos certificados pela WWCB em que amostras foram enviadas para a Allion.

Se a versão atual do fwupd no ChromeOS ainda não for compatível com o periférico, siga as instruções fornecidas no caso de uso 1 e no caso de uso 2. Se a versão atual do fwupd no ChromeOS já for compatível com o periférico, pule para o caso de uso 2.

Caso de uso 1: a versão atual do fwupd do ChromeOS não é compatível com o periférico

A versão atual do fwupd no ChromeOS ainda não é compatível com o periférico.

1. ODMs e OEMs trabalham diretamente com fornecedores de chipset para enviar mudanças de plug-in na base de código do fwupd.

   1. Consulte o Manual de integração do fwupd (segunda etapa: usar o fwupd).
   2. Mudanças no plug-in: exemplo 1, exemplo 2
   3. Correspondência de VIDs:PIDs no arquivo .quirk: exemplo 3
      • Como alternativa às mudanças no arquivo de quirks, se o periférico USB for compatível com o plug-in atual, siga a especificação DS20.
   4. Ter as mudanças resultantes de plug-ins e quirks mescladas pelos mantenedores do fwupd.
   5. Aguarde o lançamento oficial do fwupd (ou seja, 1.8.4), anote a versão.

2. Os lançamentos do fwupd são espelhados regularmente no ChromeOS e seguem a programação de lançamentos do Chromium.

3. Se você enviar mudanças de plug-in, correções de bugs ou mudanças de arquivo de quirks após a data de corte do congelamento de recursos de uma próxima versão do Chromium, mas as mudanças forem de alta prioridade para a próxima versão do ChromeOS, faça o seguinte:

   1. Acesse o Rastreador de problemas do parceiro.
   2. Faça login com sua conta de domínio do Google Partner.

   3. Clique no botão Criar problema no menu à esquerda para criar um bug no seu componente (ChromeOS > External > WWCB > PERIPHERAL OEM > fwupd). Isso alerta a equipe do ChromeOS para atualizar a versão do fwupd no ChromeOS.

      Forneça as seguintes informações no bug:

      1. Título do bug:

         [PRODUCT NAME - fwupd]: New Plugin NAME OF THE PLUGIN requires fwupd X.Y.Z version uprev
         

      2. Descrição do bug:

         1. Número da versão do fwupd que consiste em mudanças de plug-in:
            • Quais recursos ele adiciona?
            • Quais bugs foram corrigidos?
            • Quais hardwares são compatíveis?
         2. Marca/modelo do dispositivo
         3. VID, PID
         4. GUID (identificador globalmente exclusivo)

      3. Exemplo de captura de tela:

         

4. O bug será triado, e a versão seletiva do fwupd será incorporada ao ChromeOS pelos engenheiros do Google.

   • Lista de mudanças de exemplo 1
   • Observação: o uprev do fwupd segue a programação de lançamento do Chromium. Envie a solicitação de uprev do fwupd antes da data de corte do congelamento de recursos da ramificação.

5. A versão atualizada do fwupd será promovida para o canal canário assim que a lista de mudanças for aprovada.

   • Deixe um comentário no bug para saber qual versão de build do ChromeOS consiste na versão atualizada do fwupd. Você também pode usar o CL Finder para pesquisar a versão do build no Console de parceiros do ChromeOS (CPCon) (requer uma conta de domínio de parceiro corporativo do Google. Entre em contato com os TAMs para acessar o CPCon).

Caso de uso 2: a versão atual do fwupd do ChromeOS é compatível com o periférico

A versão atual do fwupd no ChromeOS já é compatível com o periférico e um novo firmware está disponível.

1. Crie um arquivo .cab.

   Todo o firmware é enviado como um arquivo de gabinete. Além do binário do firmware, a LVFS espera que o arquivo contenha pelo menos um arquivo .metainfo.xml que descreva o dispositivo e o firmware de destino. É possível criar um arquivo de gabinete usando gcab (uma biblioteca para criar arquivos de gabinete) no Linux.

2. Faça upload da atualização de firmware testada e final (arquivo .cab) para o LVFS.

   1. Verifique se a atualização está disponível no controle remoto estável.

      Se ele estiver disponível no repositório privado, embargado ou de teste remoto, ele não será adicionado ao espelho do ChromeOS.

   2. Atualizações marcadas como validadas na LVFS por um relatório assinado.

      Confira se os testes de dispositivo foram adicionados.

      • Exemplo de arquivo JSON, compatível com o framework de teste para testes de dispositivos

   3. Se este for o primeiro upload de firmware, verifique se pelo menos dois firmwares,o firmware base (para testar o downgrade) e o novo firmware (para testar o upgrade), estão disponíveis no repositório remoto estável do LVFS.

3. O upgrade de firmware precisa ser testado no ChromeOS usando um relatório assinado.

   1. Faça upload dos certificados para o LVFS e vincule o DUT à sua conta.

      1. Faça login no LVFS com sua conta.
      2. Clique no ícone "Pessoa" no canto superior direito ou em https://fwupd.org/lvfs/profile{:.external}.
      3. Clique em Configurações do perfil.

      4. Localize o Certificado do cliente no Chromebook.

         • Observação: o Chromebook precisa estar no modo de desenvolvedor.
         • Inicie o shell do desenvolvedor do ChromeOS pressionando ctrl+alt+t

         • Tipo:

           shell

         • Navegue até /var/lib/fwupd/pki:

           cd /var/lib/fwupd/pki

         • Copie o client.pem para uma pasta no Chromebook, por exemplo: Downloads.

           cp client.pm /home/chronos/user/MyFiles/Downloads/

   2. Clique no botão Fazer upload do certificado na seção Certificados do cliente do site da LVFS e faça upload do certificado.

      1. Repita essas etapas em cada Chromebook que você estiver usando para teste. É possível fazer upload de vários certificados para computadores diferentes.

   3. Teste o upgrade e faça upload de relatórios assinados usando o DUT.

      1. Para testar e fazer upload de relatórios, execute os seguintes comandos e faça a autenticação quando solicitado.

         fwupdmgr refresh
         fwupdmgr update
         fwupdmgr report-history --sign

      2. Observação: se você já enviou relatórios sem a flag --sign, use fwupdmgr report-history --sign --force para reenviar o mesmo relatório para o LVFS.

         fwupdmgr report-history --sign --force

         • Você pode transmitir --verbose para ver a resposta do servidor.

           fwupdmgr report-history --force --verbose

      3. Clique em Sim na caixa de diálogo de confirmação.

         • Isso vai fazer upload do relatório assinado na sua conta.
         • Para confirmar, acesse https://fwupd.org/lvfs/dashboard e clique em Relatórios assinados na seção Página inicial no canto superior esquerdo.
      Observação: o relatório leva cerca de 4 horas para aparecer no LVFS.

   4. Verificar se a versão do firmware no LVFS tem relatórios assinados

      • Pesquise o periférico no LVFS.
      • Se o relatório assinado enviado foi depois de atualizar a versão do firmware no periférico usando um Chromebook, a seção Testado por vai mostrar a versão do ChromeOS, a versão do fwupd e a entidade. Confira um exemplo.
      • Verifique se Controle de lançamento mostra uma marca de seleção verde "Disponível para usuários do ChromeOS".

   5. A partir do M126, as atualizações de firmware só estarão disponíveis para usuários do ChromeOS se o firmware tiver relatórios assinados (testados com o ChromeOS) no LVFS.

      • Após 24 horas, os usuários podem conectar o periférico ao Chromebook e atualizar o firmware pela interface do ChromeOS. Acesse Configurações > Sobre o ChromeOS > Atualizações de firmware.
      • Observação: as atualizações de firmware estarão disponíveis se todas as mudanças necessárias de plug-in estiverem disponíveis no ChromeOS para um determinado marco.

Mais detalhes sobre relatórios assinados podem ser encontrados no LVFS.

Perguntas frequentes

P: Qual Chromebook é compatível com fwupd?

Todos os dispositivos ChromeOS na versão M101 ou mais recente.

P: Como saber qual versão do fwupd está integrada ao ChromeOS?

1. Abra chrome://system no navegador (M109 ou mais recente).
   1. Navegue para fwupd_version.
2. Ou no modo de desenvolvedor, console raiz,
   1. Tipo fwupdmgr --version
   2. Procure runtime org.freedesktop.fwupd

P: Quanto tempo leva o processo de atualização do fwupd?

O fwupd uprev segue a programação de lançamento do Chromium. Verifique se a solicitação de fwupd uprev foi enviada antes da data limite de congelamento de recursos da ramificação.

P: Onde posso encontrar mais informações sobre a programação de lançamentos do ChromeOS?

Na programação de lançamentos do Chromium.

P: Como mudar um Chromebook para o modo de desenvolvedor?

1. Desligue o Chromebook.
2. Mantenha pressionadas as teclas esc+Atualizar e pressione o botão liga/desliga.
   • Observação: em alguns Chromebooks, pressione esc+→ (tecla de seta para a direita) e o botão liga/desliga.
3. O dispositivo vai ligar, e a tela / o modo de recuperação vai aparecer.
4. Em seguida, pressione ctrl+d e Enter para aceitar.
   • Observação: se você pressionar qualquer tecla antes de ctrl+d, o dispositivo não vai entrar no modo de desenvolvedor.
5. O dispositivo será reiniciado, vai emitir um bipe e você verá a mensagem "Seu sistema está fazendo a transição para o modo de desenvolvedor".
6. Após cerca de 30 segundos, você vai ver "Preparando o sistema para o modo desenvolvedor".
7. Depois de um tempo (de 10 minutos a mais de uma hora, dependendo do tamanho do disco), o dispositivo será reiniciado na tela de boas-vindas normal.
8. Para abrir o prompt de comando, pressione ctrl+alt+→ (seta para a direita).
   • Observação:em alguns Chromebooks, é a tecla ctrl+alt+atualizar.
   • Para voltar à visualização do navegador, pressione ctrl+alt+← (tecla de seta para a esquerda).
9. Mais detalhes podem ser encontrados em [Modo de desenvolvedor]

P: Como mudar um Chromebook para o modo normal (ou seja, desativar o modo de desenvolvedor)?

Reinicie o dispositivo e pressione a barra de espaço na tela do firmware.

Confira mais detalhes em [Modo de desenvolvedor].

P: O ChromeOS aceita downgrades via fwupd?

Não. Se a versão de produção do fwupd ou o firmware falhar, você terá que excluir o relatório assinado em https://fwupd.org/lvfs/dashboard. É importante testar sempre que você enviar mudanças no plug-in e/ou tiver um novo firmware disponível. Garantir que uma versão básica do firmware esteja sempre disponível em um controle remoto estável do LVFS.

P: Como saber quais versões do ChromeOS são compatíveis com quais atualizações do fwupd?

Você pode deixar um comentário no bug perguntando em qual versão de build as mudanças foram incorporadas. Os engenheiros do Google poderão fornecer essas informações. Você também pode usar o CL Finder para pesquisar a versão do build no Console de parceiros do ChromeOS (CPCon). Isso exige uma conta de domínio corporativa do Google para parceiros. Entre em contato com os TAMs para acessar o CPCon. É possível fazer uma referência cruzada à versão do build no ChromeOS Partner Frontend (CPFE) para saber a qual marco ela corresponde.

P: Como criar uma conta do LVFS?

Consulte a documentação da LVFS Como criar uma conta.

P: Como fazer upload de arquivos CAB para o LVFS?

Consulte a documentação da LVFS sobre Como fazer upload de firmware.

P: Como garantir que um firmware é para um periférico específico?

Isso é possível usando o arquivo de configuração mais conhecido. Consulte a Melhor configuração conhecida do fwupd para mais informações.

P: Como posso testar minha atualização do fwupd antes de fazer upload para o LVFS?

Depois que as mudanças no plug-in forem enviadas e a versão seletiva do fwupd for incorporada à imagem de teste do ChromeOS, você poderá acessar a imagem de teste pelo front-end do parceiro do ChromeOS (CPFE, na sigla em inglês). Isso exige uma conta de domínio de parceiro corporativo do Google. Entre em contato com os TAMs para ter acesso ao CPFE.

Consulte a documentação do LVFS Teste de firmware no ChromeOS. Você também pode executar testes do fwupd com o Moblab.

P: Como um usuário vai saber que uma atualização de firmware está disponível para o periférico dele?

O usuário vai receber uma notificação informando que uma atualização está disponível com base na urgência atribuída a ela no LVFS. O comportamento é o seguinte:

Urgência	Comportamento de notificação
Baixo	O usuário não vai receber notificações e terá que verificar manualmente se há atualizações.
Médio
Alta
Crítico	A notificação vai aparecer em todas as inicializações até que a atualização seja concluída.

P: As atualizações do fwupd acontecem automaticamente?

Não. Todas as atualizações do fwupd são iniciadas pelo usuário e não acontecem durante a inicialização nem de forma automática.

P: Qual é a vantagem da especificação DS20?

No momento, a verificação é feita apenas para periféricos USB. Se você usar o mesmo protocolo que no outro hardware, ele vai funcionar com um descritor DS20.

Os fornecedores podem colocar os dados do arquivo de quirk no descritor USB em vez de no projeto fwupd. Assim, o dispositivo USB é inserido, o fwupd lê os dados do descritor, corresponde ao plug-in e enumera o dispositivo sem precisar que o fornecedor envie um patch para o fwupd e espere o uprev do fwupd.

P: O DS20 é uma opção alternativa para mudanças apenas no arquivo de quirks?

Sim. Na maioria das vezes, o hardware futuro só precisa que VID&PIDs sejam adicionados a um plug-in existente, em vez de mudanças reais no código. Se forem necessárias mudanças no código, o fornecedor precisará enviar as alterações do plug-in para o fwupd.

Anexos

1. Guia do desenvolvedor
2. Suporte para desenvolvedores
3. Introdução ao Git e ao Gerrit para colaboradores do CrOS
4. Fazer mudanças no código-fonte
5. Processo de análise/aprovação do Gerrit
6. Manual de integração do fwupd (em inglês)

Histórico de revisões

Data	Versão	Observações
2025-07-23	2.4.3	Atualizar o fluxo de trabalho do caso de uso 1
2024-10-18	2.4.2	Atualizar imagens e etapas do fluxo de trabalho do fwupd para fazer upload do certificado do cliente
2024-07-23	2.4.1	Atualizações de formatação.
2024-06-26	2.4	Atualização do fluxo de trabalho fwupd uprev (caso de uso 1). Publicado com a versão 2.4.1.
2024-06-17	2.3	Atualizar o fluxo de trabalho de relatório assinado. (publicado com a versão 2.4.1)
2024-02-01	2.2	Republicação em uma nova plataforma; pequenas atualizações de texto.
2023-10-12	2.1	Adicionamos imagens nos casos 1 e 2, o manual de integração do fwupd hospedado no site do parceiro.
2022-08-14	2,0	Publicação inicial do site do parceiro