14.3.3. Igiene del filesystem

La memoria flash e SD di una cam in produzione si riempiono di file che nessun operatore andrà a ripulire a mano. Due decisioni riguardanti questa memoria accompagnano il prodotto per tutta la sua vita: quale supporto contiene quale tipo di dati e come sono strutturate le directory affinché le operazioni sui file continuino a funzionare man mano che l’applicazione accumula record.

14.3.3.1. Dove vanno le cose

Il codice e gli asset risiedono nei moduli congelati e nel ROMFS che la build fissa al momento della spedizione. Lo stato dell’applicazione – tutto ciò che l’applicazione scrive a runtime, tutto ciò che cresce, tutto ciò che cambia tra un avvio e l’altro – deve risiedere da qualche altra parte. La cam espone due supporti scrivibili a questo scopo:

  • Flash interna in /flash: un piccolo filesystem scrivibile montato prima che venga eseguito qualsiasi codice applicativo. Il posto giusto per piccoli record di dimensione fissa che sopravvivono ai riavvii: la configurazione che l’applicazione aggiorna a runtime, l’ultima calibrazione nota, un contatore progressivo, un file marcatore di una riga che dice «questa cam è stata provisionata.» Cicli di scrittura limitati – la flash interna moderna tollera da migliaia a decine di migliaia di scritture per settore, non milioni, quindi le scritture devono essere poco frequenti, non per ogni frame.

  • Scheda SD in /sdcard: un filesystem scrivibile più grande montato quando è presente una scheda. Il posto giusto per file voluminosi e di dimensione variabile: acquisizioni di immagini e video, file di log, dati per il fine-tuning del modello, qualsiasi cosa che possa crescere fino a megabyte o gigabyte. Maggiore capacità di scrittura rispetto alla flash interna ma comunque finita; rimovibile, sostituibile, e il supporto che più probabilmente sparisce mentre l’applicazione è nel mezzo di una scrittura.

La risposta giusta su dove scrivere qualcosa è quasi sempre «flash per i piccoli record fissi, SD per tutto il resto.» I due non sono intercambiabili: un’applicazione che scarabocchia il proprio file di log progressivo su /flash esaurirà la resistenza alle scritture della flash in un’installazione in cui sarebbe andato tutto bene su SD.

14.3.3.2. Tratta entrambi come soggetti a guasti

/flash e /sdcard possono entrambi guastarsi. La scheda SD può essere espulsa, la flash può danneggiarsi a causa di un’interruzione di corrente nel mezzo di una scrittura, entrambe possono esaurire lo spazio, e qualsiasi operazione su una delle due può sollevare un OSError per motivi che l’applicazione non avrà la possibilità di diagnosticare sul campo.

Due pattern fanno sì che l’applicazione sopravviva a tutto questo:

  • Avvolgi i mount e le operazioni in blocchi try. Ogni open(), os.listdir(), os.rename() su percorsi di dati utente è potenzialmente soggetto a guasti. Cattura OSError, registralo nel log e ricorri a un’alternativa definita – scrivi su /flash se /sdcard non c’è, salta l’operazione se nessuno dei due è disponibile.

  • Scritture atomiche per i file che devono sopravvivere a un’interruzione di corrente. Scrivi su un percorso temporaneo, chiudi l’handle, poi usa os.rename() sul nome attivo. O il rename è riuscito e il file è la nuova versione, oppure non è riuscito e il file è la vecchia versione. Non esiste un terzo stato in cui il file è scritto a metà:

    import os

def write_config_atomic(path, contents):
    tmp = path + '.tmp'
    with open(tmp, 'w') as f:
        f.write(contents)
        f.flush()
    os.rename(tmp, path)

    Il pattern funziona sia su flash che su SD. Non funziona per file abbastanza grandi da far sì che il file temporaneo consumi lo spazio libero del filesystem; riservalo ai piccoli record.

14.3.3.3. La trappola della directory lenta

