13.1.14. Repositórios de terceiros#

O IDE fornece placas, firmware, exemplos, modelos de aprendizado de máquina e stubs de editor próprios do OpenMV, mas também pode carregar os mesmos tipos de conteúdo de outras empresas - uma placa construída por um parceiro, o firmware que é executado nela, exemplos e modelos ajustados para ela e conclusão de código para as APIs que o firmware adiciona. Eles chegam como third-party repositories: pastas de conteúdo que o IDE mescla com o seu próprio e mantém atualizado.

Esta página tem dois públicos. A maior parte é para a pessoa que instala e gerencia um repositório publicado por outra pessoa. A última seção, authoring a repository, é para o fornecedor que está construindo uma.

13.1.14.1. A página Repositórios de terceiros#

Tudo é gerenciado em Editar → Preferências → OpenMV → Repositórios de terceiros. A tabela lista cada repositório instalado e, para cada um, seu nome de exibição, seu ID abreviado, seja Built-in ou User, a versão instalada de cada tipo de conteúdo que ele fornece – firmware, exemplos, modelos, stubs – e a URL a partir da qual ele atualiza.

Built-in significa que o repositório foi colocado no próprio diretório do aplicativo por um instalador fornecido pelo fornecedor, da mesma forma que um pacote de driver adiciona arquivos a um programa. User significa que você mesmo instalou a partir de um URL. A única diferença prática é que você não pode remover um repositório interno do IDE - ele é removido desinstalando o que quer que esteja lá - então o botão Remover está desabilitado para ele.

13.1.14.2. Instalando um repositório#

Instalar a partir de URL pede o endereço do config.json de um repositório – o pequeno arquivo de manifesto que o fornecedor publica – e instala tudo para o qual aponta. Cole o URL fornecido pelo fornecedor; o IDE baixa o manifesto, busca o firmware, exemplos, modelos e stubs que lista e verifica cada download. A instalação, a remoção e a atualização de um repositório entram em vigor após a reinicialização, portanto, o IDE se oferece para reiniciar quando a instalação for concluída.

Um fornecedor também pode distribuir um repositório como um instalador que o coloca diretamente no diretório do aplicativo; nesse caso, ele estará simplesmente presente como uma linha Built-in na primeira vez que você abrir a página - nada para instalar.

13.1.14.3. Mantendo os repositórios atualizados#

Um repositório que contém um URL de atualização é verificado sempre que o IDE é iniciado. Quando um conteúdo mais recente está disponível, o IDE informa o que é - listando cada repositório e as versões envolvidas - e se oferece para instalá-lo, tudo em um único prompt. Check for Updates executa a mesma verificação sob demanda.

13.1.14.4. Prioridade e substituições#

Os repositórios são uma lista ordenada, com a prioridade mais alta no topo, e Mover para Cima e Mover para Baixo reordenam o selecionado. A ordem só importa quando duas fontes fornecem o same: uma placa com o mesmo identificador USB ou um exemplo, modelo ou stub com o mesmo nome. Quando isso acontece, a entrada mais alta vence e cada repositório vence o conteúdo integrado do OpenMV. Isso é deliberado - é como um fornecedor fornece seu próprio firmware para uma placa que compartilha o identificador USB de uma placa OpenMV, substituindo o firmware padrão que o IDE ofereceria para ela, ou substitui um exemplo padrão por um escrito para seu hardware.

Como uma substituição altera silenciosamente o que um nome familiar faz, a página nunca oculta um nome. O painel Override warnings lista todas as substituições em vigor - qual placa, exemplo, modelo ou stub do repositório está substituindo qual - e a mesma lista aparece uma vez como uma mensagem na primeira vez que um repositório é visto. Se uma placa, exemplo ou modelo não estiver se comportando conforme descrito na documentação do OpenMV, este painel é o primeiro lugar a procurar.

13.1.14.5. O que um repositório fornece#

