ניהול חבילות

התקנת חבילות באמצעות mip

לוחות בעלי יכולת רשת כוללים את המודול mip, שיכול להתקין חבילות מ-micropython-lib ומאתרי צד שלישי (כולל GitHub, GitLab).

mip (”mip installs packages“) דומה במושג לכלי pip של Python, אולם הוא אינו משתמש באינדקס PyPI, אלא משתמש ב-micropython-lib כאינדקס שלו כברירת מחדל. mip יביא אוטומטית .mpy file מהודר בעת הורדה מ-micropython-lib.

הדרך הנפוצה ביותר להשתמש ב-mip היא מה-REPL:

>>> import mip
>>> mip.install("pkgname")  # Installs the latest version of "pkgname" (and dependencies)
>>> mip.install("pkgname", version="x.y")  # Installs version x.y of "pkgname"
>>> mip.install("pkgname", mpy=False)  # Installs the source version (i.e. .py rather than .mpy files)

mip יאתר מיקום מתאים במערכת הקבצים על ידי סריקת sys.path אחר הערך הראשון המסתיים ב-/lib. ניתן לעקוף את היעד באמצעות target, אך שימו לב שנתיב זה חייב להיות ב-sys.path כדי שניתן יהיה לאחר מכן לייבא אותו:

>>> mip.install("pkgname", target="third-party")
>>> sys.path.append("third-party")

בנוסף להורדת חבילות מאינדקס micropython-lib, mip יכול גם להתקין ספריות צד שלישי. הדרך הפשוטה ביותר היא להוריד קובץ ישירות:

>>> mip.install("http://example.com/x/y/foo.py")
>>> mip.install("http://example.com/x/y/foo.mpy")

בעת התקנת קובץ ישירות, הארגומנט target עדיין נתמך לקביעת נתיב היעד, אך mpy ו-version מתעלמים מהם.

ה-URL יכול גם להתחיל ב-github: או ב-gitlab: כדרך פשוטה להצביע על תוכן המתארח ב-GitHub או ב-GitLab:

>>> mip.install("github:org/repo/path/foo.py")  # Uses default branch
>>> mip.install("github:org/repo/path/foo.py", version="branch-or-tag")  # Optionally specify the branch or tag
>>> mip.install("gitlab:org/repo/path/foo.py")  # Uses default branch
>>> mip.install("gitlab:org/repo/path/foo.py", version="branch-or-tag")  # Optionally specify the branch or tag

חבילות מתוחכמות יותר (כלומר עם יותר מקובץ אחד, או עם תלויות) ניתן להוריד על ידי ציון הנתיב ל-package.json שלהן:

>>> mip.install("http://example.com/x/package.json")
>>> mip.install("github:org/user/path/package.json")
>>> mip.install("gitlab:org/user/path/package.json")

אם לא צוין קובץ json, אזי ”package.json“ מתווסף באופן משתמע:

>>> mip.install("http://example.com/x/")
>>> mip.install("github:org/repo")  # Uses default branch of that repo
>>> mip.install("github:org/repo", version="branch-or-tag")
>>> mip.install("gitlab:org/repo")  # Uses default branch of that repo
>>> mip.install("gitlab:org/repo", version="branch-or-tag")

שימוש ב-mip ב-port של Unix

ב-port של Unix, ניתן להשתמש ב-mip ב-REPL כמתואר לעיל, וגם באמצעות -m

$ ./micropython -m mip install pkgname-or-url
$ ./micropython -m mip install pkgname-or-url@version

ניתן לקבוע את הארגומנטים --target path, --no-mpy ו---index

$ ./micropython -m mip install --target third-party pkgname
$ ./micropython -m mip install --no-mpy pkgname
$ ./micropython -m mip install --index https://host/pi pkgname

התקנת חבילות באמצעות mpremote

הכלי mpremote כולל גם את אותה פונקציונליות כמו mip וניתן להשתמש בו ממחשב מארח להתקנת חבילות בהתקן המחובר באופן מקומי (למשל באמצעות USB או UART):

$ mpremote mip install pkgname
$ mpremote mip install [email protected]
$ mpremote mip install http://example.com/x/y/foo.py
$ mpremote mip install github:org/repo
$ mpremote mip install github:org/repo@branch-or-tag
$ mpremote mip install gitlab:org/repo
$ mpremote mip install gitlab:org/repo@branch-or-tag

ניתן לקבוע את הארגומנטים --target=path, --no-mpy ו---index

$ mpremote mip install --target=/flash/third-party pkgname
$ mpremote mip install --no-mpy pkgname
$ mpremote mip install --index https://host/pi pkgname

