Bekerja dengan ROMFS

Gambaran Umum

ROMFS (Read-Only Memory Filesystem) adalah sistem berkas ringan dan hanya-baca yang dirancang untuk perangkat MicroPython. Sistem ini dioptimalkan untuk mikrokontroler dan sistem tertanam di mana kode dan data perlu disimpan dalam memori flash dan diakses secara efisien tanpa harus disalin ke RAM.

Manfaat utama ROMFS adalah:

  • Impor zero-copy: File bytecode .mpy yang tersimpan dalam ROMFS dapat dieksekusi langsung dari memori flash (dipetakan ke memori) tanpa harus disalin ke RAM terlebih dahulu. Ini mirip dengan cara kerja modul beku, tetapi tidak memerlukan reflash keseluruhan firmware.

  • Overhead RAM rendah: Objek konstan (string, bytes, dll.) dalam file .mpy yang dimuat dari ROMFS direferensikan langsung dari flash, tidak diduplikasi di RAM.

  • Deployment fleksibel: Citra ROMFS dapat dibangun di PC host dan di-deploy ke perangkat menggunakan mpremote, tanpa perlu membangun ulang firmware.

  • Antarmuka sistem berkas standar: ROMFS dipasang dalam VFS dan diakses melalui operasi file Python biasa (open, os.listdir, import, dll.).

ROMFS melengkapi baik sistem berkas FAT/LittleFS yang dapat ditulis (yang berada di partisi flash lain) maupun modul beku (yang dikompilasi langsung ke dalam firmware).

Dukungan board

ROMFS diaktifkan dalam firmware OpenMV di setiap board kamera yang memiliki partisi ROMFS yang dicadangkan dalam tata letak flashnya. Di board-board ini, partisi ROMFS secara otomatis terdeteksi saat boot dan dipasang di /rom; baik /rom maupun /rom/lib ditambahkan ke sys.path sehingga modul yang tersimpan di sana dapat diimpor secara langsung.

Board

Dukungan ROMFS

OpenMV Cam N6

Ya

OpenMV AE3

Ya

OpenMV Cam RT1062

Ya

OpenMV Cam Pure Thermal

Ya

OpenMV Cam M4 / M7 / H7 / H7 Plus

Ya

Arduino Giga

Ya

Arduino Portenta H7

Ya

Arduino Nicla Vision

Ya

Arduino Nano 33 BLE Sense

Tidak (tidak ada partisi ROMFS)

Arduino Nano RP2040 Connect

Tidak (tidak ada partisi ROMFS)

Lihat romfs untuk helper khusus OpenMV yang memeriksa ROMFS yang terpasang di /rom.

Alur Kerja

Alur kerja umum untuk menggunakan ROMFS adalah:

  1. Buat direktori di PC Anda dengan file Python (atau file .mpy) yang ingin Anda deploy.

  2. Gunakan mpremote romfs deploy <directory> untuk membangun dan men-deploy citra ROMFS ke perangkat.

  3. ROMFS akan dipasang di /rom pada boot berikutnya (atau dapat dipasang segera jika perangkat di-reboot).

  4. Kode Python di perangkat kemudian dapat import modul dari ROMFS sama seperti dari sistem berkas lainnya.

Contoh:

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

Setelah soft-reset, perangkat akan memiliki /rom/app.py (atau /rom/app.mpy jika mpy_cross terpasang) yang tersedia untuk diimpor.

Lihat bagian sub-perintah mpremote romfs di bawah untuk detail lengkap sub-perintah mpremote.

Python API

Python API untuk ROMFS disediakan melalui modul vfs.

class vfs.VfsRom(buffer)

Buat objek sistem berkas ROMFS dari buffer, yang harus berupa objek yang mendukung protokol buffer (misalnya objek bytes, bytearray, atau memoryview) yang berisi citra ROMFS yang valid.

Konstruktor memvalidasi bahwa buffer diawali dengan magic bytes ROMFS (b"\xd2\xcd\x31"). Jika buffer terlalu kecil atau bukan ROMFS yang valid, maka OSError(ENODEV) akan dimunculkan.

Objek yang dibuat oleh konstruktor ini dapat dipasang menggunakan vfs.mount().