Cada um dos quatro tipos de conteúdo aparece em seu lugar habitual no IDE, portanto, depois que um repositório é instalado, não há nada de novo para aprender:

  • Boards and firmware. A placa de um repositório se comporta exatamente como uma placa OpenMV - ela é reconhecida na conexão, seu tipo é mostrado na barra de status e seu firmware é atualizado através do IDE, incluindo o caminho Instalar a versão de desenvolvimento mais recente. Consulte Atualizações e recuperação de firmware.

  • Examples. Os exemplos de um repositório aparecem em Arquivo → Exemplos, mesclados na árvore de categorias: um exemplo em uma categoria que o fornecedor nomeou igual a uma categoria OpenMV fica ao lado dos OpenMV, e uma nova categoria se torna seu próprio submenu. Eles são filtrados nas placas que suportam, como qualquer exemplo. Consulte Scripts, exemplos e a pasta de documentos.

  • Models. Os modelos de um repositório aparecem em Model Zoo, mesclados na árvore do navegador da mesma forma, com as próprias descrições do fornecedor.

  • Stubs. Um repositório pode enviar arquivos stub .pyi para que editor ofereça preenchimento, assinaturas e documentação para as funções que seu firmware adiciona - o mesmo preenchimento que você obtém para os próprios módulos do OpenMV, para a API personalizada de um fornecedor.

13.1.14.6. Criando um repositório#

Um repositório é uma pasta nomeada em homenagem ao fornecedor, contendo um manifesto config.json e uma subpasta para cada tipo de conteúdo que ele fornece:

acme/
  config.json
  firmware/
    settings.json                 board descriptions
    ACME_CAM1/                    one folder per board, named by boardFirmwareFolder
      firmware.bin
      romfs0.img
  firmware.version
  examples/
    index.csv                     which examples show for which board / sensor
    01-Getting-Started/           numbered category folders, same as OpenMV's
      hello_acme.py
      read_sensor.py
    02-Acme-Widgets/
      spin_widget.py
  examples.version
  models/
    index.csv                     which models show for which board
    acme/                         a group; its index.html + image describe it
      index.html
      image.jpg
      person_detector/            one folder per model
        person_detector.tflite
        person_detector.txt       class labels
  models.version
  stubs/
    acme_hal.pyi                  a module the firmware adds
    csi.pyi                       overrides OpenMV's to add methods
  stubs.version

O nome da pasta é o id do repositório: letras minúsculas, dígitos, - e _, começando com uma letra. Cada pasta de peças é opcional; envie apenas o que você tem. Ao lado de cada pasta de parte há um arquivo <part>.version contendo uma única string de versão (1.2.0) que o IDE usa para decidir quando uma atualização é mais recente.

13.1.14.6.1. O manifesto#

config.json nomeia o repositório e, para cada parte, aponta para um arquivo para download:

{
  "name": "acme",
  "displayName": "Acme Robotics",
  "homepage": "https://acme.example",
  "configUrl": "https://acme.example/openmv/config.json",
  "firmware": {
    "release":     { "version": "1.2.0", "url": "https://acme.example/acme-fw-1.2.0.zip", "sha256": "..." },
    "development": { "version": "dev-20260701", "url": "https://acme.example/acme-fw-dev.zip", "sha256": "..." }
  },
  "examples": { "release": { "version": "1.1.0", "url": "https://acme.example/acme-examples-1.1.0.zip", "sha256": "..." } },
  "models":   { "release": { "version": "1.0.0", "url": "https://acme.example/acme-models-1.0.0.zip", "sha256": "..." } },
  "stubs":    { "release": { "version": "1.0.0", "url": "https://acme.example/acme-stubs-1.0.0.zip", "sha256": "..." } }
}

name deve corresponder ao nome da pasta. configUrl é o endereço em que este mesmo arquivo está hospedado; o IDE o busca novamente para verificar se há atualizações, portanto, omita-o apenas para um repositório que nunca será atualizado. Cada parte possui um canal release e o firmware também pode ter um canal development usado pela instalação da versão de desenvolvimento mais recente. Os valores da versão version são comparados como números, portanto, um valor mais alto é oferecido como atualização; versões de desenvolvimento são comparadas apenas para alterações. O sha256 é opcional, mas é verificado quando presente.

Cada url aponta para .zip (somente zip). Um arquivo contém exatamente one top-level folder, e o IDE instala o contents dessa pasta como parte - então o arquivo de firmware é empacotado assim:

acme-fw-1.2.0.zip
  acme-firmware/           one wrapping folder; its name does not matter
    settings.json
    ACME_CAM1/
      firmware.bin
      romfs0.img

e descompacta na pasta firmware/ mostrada anteriormente. Os arquivos de exemplos, modelos e stubs são empacotados da mesma maneira - uma pasta de empacotamento contendo o que ficaria dentro de examples/, models/ ou stubs/. O nome da pasta de empacotamento é ignorado; o que importa é que existe exatamente um. Compactar os arquivos na raiz do arquivo sem pasta de empacotamento ou agrupá-los em mais de uma pasta não será instalado. A maneira mais simples de acertar é compactar a própria pasta - selecione acme-firmware e compacte-a, em vez de selecionar seu conteúdo.