mpremote יכול גם להתקין חבילות מקבצים המאוחסנים במערכת הקבצים המקומית של המארח:

$ mpremote mip install path/to/pkg.py
$ mpremote mip install path/to/app/package.json
$ mpremote mip install \\path\\to\\pkg.py

זה שימושי במיוחד לבדיקת חבילות במהלך הפיתוח ולהתקנת חבילות משכפולים מקומיים של מאגרי GitHub. שימו לב שכתובות URL בקובצי package.json חייבות להשתמש בקווים נטויים קדמיים (”/“) כמפרידי ספריות, אפילו ב-Windows, כך שהן יהיו תואמות להתקנה מהאינטרנט.

התקנת חבילות באופן ידני

ניתן להתקין חבילות (בצורת .py או .mpy) גם על ידי העתקה ידנית של הקבצים אל ההתקן. בהתאם ללוח, זה עשוי להיות באמצעות USB Mass Storage, הכלי mpremote (למשל mpremote fs cp path/to/package.py :package.py), webrepl וכו«.

כתיבה ופרסום של חבילות

פרסום ל-micropython-lib הוא הדרך הקלה ביותר להפוך את החבילה שלכם לנגישה באופן רחב למשתמשי MicroPython, וזמינה אוטומטית באמצעות mip ו-mpremote ומהודרת ל-bytecode. ראו https://github.com/micropython/micropython-lib למידע נוסף.

כדי לכתוב חבילה ”מתארחת עצמאית“ שניתן להוריד באמצעות mip או mpremote, אתם זקוקים לשרת אינטרנט סטטי (או GitHub) שיארח קובץ .py יחיד, או קובץ package.json לצד קובצי ה-.py שלכם.

דוגמה לספריית mlx90640 המתארחת ב-GitHub ניתן להתקין באמצעות:

$ mpremote mip install github:org/micropython-mlx90640

פריסת החבילה ב-GitHub עשויה להיראות כך:

https://github.com/org/micropython-mlx90640/
    package.json
    mlx90640/
        __init__.py
        utils.py

ה-package.json מציין את מיקום הקבצים שיש להתקין ואת התלויות האחרות:

{
  "urls": [
    ["mlx90640/__init__.py", "mlx90640/__init__.py"],
    ["mlx90640/utils.py", "mlx90640/utils.py"]
  ],
  "deps": [
    ["collections-defaultdict", "latest"],
    ["os-path", "latest"],
    ["github:org/micropython-additions", "main"],
    ["gitlab:org/micropython-otheradditions", "main"]
  ],
  "version": "0.2"
}

רשימת ה-urls מציינת את הקבצים שיש להתקין בהתאם ל:

"urls": [
    [destination_path, source_url]
    ...

כאשר destination_path הוא המיקום והשם של הקובץ שיש להתקין בהתקן ו-source_url הוא ה-URL של הקובץ שיש להתקין. כתובת ה-URL של המקור תצוין בדרך כלל ביחס לספרייה המכילה את קובץ ה-package.json, אך יכולה להיות גם URL מוחלט, למשל:

["mlx90640/utils.py", "github:org/micropython-mlx90640/mlx90640/utils.py"]

החבילה תלויה ב-collections-defaultdict וב-os-path אשר יותקנו אוטומטית מ-micropython-lib. התלות השלישית מתקינה את התוכן כפי שמוגדר על ידי קובץ ה-package.json של ענף ה-main של מאגר ה-GitHub org/micropython-additions.

הקפאת חבילות

כאשר מודול או חבילה של Python מיובאים ממערכת הקבצים של ההתקן, הם מהודרים ל-bytecode ב-RAM, מוכנים להרצה על ידי ה-VM. עבור .mpy file, המרה זו כבר בוצעה, אך ה-bytecode עדיין מסתיים ב-RAM.

עבור התקנים בעלי זיכרון נמוך, או עבור יישומים גדולים, יכול להיות יתרון בהרצת ה-bytecode מ-ROM (כלומר זיכרון פלאש (flash)) במקום. ניתן לעשות זאת על ידי ”הקפאת“ ה-bytecode לתוך קושחת MicroPython, אשר לאחר מכן נצרבת להתקן. ביצועי זמן הריצה זהים (אם כי הייבוא מהיר יותר), אך זה יכול לפנות כמויות משמעותיות של RAM לשימוש התוכנית שלכם.

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

ההקפאה מתבצעת על ידי כתיבת קובץ manifest ושימוש בו בבנייה, לעתים קרובות כחלק מהגדרת לוח מותאמת אישית. ראו את המדריך קובצי manifest של MicroPython למידע נוסף.