Contoh:

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')

Atau, untuk memasang citra ROMFS yang tersimpan dalam file:

import vfs

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

Metode berikut tersedia pada objek VfsRom:

VfsRom.open(path, mode)

Buka file dari ROMFS. Hanya mode baca ('', 'r', 'rt', 'rb') yang didukung. Mencoba membuka file untuk penulisan akan memunculkan OSError(EROFS).

Objek file yang dikembalikan mendukung read(), seek(), tell(), dan close(). Untuk file biner yang dibuka dalam mode baca, objek yang dikembalikan juga mendukung protokol buffer sehingga memoryview dari data file dapat diperoleh, yang merujuk langsung ke memori ROMFS (zero-copy).

VfsRom.ilistdir(path)

Kembalikan iterator atas entri dalam direktori path. Setiap entri adalah tuple (name, type, inode, size) di mana type adalah 0x8000 untuk file atau 0x4000 untuk direktori.

VfsRom.stat(path)

Kembalikan 10-tuple seperti os.stat untuk path. Memunculkan OSError(ENOENT) jika path tidak ada.

VfsRom.statvfs(path)

Kembalikan statistik sistem berkas. Ukuran blok dilaporkan sebagai 1 dan jumlah blok mewakili total ukuran citra ROMFS dalam byte. Blok bebas dan file bebas selalu 0 (sistem berkas hanya-baca).

VfsRom.chdir(path)

Ubah direktori dalam ROMFS. Hanya root ('/') yang didukung; berpindah ke subdirektori mana pun akan memunculkan OSError(EOPNOTSUPP).

VfsRom.getcwd()

Kembalikan direktori kerja saat ini dalam ROMFS. Selalu mengembalikan '/'.

vfs.rom_ioctl(op, ...)

Antarmuka tingkat rendah untuk mengakses partisi memori hanya-baca (ROM) dari perangkat.

Operasi yang didukung adalah:

  • vfs.rom_ioctl(1) -- Kembalikan jumlah partisi ROM yang tersedia.

  • vfs.rom_ioctl(2, id) -- Kembalikan partisi ROM dengan indeks id sebagai objek memoryview. Memori dapat dibaca tetapi tidak dapat ditulis secara langsung.

  • vfs.rom_ioctl(3, id, length) -- Siapkan partisi ROM untuk penulisan. Hapus length byte pertama dari partisi dengan indeks id. Mengembalikan ukuran penulisan minimum dalam byte (penyelarasan yang diperlukan untuk penulisan berikutnya).

  • vfs.rom_ioctl(4, id, offset, buf) -- Tulis buf (objek seperti bytes) ke partisi ROM dengan indeks id pada byte offset.

  • vfs.rom_ioctl(5, id) -- Selesaikan urutan penulisan ke partisi id (melakukan finalisasi yang diperlukan setelah penulisan, seperti pembersihan cache).

Operasi-operasi ini digunakan secara internal oleh mpremote untuk men-deploy citra ROMFS. Sebagian besar pengguna tidak perlu memanggil vfs.rom_ioctl() secara langsung.

Contoh (menanyakan partisi yang tersedia):

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")

Pemasangan otomatis saat boot

Ketika dukungan ROMFS diaktifkan dalam firmware, MicroPython akan secara otomatis mencoba memasang partisi ROM pertama di /rom selama inisialisasi. Jika partisi berisi citra ROMFS yang valid, maka akan dipasang dan baik /rom maupun /rom/lib ditambahkan ke sys.path secara otomatis.

Ini berarti bahwa setelah men-deploy citra ROMFS dengan mpremote, soft-reset sudah cukup untuk membuat modul-modul baru dapat diimpor.

Jika tidak ada citra ROMFS yang valid yang ditemukan dalam partisi (misalnya pada board yang baru saja diprogram), pemasangan akan dilewati secara diam-diam.

Menggunakan mpremote untuk mengelola ROMFS

Alat mpremote menyediakan tiga sub-perintah untuk mengelola citra ROMFS pada perangkat yang terhubung.

romfs query

$ mpremote romfs query