13.1.14.6.2. Quadros, exemplos, modelos e esboços#

firmware/settings.json usa o mesmo formato de descrição da placa que o firmware fornecido pelo IDE; adicione uma entrada boards para cada um dos seus painéis. Algumas regras são específicas para placas de terceiros: boardFirmwareFolder deve ser único (ainda não é usado pelo OpenMV ou outro fornecedor, pois nomeia a pasta em que seus binários residem), cada placa deve ter seu próprio firmware_version (isto é o que impulsiona o prompt update-on-connect), e uma placa pode definir boardFirmwareFolderAlias para o nome da pasta de firmware de uma placa OpenMV para herdar os exemplos e modelos de estoque daquela placa - o escape hachura para uma placa que seja compatível com firmware com uma placa OpenMV. A reutilização dos identificadores do bootloader OpenMV é esperada (eles carregam os drivers assinados do Windows); um identificador de aplicativo que colide com uma placa integrada substitui essa placa, informada pelo painel de avisos de substituição.

Os exemplos vão em pastas de categorias numeradas como OpenMV (01-Getting-Started); uma categoria que você nomeia da mesma forma que uma categoria OpenMV é intercalada nela, e um novo nome se torna sua própria seção de menu. Um modelo é uma pasta contendo seu .tflite e um .txt correspondente de rótulos de classe, agrupados em uma pasta cujo index.html (e uma imagem opcional) é a descrição mostrada ao lado dele no Model Zoo. examples/index.csv e models/index.csv são os mesmos arquivos de filtro de placa e sensor que os próprios exemplos e modelos do OpenMV usam, comparados com seu exemplo e caminhos de modelo, e decidem quais dos seus mostram para qual placa. Stubs são arquivos .pyi comuns; o IDE entrega sua pasta ao servidor de idiomas para que eles sejam resolvidos junto com o OpenMV, e um stub nomeado para um módulo existente (csi.pyi) substitui a conclusão desse módulo.

13.1.14.6.3. Publicação e atualização#

Para publicar, hospede o config.json e os arquivos referenciados em URLs estáveis ​​e forneça aos usuários o URL config.json para instalar. Qualquer lugar que sirva arquivos simples por HTTPS funciona – um servidor web, um armazenamento de objetos ou um host de código. Para enviar uma atualização, carregue novos arquivos, coloque os valores version afetados no config.json hospedado e, na próxima vez que o IDE de cada usuário for iniciado, ele oferecerá a atualização. Os usuários que instalaram o repositório por meio de um instalador obtêm atualizações da mesma maneira, desde que o config.json instalado carregue um configUrl.

13.1.14.6.4. Hospedagem no GitHub#

O GitHub é um host conveniente, e o IDE busca nele da mesma forma que busca seus próprios recursos. Existem duas peças para colocar: o manifesto e os arquivos.

Mantenha o config.json em um repositório e forneça aos usuários seu URL raw – o endereço no qual o arquivo é servido diretamente, não a página do GitHub que o exibe. O botão Raw no arquivo mostra isso; tem a forma

https://raw.githubusercontent.com/<user>/<repo>/<branch>/config.json

Esse URL bruto é o que um usuário cola em Instalar do URL e o que você coloca no próprio configUrl do manifesto para que o IDE o busque novamente para verificar se há atualizações. Apontar para um branch (main) significa que enviar um novo commit publica a mudança; apontá-lo para uma tag fixa os usuários em uma versão fixa.

Hospede os arquivos .zip como release assets em vez de enviá-los - as versões são construídas para downloads binários, portanto, um pacote de firmware de vários megabytes pertence a ele, não ao histórico do repositório. Anexe cada arquivo a uma versão do GitHub e use seu URL de download, que tem o formato

https://github.com/<user>/<repo>/releases/download/<tag>/acme-fw-1.2.0.zip

nos campos url do manifesto, cada um com o sha256 do arquivo. Enviar uma atualização é então: anexar os novos arquivos a um lançamento, editar config.json para apontá-los e alterar as versões e confirmar. O IDE capta a alteração em sua próxima inicialização (o arquivo bruto é servido por meio de um cache que é atualizado alguns minutos após o envio).