13.1.14. Repositórios de terceiros#

O IDE fornece placas, firmware, exemplos, modelos de aprendizagem automática 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. Chegam como third-party repositories: pastas de conteúdo que o IDE funde 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 gere um repositório publicado por outra pessoa. A última secção, authoring a repository, é para o fornecedor que está a construir uma.

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

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

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

13.1.14.2. Instalando um repositório#

A instalação a partir de URL pede o endereço do config.json de um repositório – o pequeno ficheiro de manifesto que o fornecedor publica – e instala tudo para o qual aponta. Cole o URL fornecido pelo fornecedor; o IDE descarrega o manifesto, procura 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 o reinício, pelo que o IDE se oferece para reiniciar quando a instalação estiver concluída.

Um fornecedor pode também distribuir um repositório como um instalador que o coloca diretamente no diretório da aplicação; nesse caso, estará simplesmente presente como uma linha Built-in na primeira vez que 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 diz-lhe o que é - listando cada repositório e as versões envolvidas - e oferece-se para o instalar, tudo num único prompt. O Check for Updates executa a mesma verificação a pedido.

13.1.14.4. Prioridade e substituições#

Os repositórios são uma lista ordenada, com a prioridade mais alta no topo, e o Mover para Cima e o 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 isto acontece, a entrada mais alta ganha e cada repositório ganha o conteúdo integrado do OpenMV. Isto é propositado - é a forma como um fornecedor fornece o seu próprio firmware para uma placa que partilha o identificador USB de uma placa OpenMV, substituindo o firmware padrão que o IDE lhe ofereceria, ou substitui um exemplo padrão por um escrito para o 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 a placa, exemplo, modelo ou stub do repositório que está a substituir 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 se estiver a comportar como descrito na documentação do OpenMV, este painel é o primeiro local a procurar.

13.1.14.5. O que um repositório fornece#

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

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

  • Examples. Os exemplos de um repositório aparecem em Ficheiro → Exemplos, fundidos na árvore de categorias: um exemplo numa categoria que o fornecedor nomeou igual a uma categoria OpenMV fica ao lado dos OpenMV, e uma nova categoria torna-se o seu próprio submenu. 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, fundidos na árvore do browser da mesma forma, com as próprias descrições do fornecedor.

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

13.1.14.6. Criando um repositório#

Um repositório é uma pasta com o nome do fornecedor, contendo um manifesto config.json e uma subpasta para cada tipo de conteúdo que 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 por uma letra. Cada pasta de peças é opcional; envie apenas o que tem. Ao lado de cada pasta de parte existe um ficheiro <part>.version contendo uma única string de versão (1.2.0) que o IDE utiliza para decidir quando é que 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 ficheiro 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 ficheiro está alojado; o IDE procura-o novamente para verificar se há atualizações, por isso omita-o apenas para um repositório que nunca será atualizado. Cada parte tem um canal release e o firmware pode também ter um canal development utilizado pela instalação da versão de desenvolvimento mais recente. Os valores da versão version são comparados como números, pelo que é oferecido um valor mais elevado como atualização; as versões de desenvolvimento são comparadas apenas para alterações. O sha256 é opcional, mas verifica-se quando presente.

Cada url aponta para .zip (apenas zip). Um ficheiro contém exatamente one top-level folder, e o IDE instala o contents dessa pasta como parte - depois o ficheiro 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 para a pasta firmware/ mostrada anteriormente. Os ficheiros de exemplos, modelos e stubs são empacotados da mesma forma - uma pasta de empacotamento contendo o que estaria dentro de examples/, models/ ou stubs/. O nome da pasta de empacotamento é ignorado; o que interessa é que existe exactamente um. Compactar os ficheiros na raiz do ficheiro sem pasta de empacotamento ou agrupá-los em mais do que uma pasta não será instalado. A forma mais simples de acertar é comprimir a própria pasta - selecione acme-firmware e comprima-a, em vez de selecionar o seu conteúdo.

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

firmware/settings.json utiliza 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 é utilizado pelo OpenMV ou outro fornecedor, uma vez que nomeia a pasta em que residem os seus binários), cada placa deve ter o 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 stock dessa 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 (carregam os drivers assinados do Windows); um identificador de aplicação que colide com uma placa integrada substitui essa placa, informada pelo painel de avisos de substituição.

Os exemplos vão para pastas de categorias numeradas como OpenMV (01-Getting-Started); uma categoria que nomeia da mesma forma que uma categoria OpenMV é intercalada nela, e um novo nome torna-se a sua própria secção de menu. Um modelo é uma pasta contendo o seu .tflite e um .txt correspondente de etiquetas de classe, agrupadas numa pasta cujo index.html (e uma imagem opcional) é a descrição mostrada ao lado no Model Zoo. examples/index.csv e models/index.csv são os mesmos ficheiros de filtro de placa e sensor que os próprios exemplos e modelos do OpenMV utilizam, comparados com o seu exemplo e caminhos de modelo, e decidem quais dos seus mostram para placa. Os stubs são ficheiros .pyi comuns; o IDE entrega a sua pasta ao servidor de idiomas para que sejam resolvidos juntamente 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, aloja o config.json e os ficheiros referenciados em URLs estáveis ​​e fornece aos utilizadores o URL config.json para instalar. Qualquer lugar que sirva ficheiros simples por HTTPS funciona – um servidor web, um armazenamento de objetos ou um host de código. Para enviar uma atualização, carregue novos ficheiros, coloque os valores version afetados no config.json alojado e, da próxima vez que o IDE de cada utilizador for iniciado, oferecerá a atualização. Os utilizadores que instalaram o repositório através de um instalador obtêm atualizações da mesma forma, desde que o config.json instalado carregue um configUrl.

13.1.14.6.4. Alojamento no GitHub#

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

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

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

Este URL em bruto é o que um utilizador cola em Instalar a partir do URL e o que se coloca no próprio configUrl do manifesto para que o IDE o vá buscar novamente para verificar se há atualizações. Apontar para um branch (main) significa que o envio de um novo commit publica a alteração; apontá-lo para uma etiqueta fixa os utilizadores numa versão fixa.

Hospede os ficheiros .zip como release assets em vez de os enviar - as versões são construídas para downloads binários, pelo que um pacote de firmware de vários megabytes pertence-lhe, não ao histórico do repositório. Anexe cada ficheiro a uma versão do GitHub e utilize o 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 ficheiro. Enviar uma atualização é então: anexar os novos ficheiros a um lançamento, editar config.json para os apontar e alterar as versões e confirmar. O IDE capta a alteração na sua próxima inicialização (o ficheiro em bruto é servido através de uma cache que é atualizada alguns minutos após o envio).