OpenMV MicroPython
Per iniziare¶
Questa guida descrive passo dopo passo come configurare il controllo di versione, ottenere e compilare una copia del codice sorgente per un port, creare la documentazione, eseguire i test e fornisce una descrizione della struttura delle directory del codice base di MicroPython.
Controllo del codice sorgente con git¶
MicroPython è ospitato su GitHub e utilizza Git per il controllo del codice sorgente. Il flusso di lavoro prevede che il codice venga prelevato e inviato da e verso il repository principale. Installa la versione di Git adatta al tuo sistema operativo per seguire i passaggi successivi.
Nota
Per i dettagli sulle istruzioni di installazione, consulta le istruzioni di installazione di Git. Scopri i comandi git di base in questo Git Handbook o in qualunque altra fonte presente in internet.
Nota
È incluso un file .git-blame-ignore-revs che evita che l’output di git blame venga ingombrato da commit dedicati alla sola formattazione del codice ma privi di modifiche funzionali. Consulta la documentazione di git blame per sapere come utilizzarlo.
Ottenere il codice¶
È consigliabile mantenere un fork del repository MicroPython per i tuoi scopi di sviluppo. La procedura per ottenere il codice sorgente comprende i seguenti passaggi:
Esegui il fork del repository https://github.com/micropython/micropython
Ora avrai un fork all’indirizzo <https://github.com/<your-user-name>/micropython>.
Clona il repository forkato utilizzando il seguente comando:
$ git clone https://github.com/<your-user-name>/micropython
Quindi, configura i repository remoti per poter collaborare al progetto MicroPython.
Configura l’upstream remoto:
$ cd micropython
$ git remote add upstream https://github.com/micropython/micropython
È prassi comune configurare upstream e origin su un repository forkato per facilitare la condivisione delle modifiche al codice. Puoi mantenere la tua mappatura, ma è consigliabile che origin punti al tuo fork e upstream al repository principale di MicroPython.
Dopo la configurazione descritta sopra, la tua impostazione dovrebbe essere simile a questa:
$ git remote -v
origin https://github.com/<your-user-name>/micropython (fetch)
origin https://github.com/<your-user-name>/micropython (push)
upstream https://github.com/micropython/micropython (fetch)
upstream https://github.com/micropython/micropython (push)
Ora dovresti avere una copia del codice sorgente. Per impostazione predefinita, ti trovi sul branch master. Per prepararti allo sviluppo successivo, è consigliabile lavorare su un branch di sviluppo.
$ git checkout -b dev-branch
Puoi dargli un nome qualsiasi. Dovrai ricompilare MicroPython ogni volta che passi a un branch diverso.
Compilare e creare il codice¶
Quando compili MicroPython, compili un port specifico, di solito destinato a una determinata board. Inizia installando le dipendenze richieste. Quindi compila il cross-compiler di MicroPython prima di poter compilare e creare il codice con successo. Questo vale in particolare quando si usa Linux per la compilazione. Le istruzioni per Windows sono fornite in una sezione successiva.
Dipendenze richieste¶
Installa le dipendenze richieste per Linux:
$ sudo apt-get install build-essential libffi-dev git pkg-config
Per il port stm32 è richiesto il cross-compiler ARM:
$ sudo apt-get install gcc-arm-none-eabi libnewlib-arm-none-eabi
Consulta la toolchain ARM GCC per i dettagli più recenti.
È richiesto anche Python 3. Verifica di avere Python disponibile sul tuo sistema:
$ python3
Python 3.5.0 (default, Jul 17 2020, 14:04:10)
[GCC 5.4.0 20160609] on linux
Type "help", "copyright", "credits" or "license" for more information.
>>>
Tutti i port supportati hanno diversi requisiti di dipendenza; consulta i rispettivi file readme.
Compilare il cross-compiler di MicroPython¶
Quasi tutti i port richiedono di compilare prima mpy-cross per eseguire la pre-compilazione del codice Python che verrà incluso nel firmware del port:
$ cd mpy-cross
$ make
Nota
Nota che mpy-cross deve essere compilato per l’architettura host e non per l’architettura di destinazione.
Se la compilazione è andata a buon fine, dovresti vedere un messaggio simile a questo:
LINK mpy-cross
text data bss dec hex filename
279328 776 880 280984 44998 mpy-cross
Nota
Usa make -C mpy-cross per compilare il cross-compiler in un’unica istruzione senza spostarti nella directory mpy-cross; in caso contrario dovrai eseguire cd .. per i passaggi successivi.
Compilare il port Unix di MicroPython¶
Il port Unix è una versione di MicroPython che gira su Linux, macOS e altri sistemi operativi simili a Unix. È estremamente utile per sviluppare MicroPython perché evita di dover distribuire il codice su un dispositivo per testarlo. In molti aspetti funziona in modo molto simile al binario python di CPython.
Per compilare il port Unix, assicurati che tutte le dipendenze relative a Linux siano installate come descritto nella sezione dedicata alle dipendenze richieste. Consulta Dipendenze richieste per assicurarti che tutte le dipendenze per questo port siano installate. Inoltre, assicurati di avere un ambiente funzionante per gcc e GNU make. Per l’esempio seguente è stato usato Ubuntu 20.04, ma altri sistemi unix dovrebbero funzionare con poche modifiche:
$ gcc --version
gcc (Ubuntu 9.3.0-10ubuntu2) 9.3.0
Copyright (C) 2019 Free Software Foundation, Inc.
This is free software; see the source for copying conditions. There is NO
warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
quindi compila:
$ cd ports/unix
$ make submodules
$ make
Se MicroPython è stato compilato correttamente, dovresti vedere quanto segue:
LINK micropython
text data bss dec hex filename
412033 5680 2496 420209 66971 micropython
Ora eseguilo:
$ ./micropython
MicroPython v1.13-38-gc67012d-dirty on 2020-09-13; linux version
Use Ctrl-D to exit, Ctrl-E for paste mode
>>> print("hello world")
hello world
>>>
Compilare il port Windows¶
Il port Windows include un file di progetto di Visual Studio micropython.vcxproj che puoi usare per compilare micropython.exe. Può essere aperto in Visual Studio o compilato da riga di comando usando msbuild. In alternativa, può essere compilato usando mingw, sia in Windows con Cygwin, sia su Linux. Consulta la documentazione del port Windows per ulteriori informazioni.
Compilare il port STM32¶
Come per il port Unix, devi installare alcune dipendenze richieste come descritto nella sezione Dipendenze richieste, quindi compilare:
$ cd ports/stm32
$ make submodules
$ make
Consulta la documentazione stm32 per maggiori dettagli sul flashing del firmware.
Nota
Consulta Dipendenze richieste per assicurarti che tutte le dipendenze per questo port siano installate. È necessario il cross-compiler. Anche arm-none-eabi-gcc deve essere nel $PATH oppure specificato manualmente tramite CROSS_COMPILE, sia impostando la variabile d’ambiente sia negli argomenti della riga di comando di make.
Puoi anche specificare quale board utilizzare:
$ cd ports/stm32
$ make BOARD=<board> submodules
$ make BOARD=<board>
Consulta ports/stm32/boards per le board disponibili, ad esempio «OPENMV4» o «OPENMV4P».
Compilare la documentazione¶
La documentazione di MicroPython viene creata utilizzando Sphinx. Se hai già installato Python, installa Sphinx usando pip. È consigliabile utilizzare un ambiente virtuale:
$ python3 -m venv env
$ source env/bin/activate
$ pip install -r docs/requirements.txt
Spostati nella directory docs:
$ cd docs
Compila la documentazione:
$ make html
Apri docs/build/html/index.html nel tuo browser per visualizzare la documentazione in locale. Consulta la documentazione su come importare la tua documentazione per usare Read the Docs.
Eseguire i test¶
Per eseguire tutti i test della suite di test sul port Unix usa:
$ cd ports/unix
$ make test
Per eseguire una selezione di test su una board/dispositivo connesso tramite USB usa:
$ cd tests
$ ./run-tests.py -t /dev/ttyACM0
Vedi anche Scrittura dei test.
Target make aggiuntivi per gli sviluppatori¶
In tutti i port basati su make esiste un target per stampare la dimensione di un file oggetto specifico. Quando una modifica è circoscritta a un singolo file, questo è utile per testare varianti e trovare alternative più piccole.
Ad esempio, per stampare la dimensione di objstr.o nella directory py/ quando si esegue una build standard unix:
$ make build-standard/py/objstr.sz
Analogamente, esiste un target per salvare la versione preprocessata di un file:
$ make build-standard/py/objstr.pp
In ports/unix ci sono target aggiuntivi relativi all’esecuzione dei test:
$ make test//int # Run all tests matching the pattern "int"
$ make test/ports/unix # Run all tests in ports/unix
$ make test-failures # Re-run only the failed tests
$ make print-failures # print the differences for failed tests
$ make clean-failures # delete the .exp and .out files from failed tests
Usare ci.sh in locale¶
MicroPython utilizza GitHub Actions per l’integrazione continua. Per ridurre la dipendenza da un sistema di CI specifico, i passaggi di build effettivi per le build basate su Unix si trovano nel file tools/ci.sh. Questo può essere usato anche come script sui desktop degli sviluppatori, con alcune avvertenze:
Per la maggior parte dei passaggi si presuppone un sistema Ubuntu/Debian simile a quello usato durante la CI.
Alcuni passaggi specifici presuppongono versioni specifiche di Ubuntu.
I passaggi di configurazione possono richiamare il gestore di pacchetti del sistema per installare pacchetti, scaricare e installare software da internet, ecc.
Per ottenere un messaggio d’uso che include l’elenco dei comandi, esegui:
$ tools/ci.sh --help
Ad esempio, puoi compilare e testare il port unix minimal con:
$ tools/ci.sh unix_minimal_build unix_minimal_run_tests
Se usi la shell bash, puoi aggiungere un comando ci con il completamento tramite tab:
$ eval $(tools/ci.sh --bash-completion)
Per la shell zsh, sostituisci --bash-completion con --zsh-completion. Per la shell fish, sostituisci --bash-completion con --fish-completion.
Quindi, digitando:
$ ci unix_cov<tab>
Questo completerà il nome del passaggio ci in unix_coverage_. Premendo tab una seconda volta verrà mostrato l’elenco dei passaggi corrispondenti:
$ ci unix_coverage_<tab>
unix_coverage_32bit_build
unix_coverage_32bit_run_native_mpy_tests…
Struttura delle cartelle¶
Ci sono alcune directory da tenere a mente per quanto riguarda la posizione di determinati dettagli implementativi. Di seguito è riportata una suddivisione delle cartelle di primo livello nel codice sorgente.
py
Contiene il compilatore, il runtime e l’implementazione della libreria principale.
mpy-cross
Contiene il cross-compiler di MicroPython che pre-compila gli script Python in bytecode.
ports
Codice per tutte le versioni di MicroPython per i port supportati.
lib
Librerie C di basso livello usate da qualsiasi port, per lo più librerie di terze parti.
drivers
Contiene i driver per hardware specifico, progettati per funzionare su più port.
extmod
Contiene un’implementazione in C di altri moduli non principali.
docs
Contiene la documentazione standard disponibile su https://docs.micropython.org/.
tests
Un’implementazione della suite di test.
tools
Contiene gli script usati dai processi di build e CI, nonché strumenti per l’utente come
mpremote.
examples
Codice di esempio per compilare MicroPython come libreria e come moduli nativi.