13.1.14. מאגרים של צד שלישי

ה-IDE שולח את הלוחות, הקושחה, הדוגמאות, המודלים של לימוד מכונה ותאבי עורך משל OpenMV, אבל הוא יכול לטעון את אותם סוגי תוכן גם מחברות אחרות - לוח ששותף בנה, הקושחה שפועלת עליו, דוגמאות ודגמים מכוונים עבורו, והשלמת קוד עבור ממשקי ה-API שהקושחה מוסיפה. אלה מגיעים בתור third-party repositories: תיקיות של תוכן שה-IDE מתמזג עם תוכן שלו ומתעדכן.

לדף הזה יש שני קהלים. רובו מיועד לאדם שמתקין ומנהל מאגר שמישהו אחר פורסם. החלק האחרון, authoring a repository, מיועד לספק הבניין אחד.

13.1.14.1. דף מאגרי צד שלישי

הכל מנוהל מתוך עריכה ← העדפות ← OpenMV ← מאגרי צד שלישי. הטבלה מפרטת כל מאגר מותקן, ולכל אחד מהם, שם התצוגה שלו, המזהה הקצר שלו, בין אם הוא Built-in או User, הגרסה המותקנת של כל סוג של תוכן שהוא מספק - קושחה, דוגמאות, דגמים, קטעים - וכתובת ה-URL ממנה היא מתעדכנת.

Built-in פירושו שהמאגר הושם בספרייה של היישום עצמו על ידי מתקין שהספק שלח, האופן שבו חבילת מנהל התקן מוסיפה קבצים לתוכנית. User אומר שהתקנת אותו בעצמך מכתובת אתר. ההבדל המעשי היחיד הוא שאתה לא יכול להסיר מאגר מובנה מה-IDE – הוא מוסר על ידי הסרת ההתקנה של כל מה ששם אותו שם – אז כפתור ההסר מושבת עבורו.

13.1.14.2. התקנת מאגר

Install from URL מבקש את הכתובת של config.json של מאגר – קובץ המניפסט הקטן שהספק מפרסם – ומתקין את כל מה שהוא מצביע אליו. הדבק את כתובת האתר שהספק נתן לך; ה-IDE מוריד את המניפסט, מביא את הקושחה, הדוגמאות, הדגמים ותאבים שהוא מפרט, ומאמת כל הורדה. התקנה, הסרה ועדכון של מאגר נכנסים כולם לתוקף לאחר הפעלה מחדש, כך שה-IDE מציע להפעיל מחדש עם סיום ההתקנה.

ספק יכול גם להפיץ מאגר בתור מתקין שמפיל אותו ישירות לספריית האפליקציות, ובמקרה זה הוא פשוט קיים כשורה Built-in בפעם הראשונה שאתה פותח את הדף - אין מה להתקין.

13.1.14.3. שמירה על מאגרים מעודכנים

מאגר הנושא כתובת URL לעדכון נבדק בכל פעם שה-IDE מופעל. כאשר תוכן חדש יותר זמין, ה-IDE אומר לך מה - מפרט כל מאגר והגרסאות המעורבות - ומציע להתקין אותו, הכל בהנחיה אחת. Check for Updates מפעיל את אותה בדיקה לפי דרישה.

13.1.14.4. עדיפות ועקיפות

מאגרים הם רשימה מסודרת, העדיפות הגבוהה ביותר בחלק העליון, ו-Move Up and Move Down סדר מחדש את זה שנבחר. הסדר חשוב רק כאשר שני מקורות מספקים את הדבר same: לוח עם אותו מזהה USB, או דוגמה, דגם או בדל עם אותו שם. כשזה קורה הכניסה הגבוהה יותר מנצחת, וכל מאגר מנצח את התוכן המובנה של OpenMV. זה בכוונה – זה האופן שבו ספק מספק קושחה משלו ללוח שחולק מזהה USB של לוח OpenMV, מחליף את קושחת המניות שה-IDE היה מציע לו אחרת, או מחליף דוגמה של מניות באחד שנכתב עבור החומרה שלו.

מכיוון שעקיפה משנה בשקט את מה ששם מוכר עושה, הדף אף פעם לא מסתיר אותו. חלונית האזהרות לעקוף מפרטת כל עקיפה בתוקף - הלוח של המאגר, הדוגמה, הדגם או הסטאב מחליף איזה - ואותה רשימה מופיעה פעם אחת כהודעה בפעם הראשונה שבה רואים מאגר. אם לוח, דוגמה או דגם אינם מתנהגים כפי שמתאר התיעוד של OpenMV, פאנל זה הוא המקום הראשון לחפש בו.

