13.1.14. Repositorios de terceros#

El IDE envía las propias placas, firmware, ejemplos, modelos de aprendizaje automático y resguardos de editor de OpenMV, pero también puede cargar el mismo tipo de contenido de otras compañías: una placa construida por un socio, el firmware que se ejecuta en ella, ejemplos y modelos ajustados para ello, y finalización de código para las API que agrega el firmware. Estos llegan como third-party repositories: carpetas de contenido que el IDE fusiona con las suyas y las mantiene actualizadas.

Esta página tiene dos públicos. La mayor parte es para la persona que instala y administra un repositorio publicado por otra persona. La última sección, authoring a repository, es para el edificio del proveedor.

13.1.14.1. La página de repositorios de terceros#

Todo se gestiona desde Editar → Preferencias → OpenMV → Repositorios de terceros. La tabla enumera cada repositorio instalado y, para cada uno, su nombre para mostrar, su identificación corta, ya sea Built-in o User, la versión instalada de cada tipo de contenido que proporciona (firmware, ejemplos, modelos, resguardos) y la URL desde la que se actualiza.

Built-in significa que el repositorio fue colocado en el propio directorio de la aplicación mediante un instalador que envió el proveedor, de la misma manera que un paquete de controladores agrega archivos a un programa. User significa que lo instalaste tú mismo desde una URL. La única diferencia práctica es que no se puede eliminar un repositorio integrado del IDE (se elimina desinstalando lo que esté allí), por lo que el botón Eliminar está deshabilitado.

13.1.14.2. Instalar un repositorio#

Instalar desde URL solicita la dirección del config.json de un repositorio (el pequeño archivo de manifiesto que publica el proveedor) e instala todo lo que apunta. Pegue la URL que le proporcionó el proveedor; el IDE descarga el manifiesto, recupera el firmware, los ejemplos, los modelos y los códigos auxiliares que enumera y verifica cada descarga. La instalación, eliminación y actualización de un repositorio entran en vigor después de reiniciar, por lo que el IDE ofrece reiniciar cuando finaliza la instalación.

Un proveedor también puede distribuir un repositorio como un instalador que lo coloca directamente en el directorio de la aplicación, en cuyo caso simplemente está presente como una fila Built-in la primera vez que abre la página: no hay nada que instalar.

13.1.14.3. Mantener los repositorios actualizados#

Cada vez que se inicia el IDE se comprueba un repositorio que contiene una URL de actualización. Cuando hay contenido más nuevo disponible, el IDE le dice qué (enumera cada repositorio y las versiones involucradas) y le ofrece instalarlo, todo en un solo mensaje. Buscar actualizaciones ejecuta la misma verificación a pedido.

13.1.14.4. Prioridad y anulaciones#

Los repositorios son una lista ordenada, la prioridad más alta en la parte superior, y Mover hacia arriba y Mover hacia abajo reordenan el seleccionado. El orden solo importa cuando dos fuentes proporcionan el elemento same: una placa con el mismo identificador USB o un ejemplo, modelo o código auxiliar con el mismo nombre. Cuando eso sucede, gana la entrada más alta y cada repositorio gana sobre el contenido integrado de OpenMV. Esto es deliberado: así es como un proveedor suministra su propio firmware para una placa que comparte el identificador USB de una placa OpenMV, reemplazando el firmware original que el IDE ofrecería de otro modo, o reemplaza un ejemplo original con uno escrito para su hardware.

Debido a que una anulación cambia silenciosamente lo que hace un nombre familiar, la página nunca oculta uno. El panel de advertencias de anulación enumera todas las anulaciones vigentes (qué tablero, ejemplo, modelo o código auxiliar del repositorio está anulando cuál) y la misma lista aparece una vez como mensaje la primera vez que se ve un repositorio. Si una placa, ejemplo o modelo no se comporta como se describe en la documentación de OpenMV, este panel es el primer lugar donde buscar.

13.1.14.5. Qué proporciona un repositorio#

Cada uno de los cuatro tipos de contenido aparece en su lugar habitual en el IDE, por lo que una vez instalado un repositorio no hay nada nuevo que aprender:

  • Boards and firmware. La placa de un repositorio se comporta exactamente como una placa OpenMV: se reconoce al conectarse, su tipo se muestra en la barra de estado y su firmware se actualiza a través del IDE, incluida la ruta Instalar la última versión de desarrollo. Ver Actualizaciones y recuperación del firmware.

  • Examples. Los ejemplos de un repositorio aparecen en Archivo → Ejemplos, combinados en el árbol de categorías: un ejemplo en una categoría que el proveedor nombró igual que una categoría OpenMV se ubica junto a los de OpenMV, y una nueva categoría se convierte en su propio submenú. Se filtran a los foros que soportan como cualquier ejemplo. Ver Scripts, ejemplos y la carpeta de documentos.

  • Models. Los modelos de un repositorio aparecen en Model Zoo, fusionados en el árbol del navegador de la misma manera, con las propias descripciones del proveedor.

  • Stubs. Un repositorio puede enviar archivos stub .pyi, por lo que editor ofrece finalización, firmas y documentación para las funciones que agrega su firmware: la misma finalización que obtiene para los propios módulos de OpenMV, para la API personalizada de un proveedor.

13.1.14.6. Crear un repositorio#

Un repositorio es una carpeta con el nombre del proveedor, que contiene un manifiesto config.json y una subcarpeta para cada tipo de contenido que proporciona:

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

El nombre de la carpeta es la identificación del repositorio: letras minúsculas, dígitos, - y _, comenzando con una letra. Cada carpeta de piezas es opcional; envía solo lo que tienes. Al lado de cada carpeta de partes hay un archivo <part>.version que contiene una única cadena de versión (1.2.0) que el IDE usa para decidir cuándo una actualización es más nueva.

