13.1.14. Repository di terze parti#

L’IDE fornisce le schede, il firmware, gli esempi, i modelli di apprendimento automatico e gli stub dell’editor di OpenMV, ma può caricare gli stessi tipi di contenuti anche di altre società: una scheda creata da un partner, il firmware che viene eseguito su di essa, esempi e modelli ottimizzati per esso e completamento del codice per le API aggiunte dal firmware. Questi arrivano come third-party repositories: cartelle di contenuti che l’IDE unisce ai propri e mantiene aggiornate.

Questa pagina ha due segmenti di pubblico. La maggior parte spetta alla persona che installa e gestisce un repository pubblicato da qualcun altro. L’ultima sezione, authoring a repository, è per la costruzione del venditore.

13.1.14.1. La pagina Repository di terze parti#

Tutto è gestito da Modifica → Preferenze → OpenMV → Repository di terze parti. La tabella elenca ogni repository installato e, per ciascuno, il nome visualizzato, l’ID breve, che sia Built-in o User, la versione installata di ogni tipo di contenuto fornito (firmware, esempi, modelli, stub) e l’URL da cui si aggiorna.

Built-in significa che il repository è stato inserito nella directory dell’applicazione da un programma di installazione fornito dal fornitore, nello stesso modo in cui un pacchetto driver aggiunge file a un programma. User significa che l’hai installato tu stesso da un URL. L’unica differenza pratica è che non è possibile rimuovere un repository integrato dall’IDE: viene rimosso disinstallando qualunque cosa lo abbia messo lì, quindi il pulsante Rimuovi è disabilitato.

13.1.14.2. Installazione di un archivio#

Installa da URL richiede l’indirizzo di config.json di un repository, il piccolo file manifest pubblicato dal fornitore, e installa tutto ciò a cui punta. Incolla l’URL che ti ha fornito il venditore; l’IDE scarica il manifest, recupera il firmware, gli esempi, i modelli e gli stub che elenca e verifica ogni download. L’installazione, la rimozione e l’aggiornamento di un repository hanno tutti effetto dopo il riavvio, quindi l’IDE offre il riavvio al termine dell’installazione.

Un fornitore può anche distribuire un repository come programma di installazione che lo inserisce direttamente nella directory dell’applicazione, nel qual caso è semplicemente presente come riga Built-in la prima volta che apri la pagina: niente da installare.

13.1.14.3. Mantenere aggiornati i repository#

Un repository che contiene un URL di aggiornamento viene controllato ogni volta che viene avviato l’IDE. Quando è disponibile un contenuto più recente, l’IDE ti dice cosa - elencando ciascun repository e le versioni coinvolte - e offre di installarlo, il tutto in un unico prompt. Verifica aggiornamenti esegue lo stesso controllo su richiesta.

13.1.14.4. Priorità e override#

I repository sono un elenco ordinato, con la priorità più alta in alto e Sposta su e Sposta giù riordinano quello selezionato. L’ordine conta solo quando due fonti forniscono la cosa same: una scheda con lo stesso identificatore USB o un esempio, modello o stub con lo stesso nome. Quando ciò accade, vince la voce più alta e ogni repository vince sul contenuto integrato di OpenMV. Questo è intenzionale: è il modo in cui un fornitore fornisce il proprio firmware per una scheda che condivide l’identificatore USB di una scheda OpenMV, sostituendo il firmware di serie che l’IDE altrimenti offrirebbe per essa, o sostituisce un esempio di serie con uno scritto per il proprio hardware.

Poiché una sostituzione modifica silenziosamente ciò che fa un nome familiare, la pagina non ne nasconde mai uno. Il pannello Avvisi di override elenca ogni override in vigore - quale scheda, esempio, modello o stub del repository sta sovrascrivendo quale - e lo stesso elenco appare una volta come messaggio la prima volta che viene visualizzato un repository. Se una scheda, un esempio o un modello non si comporta come descritto nella documentazione di OpenMV, questo pannello è il primo posto in cui cercare.