13.1.14.5. מה שמאגר מספק

ארבעת סוגי התוכן מופיעים כל אחד במקומם הרגיל ב-IDE, כך שלאחר התקנת מאגר אין שום דבר חדש ללמוד:

• Boards and firmware. לוח של מאגר מתנהג בדיוק כמו לוח OpenMV – הוא מזוהה בחיבור, הסוג שלו מופיע בשורת המצב ועדכוני הקושחה שלו דרך ה-IDE, כולל הנתיב Install the Latest Development Release. ראה עדכוני קושחה ושחזור.

• Examples. דוגמאות של מאגר מופיעות בקובץ → דוגמאות, מוזגות לתוך עץ הקטגוריות: דוגמה בקטגוריה שהספק שמה זהה לקטגוריית OpenMV יושבת לצד אלו של OpenMV, וקטגוריה חדשה הופכת לתפריט משנה משלה. הם מסוננים אל הלוחות שהם תומכים בהם כמו כל דוגמה. ראה סקריפטים, דוגמאות, ותיקיית המסמכים.

• Models. מודלים של מאגר מופיעים ב-Model Zoo, מוזגים בעץ הדפדפן באותו אופן, עם התיאורים של הספק עצמו.

• Stubs. מאגר יכול לשלוח .pyi קבצי stub כך שה-editor מציע השלמה, חתימות ותיעוד עבור הפונקציות שהקושחה שלו מוסיפה - אותה השלמה שאתה מקבל עבור המודולים של OpenMV, עבור API מותאם אישית של ספק.

13.1.14.6. עריכת מאגר

מאגר הוא תיקיה על שם הספק, המכילה מניפסט config.json ותיקיית משנה לכל סוג של תוכן שהוא מספק:

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

שם התיקיה הוא מזהה המאגר: אותיות קטנות, ספרות, - ו_, המתחיל באות. כל תיקיית חלקים היא אופציונלית; לשלוח רק מה שיש לך. ליד כל תיקיית חלק יש קובץ <part>.version המכיל מחרוזת גרסה אחת (1.2.0) שבה משתמש ה-IDE כדי להחליט מתי עדכון חדש יותר.

13.1.14.6.1. המניפסט

config.json נותן שם למאגר, ולכל חלק מצביע על ארכיון הניתן להורדה:

{
  "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 חייב להתאים לשם התיקיה. configUrl היא הכתובת שבה מתארח אותו קובץ; ה-IDE מביא אותו מחדש כדי לחפש עדכונים, אז השמיט אותו רק עבור מאגר שלעולם לא יתעדכן. לכל חלק יש ערוץ release, ולקושחה עשויה להיות ערוץ development המשמש את התקן את מהדורת הפיתוח האחרונה. ערכי שחרור version מושווים כמספרים, כך שערך גבוה יותר מוצע כעדכון; גרסאות פיתוח מושוות רק לצורך שינוי. ה-sha256 הוא אופציונלי אך מאומת כאשר הוא קיים.

כל url מצביע על .zip (zip בלבד). ארכיון מחזיק בדיוק one top-level folder, וה-IDE מתקין את contents של התיקיה הזו כחלק - אז ארכיון הקושחה ארוז כך:

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

ופורק את התיקיה firmware/ שהוצגה קודם לכן. הארכיונים של הדוגמאות, הדגמים וארכיוני התליונים ארוזים באותו אופן – תיקיית עטיפה אחת שמכילה את מה שישב בתוך examples/, models/ או stubs/. מתעלם מהשם של תיקיית העטיפה; מה שחשוב זה שיש בדיוק אחד. צירוף הקבצים בשורש הארכיון ללא תיקיית עטיפה, או עטיפה ביותר מתיקיה אחת, לא יותקן. הדרך הפשוטה ביותר לעשות את זה נכון היא לדחוס את התיקיה עצמה – בחר acme-firmware ודחוס אותה, במקום לבחור את התוכן שלה.

13.1.14.6.2. לוחות, דוגמאות, דגמים ושבבים

firmware/settings.json משתמש באותו פורמט תיאור לוח כמו הקושחה שה-IDE שולח; הוסף ערך boards לכל אחד מהלוחות שלך. כמה כללים ספציפיים ללוחות של צד שלישי: boardFirmwareFolder חייב להיות ייחודי (הוא עדיין לא בשימוש על ידי OpenMV או ספק אחר, מכיוון שהוא נותן שם לתיקייה שהקבצים הבינאריים שלך חיים בה), כל לוח חייב לשאת firmware_version משלו (זה מה שמניע את בקשת העדכון בחיבור), ולוח עשוי להגדיר את boardFirmwareFolderAlias ללוח ה-Open של הלוח שלה ב-MV. דוגמאות ודגמים – פתח המילוט ללוח התואם קושחה ל-OpenMV. צפוי שימוש חוזר במזהי אתחול OpenMV (הם נושאים את מנהלי ההתקן החתומים של Windows); מזהה אפליקציה שמתנגש עם לוח מובנה עוקף את הלוח הזה, מה שלוח האזהרות לעקוף מדווח.

דוגמאות נכנסות לתיקיות קטגוריות ממוספרות כמו של OpenMV (01-Getting-Started); קטגוריה שאתה שם זהה לקטגוריה של OpenMV משתלבת בה, ושם חדש הופך לקטע תפריט משלה. דגם הוא תיקייה שמכילה את .tflite ו-.txt תואם של תוויות כיתה, מקובצות תחת תיקייה ש-index.html שלה (ותמונה אופציונלית) היא התיאור המוצג לצדה בגן החיות של הדגם. examples/index.csv ו-models/index.csv הם אותם קבצי לוח וחיישנים שהדוגמאות והדגמים של OpenMV משתמשים בהם, מותאמים לנתיבי הדוגמה והמודל שלך, ומחליטים איזה מכם מציג עבור איזה לוח. קבצים הם קבצי .pyi רגילים; ה-IDE מוסר את התיקייה שלו לשרת השפה כך שהם יפתרו לצד של OpenMV, ובדל על שם מודול קיים (csi.pyi) עוקף את השלמת המודול הזה.

13.1.14.6.3. פרסום ועדכון

כדי לפרסם, ארח את ה-config.json ואת הארכיונים שהוא מפנה בכתובות URL יציבות ותן למשתמשים את כתובת ה-config.json להתקנה. כל מקום שמגיש קבצים רגילים דרך HTTPS עובד - שרת אינטרנט, חנות אובייקטים או מארח קוד. כדי לשלוח עדכון, העלה ארכיונים חדשים, דחף את ערכי version המושפעים ב-config.json המתארח, ובפעם הבאה שה-IDE של כל משתמש יושק, הוא מציע את העדכון. משתמשים שהתקינו את המאגר דרך מתקין במקום זאת מקבלים עדכונים באותו אופן, כל עוד ה-config.json המותקן נושא configUrl.

13.1.14.6.4. אירוח ב-GitHub

GitHub הוא מארח נוח, וה-IDE שואב ממנו באותו אופן שבו הוא שואב את המשאבים שלו. יש להציב שני חלקים: המניפסט והארכיון.

שמור את ה-config.json במאגר ותן למשתמשים את כתובת ה-raw שלו – הכתובת שבה הקובץ מוגש ישירות, לא לדף GitHub שמציג אותו. הלחצן Raw בקובץ מציג זאת; יש לו את הצורה

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

כתובת ה-URL הגולמית הזו היא מה שמשתמש מדביק ב- Install from URL, ומה שאתה מכניס למניפסט configUrl של המניפסט עצמו, כך שה-IDE אחזר אותו כדי לבדוק אם יש עדכונים. הצבעה על סניף (main) פירושה דחיפה של התחייבות חדשה מפרסמת את השינוי; הפנייתו לתג מצמידה את המשתמשים לגרסה קבועה במקום זאת.

ארח את הארכיונים של .zip כ-release assets במקום לבצע אותם - מהדורות בנויות להורדות בינאריות, כך שצרור קושחה מרובת מגה-בייט שייך לשם, לא בהיסטוריה של המאגר. צרף כל ארכיון לגרסת GitHub והשתמש ב-URL ההורדה שלו, עם הטופס

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

בשדות url של המניפסט, כל אחד עם sha256 של הארכיון. משלוח עדכון הוא לאחר מכן: צרף את הארכיונים החדשים לגרסה, ערוך את config.json כדי להצביע עליהם ולחבוט בגרסאות, והתחייב. ה-IDE קולט את השינוי בהשקה הבאה שלו (הקובץ הגולמי מוגש דרך מטמון שמתרענן תוך דקות ספורות מהדחיפה).