Il VFS di MicroPython non indicizza il contenuto delle directory come fa un filesystem desktop. os.listdir() e os.stat() scorrono linearmente la tabella dei file sottostante. Una directory con un centinaio di file va bene; una directory con diecimila file è inutilizzabilmente lenta, con ogni os.listdir() che richiede secondi e ogni open() che deve verificare la tabella durante il suo percorso.

Le applicazioni che scrivono log o acquisizioni su disco incontrano questo problema più rapidamente. Uno schema ingenuo come /sdcard/logs/<timestamp>.log che apre un nuovo file al minuto riempie la directory logs/ con mezzo milione di file in un anno di installazione. Molto prima di allora l’applicazione inizia a mancare il proprio frame rate perché ogni apertura di file richiede più tempo di un intervallo tra frame.

Il pattern giusto è distribuire i file su un albero di sottodirectory datate in modo che nessuna singola directory contenga mai più di qualche centinaio di voci:

import os
import time

LOG_ROOT = '/sdcard/logs'

def log_path(now=None):
    if now is None:
        now = time.localtime()
    year, month, day, hour = now[0], now[1], now[2], now[3]
    directory = '{}/{:04d}/{:02d}/{:02d}'.format(
        LOG_ROOT, year, month, day)
    _makedirs(directory)
    return '{}/{:02d}.log'.format(directory, hour)

def _makedirs(path):
    # os.makedirs equivalent -- create each level if missing
    parts = path.split('/')
    for i in range(2, len(parts) + 1):
        sub = '/'.join(parts[:i])
        try:
            os.mkdir(sub)
        except OSError:
            pass

Un anno di logging con un file all’ora è ora distribuito su 365 directory giornaliere, ciascuna contenente al massimo 24 file; os.listdir() su una qualsiasi singola directory rimane economico, e il ciclo dei frame dell’applicazione non si blocca sulle operazioni sui file man mano che l’installazione invecchia.

Lo stesso principio si applica alle acquisizioni di immagini, alle tracce dei sensori, o a qualsiasi altra cosa per cui l’applicazione scrive un file per evento. Se la frequenza degli eventi è alta, l’albero deve essere più profondo (anno/mese/giorno/ora, oppure anno/mese/giorno/ora/minuto) in modo che ogni directory foglia rimanga piccola. Se la frequenza degli eventi è bassa, un albero anno/mese è sufficiente.

14.3.3.4. Percorsi per dispositivo

In un parco di più di una cam, i file di log devono identificare da quale unità fisica provengono. machine.unique_id() restituisce un identificatore hardware impresso nella cam in fabbrica; è lo stesso valore tra un riavvio e l’altro, tra gli aggiornamenti del firmware, e tra le sostituzioni della scheda SD. Inseriscilo nel percorso del log o nei record del log e un operatore che guarda una pila di schede SD o un log centralizzato può capire quale sia quale:

import binascii
import machine

UNIT_ID = binascii.hexlify(machine.unique_id()).decode()

LOG_ROOT = '/sdcard/logs/' + UNIT_ID

Combinato con il pattern delle sottodirectory datate, il layout diventa /sdcard/logs/<unit-id>/2026/06/09/14.log – un’ora di record di una singola unità, in una directory abbastanza superficiale da poter essere scorsa, su un percorso che identifica l’unità sul filesystem stesso.

14.3.3.5. Mettere tutto insieme

La memoria scrivibile di una cam in produzione assomiglia all’incirca a questa:

  • /flash – configurazione, calibrazione, un marcatore di provisioning. Scritta raramente, letta spesso. Pattern di rename atomico per ogni file la cui perdita comprometterebbe il prossimo avvio.

  • /sdcard/logs/<unit-id>/<year>/<month>/<day>/<hour>.log – il log operativo. Scritto continuamente, ruotato dal percorso, mai scritto attraverso una directory con migliaia di elementi simili.

  • /sdcard/captures/<unit-id>/<year>/<month>/<day>/ – le acquisizioni di immagini o video che l’applicazione effettua. Stessa forma dell’albero, stesso motivo.

Quel layout costa all’applicazione circa venti righe di codice e la salva dai modi di fallimento che mettono fuori uso la cam mesi dopo l’inizio di un’installazione.