ROMFS:n käyttö

Yleiskatsaus

ROMFS (Read-Only Memory Filesystem) on kevyt, vain luku -tiedostojärjestelmä, joka on suunniteltu MicroPython-laitteille. Se on optimoitu mikrokontrollereille ja sulautetuille järjestelmille, joissa koodi ja data on tallennettava flash-muistiin ja käytettävä tehokkaasti ilman, että niitä kopioidaan RAM-muistiin.

ROMFS:n keskeiset hyödyt ovat:

• Kopiointivapaat tuonnit: ROMFS:ään tallennetut .mpy-tavukooditiedostot voidaan suorittaa suoraan flash-muistista (muistikartoitettuna) sen sijaan, että ne kopioitaisiin ensin RAM-muistiin. Tämä muistuttaa sitä, miten jäädytetyt moduulit toimivat, mutta ei vaadi koko laiteohjelmiston uudelleenflashausta.

• Pieni RAM-kuormitus: ROMFS:stä ladatuissa .mpy-tiedostoissa olevat vakio-oliot (merkkijonot, tavut jne.) viitataan suoraan flash-muistista, eikä niitä monisteta RAM-muistiin.

• Joustava käyttöönotto: ROMFS-vedos voidaan rakentaa isäntä-PC:llä ja ottaa käyttöön laitteella mpremoten avulla ilman laiteohjelmiston uudelleenrakentamista.

• Vakiomuotoinen tiedostojärjestelmärajapinta: ROMFS liitetään VFS:ään ja sitä käytetään tavallisilla Python-tiedosto-operaatioilla (open, os.listdir, import jne.).

ROMFS täydentää sekä luku-kirjoitus-FAT/LittleFS-tiedostojärjestelmiä (jotka sijaitsevat muissa flash-osioissa) että jäädytettyjä moduuleja (jotka käännetään itse laiteohjelmistoon).

Korttituki

ROMFS on käytössä OpenMV-laiteohjelmistossa jokaisella kameralla, jonka flash-asettelussa on varattu ROMFS-osio. Näillä korteilla ROMFS-osio tunnistetaan automaattisesti käynnistyksen yhteydessä ja liitetään polkuun /rom; sekä /rom että /rom/lib lisätään polkuun sys.path, jotta niihin tallennetut moduulit voidaan tuoda suoraan.

Kortti	ROMFS-tuki
OpenMV Cam N6	Kyllä
OpenMV AE3	Kyllä
OpenMV Cam RT1062	Kyllä
OpenMV Cam Pure Thermal	Kyllä
OpenMV Cam M4 / M7 / H7 / H7 Plus	Kyllä
Arduino Giga	Kyllä
Arduino Portenta H7	Kyllä
Arduino Nicla Vision	Kyllä
Arduino Nano 33 BLE Sense	Ei (ei ROMFS-osiota)
Arduino Nano RP2040 Connect	Ei (ei ROMFS-osiota)

Katso romfs saadaksesi OpenMV-kohtaisen aputyökalun, joka tutkii polkuun /rom liitettyä ROMFS:ää.

Työnkulku

Tyypillinen ROMFS:n käytön työnkulku on:

1. Luo PC:llesi hakemisto, jossa on käyttöönotettavat Python-tiedostot (tai .mpy-tiedostot).

2. Käytä komentoa mpremote romfs deploy <directory> rakentaaksesi ja ottaaksesi käyttöön ROMFS-vedoksen laitteella.

3. ROMFS liitetään polkuun /rom seuraavalla käynnistyskerralla (tai se voidaan liittää välittömästi, jos laite käynnistetään uudelleen).

4. Laitteella oleva Python-koodi voi tämän jälkeen tuoda (import) moduuleja ROMFS:stä aivan kuten mistä tahansa muusta tiedostojärjestelmästä.

Esimerkiksi:

# On the host PC, with a directory "myapp/" containing app.py:
$ mpremote romfs deploy myapp/

Pehmeän uudelleenkäynnistyksen jälkeen laitteella on tuontia varten käytettävissä /rom/app.py (tai /rom/app.mpy, jos mpy_cross on asennettu).