Mencantumkan semua partisi ROMFS yang tersedia di perangkat beserta ukurannya. Juga menampilkan 12 byte pertama dari setiap partisi dalam format hex dan melaporkan apakah citra ROMFS yang valid ada.

Contoh output:

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>

Bangun citra ROMFS dari direktori source di PC host. Citra ditulis ke output (default: <source>.romfs).

Opsi:

  • -o <output>, --output <output>: Tentukan jalur file output.

  • -m, --mpy (default): Secara otomatis kompilasi file .py ke .mpy menggunakan mpy_cross sebelum menambahkannya ke citra. Memerlukan paket Python mpy_cross (pip install mpy_cross).

  • --no-mpy: Nonaktifkan kompilasi otomatis file .py.

Contoh:

$ 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>

Deploy citra ROMFS ke perangkat. source dapat berupa:

  • Direktori di host: citra ROMFS dibangun di memori dan di-deploy secara langsung.

  • File .romfs atau .img: citra dibaca dari disk dan di-deploy.

Opsi:

  • -p <partition>, --partition <partition>: Tentukan indeks partisi target (default: 0).

  • -m, --mpy (default): Kompilasi .py ke .mpy ketika source adalah direktori.

  • --no-mpy: Nonaktifkan kompilasi otomatis file .py.

Setelah deployment, perangkat harus di-soft-reset agar ROMFS baru dipasang di /rom.

Contoh:

$ 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

Contoh

Men-deploy aplikasi sederhana

Misalkan Anda memiliki direktori proyek myapp/ dengan struktur berikut:

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

Untuk men-deploy ke ROMFS perangkat:

$ mpremote romfs deploy myapp/

Setelah soft-reset, modul-modul dapat diimpor dari ROMFS:

import main
import utils
from lib import helper

Mencantumkan isi ROMFS dari Python

Setelah dipasang, isi ROMFS dapat dijelajahi seperti sistem berkas lainnya:

import os

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

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

OpenMV juga menyertakan helper kecil romfs yang mencetak daftar terformat termasuk alamat memori-mapped dan penyelarasan setiap file:

from omv import romfs
romfs.ls_romfs()

Menyarangkan ROMFS di dalam ROMFS

Citra ROMFS yang tersimpan sebagai file dalam ROMFS luar dapat dipasang sebagai sistem berkas bersarang. Misalnya, jika /rom/inner.romfs ada. Karena /rom adalah ROMFS, objek file yang dibuka darinya mendukung protokol buffer, sehingga memoryview zero-copy dapat diperoleh secara langsung:

import vfs

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

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

Format citra ROMFS

Format citra ROMFS adalah format biner kompak yang dirancang untuk akses memori-mapped pada mikrokontroler. Gambaran singkat:

  • Citra dimulai dengan magic bytes 0xd2 0xcd 0x31 (dikodekan sebagai "RM1" dengan bit tinggi dari dua byte pertama diset).

  • Sisa citra terdiri dari rekaman, masing-masing dengan tag tipe (varuint), panjang (varuint), dan payload.

  • Tipe rekaman meliputi: padding, data verbatim, pointer data tidak langsung, direktori, file.

  • Nama direktori dan file disimpan sebagai string byte dengan awalan panjang.

  • Data file dapat disimpan secara verbatim (inline) atau melalui pointer tidak langsung ke tempat lain dalam citra, yang memungkinkan penyelarasan untuk akses memori-mapped.

  • Tipe rekaman yang tidak dikenal dilewati secara diam-diam, memberikan kompatibilitas ke depan.

Format ini didefinisikan dalam extmod/vfs_rom.c di sumber MicroPython. Implementasi Python yang digunakan oleh mpremote untuk membangun citra ada di tools/mpremote/mpremote/romfs.py.

Lihat juga

Bekerja dengan filesystem -- Gambaran umum VFS MicroPython dan tipe sistem berkas yang tersedia.

File manifest MicroPython -- Cara membekukan modul Python ke dalam firmware.

File .mpy MicroPython -- Format file biner .mpy MicroPython.

Kendali jarak jauh MicroPython: mpremote -- Referensi perintah lengkap mpremote.

romfs -- Helper OpenMV untuk memeriksa sistem berkas /rom yang terpasang.