13.1.14.6.1. el manifiesto#

config.json nombra el repositorio y, para cada parte, apunta a un archivo descargable:

{
  "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 debe coincidir con el nombre de la carpeta. configUrl es la dirección en la que está alojado este mismo archivo; el IDE lo recupera para buscar actualizaciones, así que omítalo sólo para un repositorio que nunca se actualizará. Cada parte tiene un canal release y el firmware también puede tener un canal development utilizado para instalar la última versión de desarrollo. Los valores de la versión version se comparan como números, por lo que se ofrece uno más alto como actualización; Las versiones de desarrollo se comparan sólo para realizar cambios. El sha256 es opcional pero se verifica cuando está presente.

Cada url apunta a un .zip (solo cremallera). Un archivo contiene exactamente one top-level folder, y el IDE instala el contents de esa carpeta como parte, por lo que el archivo de firmware se empaqueta así:

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

y lo descomprime en la carpeta firmware/ que se mostró anteriormente. Los archivos de ejemplos, modelos y resguardos se empaquetan de la misma manera: una carpeta envolvente que contiene lo que se ubicaría dentro de examples/, models/ o stubs/. Se ignora el nombre de la carpeta de embalaje; lo que importa es que haya exactamente uno. No se instalará comprimir los archivos en la raíz del archivo sin una carpeta de embalaje o empaquetarlos en más de una carpeta. La forma más sencilla de hacerlo bien es comprimir la carpeta: seleccione acme-firmware y comprimirla, en lugar de seleccionar su contenido.

13.1.14.6.2. Tableros, ejemplos, modelos y resguardos.#

firmware/settings.json utiliza el mismo formato de descripción de placa que el firmware que envía el IDE; agregue una entrada boards para cada uno de sus tableros. Algunas reglas son específicas para placas de terceros: boardFirmwareFolder debe ser único (OpenMV u otro proveedor aún no lo utiliza, ya que nombra la carpeta en la que se encuentran sus archivos binarios), cada placa debe tener su propio firmware_version (esto es lo que impulsa el mensaje de actualización al conectarse), y una placa puede configurar boardFirmwareFolderAlias en el nombre de la carpeta de firmware de una placa OpenMV para heredar los ejemplos y modelos originales de esa placa: la trampilla de escape para una placa que sea compatible con firmware con una OpenMV. Se espera reutilizar los identificadores del gestor de arranque OpenMV (llevan los controladores de Windows firmados); un identificador de aplicación que choca con un tablero integrado anula ese tablero, lo que informa el panel Anular advertencias.

Los ejemplos van en carpetas de categorías numeradas como las de OpenMV (01-Getting-Started); una categoría a la que se le asigna el mismo nombre que OpenMV se intercala en ella y un nuevo nombre se convierte en su propia sección de menú. Un modelo es una carpeta que contiene su .tflite y un .txt coincidente de etiquetas de clase, agrupadas en una carpeta cuyo index.html (y una imagen opcional) es la descripción que se muestra a su lado en Model Zoo. examples/index.csv y models/index.csv son los mismos archivos de filtro de placa y sensor que usan los propios ejemplos y modelos de OpenMV, comparados con sus rutas de ejemplo y modelo, y decide cuál de los tuyos se muestra para qué placa. Los resguardos son archivos normales de .pyi; el IDE entrega su carpeta al servidor de idiomas para que se resuelva junto con OpenMV, y un código auxiliar con el nombre de un módulo existente (csi.pyi) anula la finalización de ese módulo.

13.1.14.6.3. Publicación y actualización#

Para publicar, aloje config.json y los archivos a los que hace referencia en URL estables y brinde a los usuarios la URL config.json para realizar la instalación. Cualquier lugar que proporcione archivos simples a través de HTTPS funciona: un servidor web, un almacén de objetos o un servidor de código. Para enviar una actualización, cargue nuevos archivos, aumente los valores version afectados en el config.json alojado y la próxima vez que se inicie el IDE de cada usuario, ofrecerá la actualización. Los usuarios que instalaron el repositorio a través de un instalador obtienen actualizaciones de la misma manera, siempre que el config.json instalado lleve un configUrl.

13.1.14.6.4. Alojamiento en GitHub#

GitHub es un host conveniente y el IDE obtiene de él de la misma manera que obtiene sus propios recursos. Hay dos piezas por colocar: el manifiesto y los archivos.

Mantenga el config.json en un repositorio y proporcione a los usuarios su URL raw: la dirección en la que se entrega el archivo directamente, no la página de GitHub que lo muestra. El botón Raw del archivo lo muestra; tiene la forma

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

Esa URL sin formato es lo que un usuario pega en Instalar desde URL y lo que usted coloca en el propio configUrl del manifiesto para que el IDE lo vuelva a buscar para buscar actualizaciones. Apuntarlo a una rama (main) significa presionar una nueva confirmación y publicar el cambio; apuntarlo a una etiqueta fija a los usuarios a una versión fija.

Aloje los archivos .zip como release assets en lugar de confirmarlos; las versiones se crean para descargas binarias, por lo que un paquete de firmware de varios megabytes pertenece allí, no en el historial del repositorio. Adjunte cada archivo a una versión de GitHub y use su URL de descarga, que tiene el formulario

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

en los campos url del manifiesto, cada uno con el sha256 del archivo. Entonces, enviar una actualización es: adjuntar los nuevos archivos a una versión, editar config.json para señalarlos y eliminar las versiones, y confirmar. El IDE recoge el cambio en su próximo lanzamiento (el archivo sin formato se entrega a través de un caché que se actualiza a los pocos minutos de la inserción).