Katso alla oleva osio mpremote romfs -alikomennot saadaksesi täydet tiedot mpremote-alikomennoista.

Python-rajapinta

ROMFS:n Python-rajapinta tarjotaan vfs-moduulin kautta.

class vfs.VfsRom(buffer)

Luo ROMFS-tiedostojärjestelmäolio kohteesta buffer, jonka on oltava puskuriprotokollaa tukeva olio (esim. bytes-, bytearray- tai memoryview-olio), joka sisältää kelvollisen ROMFS-vedoksen.

Konstruktori varmistaa, että buffer alkaa ROMFS:n maagisilla tavuilla (b"\xd2\xcd\x31"). Jos puskuri on liian pieni tai ei ole kelvollinen ROMFS, nostetaan OSError(ENODEV).

Tällä konstruktorilla luodut oliot voidaan liittää käyttäen vfs.mount().

Esimerkki:

import vfs

# Load a ROMFS image from flash into a memoryview.
dev = vfs.rom_ioctl(2, 0)   # get partition 0 as a memoryview
fs = vfs.VfsRom(dev)
vfs.mount(fs, '/rom')

Tai, liittääksesi tiedostoon tallennetun ROMFS-vedoksen:

import vfs

with open('/flash/app.romfs', 'rb') as f:
    romfs_data = f.read()
fs = vfs.VfsRom(romfs_data)
vfs.mount(fs, '/rom2')

Seuraavat metodit ovat käytettävissä VfsRom-oliolla:

VfsRom.open(path, mode)

Avaa tiedosto ROMFS:stä. Vain lukutilat ('', 'r', 'rt', 'rb') ovat tuettuja. Tiedoston avaaminen kirjoitusta varten nostaa OSError(EROFS).

Palautettu tiedosto-olio tukee metodeja read(), seek(), tell() ja close(). Lukutilassa avattujen binääritiedostojen palautettu olio tukee myös puskuriprotokollaa, joten tiedoston datasta voidaan saada memoryview, joka viittaa suoraan ROMFS-muistiin (kopiointivapaa).

VfsRom.ilistdir(path)

Palauta iteraattori hakemiston path merkintöjen yli. Jokainen merkintä on monikko (name, type, inode, size), jossa type on 0x8000 tiedostolle tai 0x4000 hakemistolle.

VfsRom.stat(path)

Palauta os.stat-tyylinen 10-monikko polulle path. Nostaa OSError(ENOENT), jos polkua ei ole olemassa.

VfsRom.statvfs(path)

Palauta tiedostojärjestelmän tilastot. Lohkokoko raportoidaan arvona 1 ja lohkojen määrä edustaa ROMFS-vedoksen kokonaiskokoa tavuina. Vapaita lohkoja ja vapaita tiedostoja on aina 0 (vain luku -tiedostojärjestelmä).

VfsRom.chdir(path)

Vaihda hakemistoa ROMFS:n sisällä. Vain juuri ('/') on tuettu; mihin tahansa alihakemistoon vaihtaminen nostaa OSError(EOPNOTSUPP).

VfsRom.getcwd()

Palauta nykyinen työhakemisto ROMFS:n sisällä. Palauttaa aina '/'.

vfs.rom_ioctl(op, ...)

Matalan tason rajapinta laitteen vain luku -muistiosioiden (ROM) käyttämiseen.

Tuetut operaatiot ovat:

• vfs.rom_ioctl(1) – Palauta käytettävissä olevien ROM-osioiden määrä.

• vfs.rom_ioctl(2, id) – Palauta indeksiä id vastaava ROM-osio memoryview-oliona. Muistia voidaan lukea, mutta ei kirjoittaa suoraan.

• vfs.rom_ioctl(3, id, length) – Valmistele ROM-osio kirjoitusta varten. Tyhjentää indeksiä id vastaavan osion ensimmäiset length tavua. Palauttaa pienimmän kirjoituskoon tavuina (myöhempien kirjoitusten vaatima kohdistus).

• vfs.rom_ioctl(4, id, offset, buf) – Kirjoita buf (bytes-tyyppinen olio) indeksiä id vastaavaan ROM-osioon tavusijainnissa offset.