13.1.14.5. Cosa fornisce un repository#

I quattro tipi di contenuto appaiono ciascuno nella loro posizione abituale nell’IDE, quindi una volta installato un repository non c’è nulla di nuovo da imparare:

  • Boards and firmware. La scheda di un repository si comporta esattamente come una scheda OpenMV: viene riconosciuta alla connessione, il suo tipo viene visualizzato nella barra di stato e gli aggiornamenti del firmware tramite l’IDE, incluso il percorso Installa l’ultima versione di sviluppo. Vedi Aggiornamento e ripristino del firmware.

  • Examples. Gli esempi di un repository appaiono in File → Esempi, uniti nell’albero delle categorie: un esempio in una categoria che il fornitore ha chiamato come una categoria OpenMV si trova accanto a quelle OpenMV e una nuova categoria diventa il suo sottomenu. Vengono filtrati in base alle schede che supportano come ogni esempio. Vedi Script, esempi e la cartella documenti.

  • Models. I modelli di un repository appaiono in Model Zoo, uniti nell’albero del browser allo stesso modo, con le descrizioni del fornitore.

  • Stubs. Un repository può fornire file stub .pyi in modo che editor offra completamento, firme e documentazione per le funzioni aggiunte dal firmware: lo stesso completamento che ottieni per i moduli di OpenMV, per l’API personalizzata di un fornitore.

13.1.14.6. Creazione di un repository#

Un repository è una cartella denominata in base al fornitore, contenente un manifest config.json e una sottocartella per ogni tipo di contenuto fornito:

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

Il nome della cartella è l’ID del repository: lettere minuscole, cifre, - e _, che iniziano con una lettera. Ogni cartella di parti è facoltativa; spedisci solo quello che hai. Accanto a ciascuna cartella della parte c’è un file <part>.version che contiene una singola stringa di versione (1.2.0) che l’IDE utilizza per decidere quando un aggiornamento è più recente.

13.1.14.6.1. Il manifesto#

config.json nomina il repository e, per ciascuna parte, punta a un archivio scaricabile:

{
  "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 corrispondere al nome della cartella. configUrl è l’indirizzo in cui è ospitato lo stesso file; l’IDE lo recupera nuovamente per verificare la presenza di aggiornamenti, quindi omettilo solo per un repository che non verrà mai aggiornato. Ciascuna parte ha un canale release e il firmware può anche avere un canale development utilizzato da Installa l’ultima versione di sviluppo. I valori della versione version vengono confrontati come numeri, quindi ne viene offerto uno più alto come aggiornamento; le versioni di sviluppo vengono confrontate solo per la modifica. Il sha256 è facoltativo ma è verificato quando presente.

Ogni url punta a .zip (solo zip). Un archivio contiene esattamente one top-level folder e l’IDE installa contents di quella cartella come parte, quindi l’archivio del firmware è confezionato in questo modo:

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 decomprime nella cartella firmware/ mostrata in precedenza. Gli esempi, i modelli e gli archivi degli stub sono confezionati allo stesso modo: una cartella che contiene ciò che si troverebbe all’interno di examples/, models/ o stubs/. Il nome della cartella di confezionamento viene ignorato; ciò che conta è che ce ne sia esattamente uno. La compressione dei file nella radice dell’archivio senza cartella di confezionamento o il loro confezionamento in più di una cartella non verrà installata. Il modo più semplice per farlo bene è comprimere la cartella stessa: selezionare acme-firmware e comprimerla, anziché selezionarne il contenuto.

13.1.14.6.2. Tavole, esempi, modelli e stub#

firmware/settings.json utilizza lo stesso formato di descrizione della scheda del firmware fornito dall’IDE; aggiungi una voce boards per ciascuna delle tue schede. Alcune regole sono specifiche per le schede di terze parti: boardFirmwareFolder deve essere univoco (non è ancora utilizzato da OpenMV o da un altro fornitore, poiché nomina la cartella in cui risiedono i file binari), ciascuna scheda deve avere il proprio firmware_version (questo è ciò che attiva il prompt di aggiornamento alla connessione) e una scheda può impostare boardFirmwareFolderAlias sul nome della cartella del firmware di una scheda OpenMV per ereditare gli esempi e i modelli stock di quella scheda: il portello di fuga per una scheda compatibile firmware con una scheda OpenMV. È previsto il riutilizzo degli identificatori del bootloader OpenMV (portano i driver Windows firmati); un identificatore dell’app che entra in collisione con una scheda integrata sovrascrive tale scheda, come riportato nel pannello Avvisi di sostituzione.

Gli esempi vanno in cartelle di categorie numerate come OpenMV (01-Getting-Started); una categoria a cui hai assegnato lo stesso nome di OpenMV si intercala in essa e un nuovo nome diventa la sua sezione di menu. Un modello è una cartella che contiene le sue .tflite e .txt corrispondenti di etichette di classe, raggruppate in una cartella il cui index.html (e un’immagine opzionale) è la descrizione mostrata accanto nello Zoo modello. examples/index.csv e models/index.csv sono gli stessi file di scheda e filtro del sensore utilizzati dagli esempi e dai modelli di OpenMV, confrontati con i percorsi di esempio e modello e decidi quale dei tuoi mostrare per quale scheda. Gli stub sono normali file .pyi; l’IDE passa la propria cartella al server della lingua in modo che si risolvano insieme a quella di OpenMV e uno stub denominato per un modulo esistente (csi.pyi) sovrascrive il completamento di quel modulo.

13.1.14.6.3. Pubblicazione e aggiornamento#

Per pubblicare, ospita config.json e gli archivi a cui fa riferimento su URL stabili e fornisci agli utenti l’URL config.json da cui eseguire l’installazione. Funziona ovunque che serva file semplici su HTTPS: un server Web, un archivio di oggetti o un host di codice. Per spedire un aggiornamento, carica nuovi archivi, aumenta i valori version interessati nel config.json ospitato e la prossima volta che l’IDE di ogni utente viene avviato offre l’aggiornamento. Gli utenti che hanno installato il repository tramite un programma di installazione ottengono invece gli aggiornamenti allo stesso modo, purché il config.json installato porti un configUrl.

13.1.14.6.4. Hosting su GitHub#

GitHub è un host conveniente e l’IDE recupera da esso nello stesso modo in cui recupera le proprie risorse. Ci sono due pezzi da collocare: il manifesto e gli archivi.

Mantieni config.json in un repository e fornisci agli utenti il ​​suo URL raw: l’indirizzo a cui viene servito direttamente il file, non la pagina GitHub che lo visualizza. Il pulsante Raw sul file lo mostra; ha la forma

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

L’URL non elaborato è ciò che un utente incolla in Installa da URL e ciò che inserisci nel file manifest configUrl in modo che l’IDE lo recuperi nuovamente per verificare la presenza di aggiornamenti. Puntandolo su un ramo (main) significa che spingendo un nuovo commit si pubblica la modifica; puntandolo su un tag, invece, gli utenti vengono bloccati su una versione fissa.

Ospita gli archivi .zip come release assets invece di impegnarli: le versioni sono create per download binari, quindi un bundle firmware multi-megabyte appartiene a lì, non nella cronologia del repository. Allega ciascun archivio a una versione GitHub e utilizza il relativo URL di download, che ha il formato

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

nei campi url del manifest, ciascuno con il sha256 dell’archivio. Spedire un aggiornamento è quindi: allegare i nuovi archivi a una versione, modificare config.json per puntarli, eseguire il bumping delle versioni ed eseguire il commit. L’IDE rileva la modifica al successivo avvio (il file raw viene servito tramite una cache che si aggiorna entro pochi minuti dal push).