• vfs.rom_ioctl(5, id) – Saata loppuun kirjoitussekvenssi osioon id (suorittaa kaikki kirjoituksen jälkeen tarvittavat viimeistelyt, kuten välimuistin tyhjennyksen).

mpremote käyttää näitä operaatioita sisäisesti ROMFS-vedosten käyttöönotossa. Useimpien käyttäjien ei tarvitse kutsua vfs.rom_ioctl() suoraan.

Esimerkki (käytettävissä olevien osioiden kysely):

import vfs

n = vfs.rom_ioctl(1)
print("Number of ROM partitions:", n)
for i in range(n):
    dev = vfs.rom_ioctl(2, i)
    print(f"  Partition {i}: {len(dev)} bytes")

Automaattinen liittäminen käynnistyksen yhteydessä

Kun ROMFS-tuki on käytössä laiteohjelmistossa, MicroPython yrittää automaattisesti liittää ensimmäisen ROM-osion polkuun /rom alustuksen aikana. Jos osio sisältää kelvollisen ROMFS-vedoksen, se liitetään ja sekä /rom että /rom/lib lisätään automaattisesti polkuun sys.path.

Tämä tarkoittaa, että ROMFS-vedoksen käyttöönoton jälkeen mpremote-työkalulla pehmeä uudelleenkäynnistys riittää tekemään uudet moduulit tuotaviksi.

Jos osiosta ei löydy kelvollista ROMFS-vedosta (esim. juuri ohjelmoidulla kortilla), liittäminen ohitetaan hiljaisesti.

ROMFS:n hallinta mpremoten avulla

mpremote -työkalu tarjoaa kolme alikomentoa ROMFS-vedosten hallintaan kytketyllä laitteella.

romfs query

$ mpremote romfs query

Listaa kaikki laitteen käytettävissä olevat ROMFS-osiot ja niiden koot. Näyttää myös kunkin osion ensimmäiset 12 tavua heksamuodossa ja raportoi, onko kelvollinen ROMFS-vedos olemassa.

Esimerkkituloste:

ROMFS0 partition has size 131072 bytes (32 blocks of 4096 bytes each)
  Raw contents: d2:cd:31:XX:XX:XX:XX:XX:XX:XX:XX:XX ...
  ROMFS image size: 1234

romfs build

$ mpremote romfs [-o <output>] build <source>

Rakenna ROMFS-vedos isäntä-PC:n hakemistosta source. Vedos kirjoitetaan kohteeseen output (oletus: <source>.romfs).

Valinnat:

• -o <output>, --output <output>: Määritä tulostetiedoston polku.

• -m, --mpy (oletus): Käännä .py-tiedostot automaattisesti .mpy-muotoon käyttäen mpy_cross -työkalua ennen niiden lisäämistä vedokseen. Vaatii mpy_cross-Python-paketin (pip install mpy_cross).

• --no-mpy: Poista .py-tiedostojen automaattinen kääntäminen käytöstä.

Esimerkki:

$ mpremote romfs build myapp/
Building romfs filesystem, source directory: myapp/
/
|-- main.py -> .mpy
\-- lib/
    \-- helper.py -> .mpy
Writing 2048 bytes to output file myapp.romfs

romfs deploy

$ mpremote romfs [-p <partition>] deploy <source>

Ota ROMFS-vedos käyttöön laitteella. source voi olla joko:

• Isännän hakemisto: ROMFS-vedos rakennetaan muistissa ja otetaan käyttöön suoraan.

• .romfs- tai .img-tiedosto: vedos luetaan levyltä ja otetaan käyttöön.

Valinnat:

• -p <partition>, --partition <partition>: Määritä kohdeosion indeksi (oletus: 0).

• -m, --mpy (oletus): Käännä .py muotoon .mpy, kun source on hakemisto.

• --no-mpy: Poista .py-tiedostojen automaattinen kääntäminen käytöstä.

Käyttöönoton jälkeen laite on käynnistettävä pehmeästi uudelleen, jotta uusi ROMFS liitetään polkuun /rom.

Esimerkki:

$ mpremote romfs deploy myapp/
Building romfs filesystem, source directory: myapp/
/
|-- main.py -> .mpy
\-- lib/
    \-- helper.py -> .mpy
Image size is 2048 bytes
ROMFS0 partition has size 131072 bytes (32 blocks of 4096 bytes each)
Preparing ROMFS0 partition for writing
Deploying ROMFS to ROMFS0 partition
ROMFS image deployed

$ mpremote soft-reset

Esimerkit

Yksinkertaisen sovelluksen käyttöönotto

Oletetaan, että sinulla on projektihakemisto myapp/, jolla on seuraava rakenne:

myapp/
    main.py
    utils.py
    lib/
        helper.py

Sen käyttöönotto laitteen ROMFS:ään:

$ mpremote romfs deploy myapp/

Pehmeän uudelleenkäynnistyksen jälkeen moduulit ovat tuotavissa ROMFS:stä:

import main
import utils
from lib import helper

ROMFS:n sisällön listaaminen Pythonista

Liittämisen jälkeen ROMFS:n sisältöä voidaan tutkia kuten mitä tahansa muuta tiedostojärjestelmää:

import os

for entry in os.ilistdir('/rom'):
    print(entry)

# Or simply:
print(os.listdir('/rom'))

OpenMV sisältää myös pienen romfs-aputyökalun, joka tulostaa muotoillun listauksen, johon sisältyy kunkin tiedoston muistikartoitettu osoite ja kohdistus:

from omv import romfs
romfs.ls_romfs()

ROMFS:n upottaminen ROMFS:ään

Ulomman ROMFS:n sisään tiedostoksi tallennettu ROMFS-vedos voidaan liittää sisäkkäisenä tiedostojärjestelmänä. Jos esimerkiksi /rom/inner.romfs on olemassa. Koska /rom on ROMFS, siitä avatut tiedosto-oliot tukevat puskuriprotokollaa, joten kopiointivapaa memoryview voidaan saada suoraan:

import vfs

with open('/rom/inner.romfs', 'rb') as f:
    inner = vfs.VfsRom(memoryview(f))
vfs.mount(inner, '/inner')

print(os.listdir('/inner'))

ROMFS-vedoksen muoto

ROMFS-vedoksen muoto on kompakti binäärimuoto, joka on suunniteltu muistikartoitettuun käyttöön mikrokontrollereissa. Lyhyt yleiskatsaus:

• Vedos alkaa maagisilla tavuilla 0xd2 0xcd 0x31 (koodattuna muotoon "RM1", jossa kahden ensimmäisen tavun ylimmät bitit on asetettu).

• Loput vedoksesta koostuvat tietueista, joista jokaisella on tyyppitunniste (varuint), pituus (varuint) ja hyötykuorma.

• Tietuetyyppejä ovat: täyte, sanatarkka data, epäsuora dataosoitin, hakemisto, tiedosto.

• Hakemisto- ja tiedostonimet tallennetaan pituusetuliitteisinä tavujonoina.

• Tiedoston data voidaan tallentaa sanatarkasti (sisäkkäin) tai epäsuoran osoittimen kautta muualle vedoksessa, mikä mahdollistaa kohdistuksen muistikartoitettua käyttöä varten.

• Tuntemattomat tietuetyypit ohitetaan hiljaisesti, mikä tarjoaa eteenpäin yhteensopivuuden.

Tämä muoto on määritelty MicroPython-lähdekoodin tiedostossa extmod/vfs_rom.c. mpremote-työkalun vedosten rakentamiseen käyttämä Python-toteutus on tiedostossa tools/mpremote/mpremote/romfs.py.

Katso myös

Tiedostojärjestelmien käyttö – Yleiskatsaus MicroPython VFS:ään ja käytettävissä oleviin tiedostojärjestelmätyyppeihin.

MicroPython-manifestitiedostot – Kuinka jäädyttää Python-moduulit laiteohjelmistoon.

MicroPython .mpy -tiedostot – MicroPython .mpy -binääritiedostomuoto.

MicroPythonin etäohjaus: mpremote – Täydellinen mpremote-komentoreferenssi.

romfs – OpenMV-aputyökalu polkuun /rom liitetyn tiedostojärjestelmän tarkasteluun.