Gerenciamento de pacotes¶

Instalando pacotes com `mip`¶

Placas com capacidade de rede incluem o módulo mip, que pode instalar pacotes a partir da micropython-lib e de sites de terceiros (incluindo GitHub, GitLab).

O mip (“mip installs packages”) é semelhante em conceito à ferramenta pip do Python, porém ele não usa o índice PyPI; em vez disso, usa a micropython-lib como seu índice por padrão. O mip buscará automaticamente o .mpy file compilado ao fazer o download a partir da micropython-lib.

A forma mais comum de usar o mip é a partir do 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)

O mip detectará uma localização apropriada no sistema de arquivos pesquisando em sys.path a primeira entrada que termina em /lib. Você pode substituir o destino usando target, mas observe que esse caminho deve estar em sys.path para que seja possível importá-lo posteriormente:

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

Além de baixar pacotes do índice da micropython-lib, o mip também pode instalar bibliotecas de terceiros. A maneira mais simples é baixar um arquivo diretamente:

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

Ao instalar um arquivo diretamente, o argumento target ainda é suportado para definir o caminho de destino, mas mpy e version são ignorados.

A URL também pode começar com github: ou gitlab: como uma forma simples de apontar para conteúdo hospedado no GitHub ou 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

Pacotes mais sofisticados (ou seja, com mais de um arquivo, ou com dependências) podem ser baixados especificando o caminho para o seu 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")

Se nenhum arquivo json for especificado, então “package.json” é adicionado implicitamente:

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

Usando o `mip` na porta Unix¶

Na porta Unix, o mip pode ser usado no REPL como acima, e também usando -m

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

Os argumentos --target path, --no-mpy e --index podem ser definidos:

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

Instalando pacotes com `mpremote`¶

A ferramenta mpremote também inclui a mesma funcionalidade do mip e pode ser usada a partir de um PC host para instalar pacotes em um dispositivo conectado localmente (por exemplo, via USB ou 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

Os argumentos --target=path, --no-mpy e --index podem ser definidos:

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

O mpremote também pode instalar pacotes a partir de arquivos armazenados no sistema de arquivos local do host:

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

Isso é especialmente útil para testar pacotes durante o desenvolvimento e para instalar pacotes a partir de clones locais de repositórios do GitHub. Observe que as URLs nos arquivos package.json devem usar barras (“/”) como separadores de diretório, mesmo no Windows, para que sejam compatíveis com a instalação a partir da web.

Instalando pacotes manualmente¶

Os pacotes também podem ser instalados (na forma .py ou .mpy) copiando manualmente os arquivos para o dispositivo. Dependendo da placa, isso pode ser feito via Armazenamento em Massa USB, pela ferramenta mpremote (por exemplo, mpremote fs cp path/to/package.py :package.py), webrepl, etc.

Escrevendo e publicando pacotes¶

Publicar na micropython-lib é a maneira mais fácil de tornar seu pacote amplamente acessível aos usuários do MicroPython, e automaticamente disponível via mip e mpremote e compilado em bytecode. Consulte https://github.com/micropython/micropython-lib para mais informações.

Para escrever um pacote “auto-hospedado” que possa ser baixado pelo mip ou mpremote, você precisa de um servidor web estático (ou do GitHub) para hospedar um único arquivo .py ou um arquivo package.json ao lado dos seus arquivos .py.

Uma biblioteca mlx90640 de exemplo hospedada no GitHub poderia ser instalada com:

$ mpremote mip install github:org/micropython-mlx90640

O layout do pacote no GitHub poderia ser parecido com:

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

O package.json especifica a localização dos arquivos a serem instalados e outras dependências:

{
  "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"
}

A lista urls especifica os arquivos a serem instalados de acordo com:

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

onde destination_path é a localização e o nome do arquivo a ser instalado no dispositivo e source_url é a URL do arquivo a ser instalado. A URL de origem normalmente seria especificada de forma relativa ao diretório que contém o arquivo package.json, mas também pode ser uma URL absoluta, por exemplo:

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

O pacote depende de collections-defaultdict e os-path, que serão instalados automaticamente a partir da micropython-lib. A terceira dependência instala o conteúdo conforme definido pelo arquivo package.json do branch main do repositório GitHub org/micropython-additions.

Congelando pacotes (freezing)¶

Quando um módulo ou pacote Python é importado do sistema de arquivos do dispositivo, ele é compilado em bytecode na RAM, pronto para ser executado pela VM. Para um .mpy file, essa conversão já foi feita, mas o bytecode ainda acaba ficando na RAM.

Para dispositivos com pouca memória, ou para aplicações grandes, pode ser vantajoso executar o bytecode a partir da ROM (ou seja, da memória flash). Isso pode ser feito “congelando” (freezing) o bytecode no firmware do MicroPython, que é então gravado no dispositivo. O desempenho em tempo de execução é o mesmo (embora a importação seja mais rápida), mas isso pode liberar quantidades significativas de RAM para o seu programa usar.

A desvantagem dessa abordagem é que o desenvolvimento fica muito mais lento, porque você precisa gravar o firmware a cada vez, mas ainda pode ser útil congelar dependências que não mudam com frequência.

O congelamento (freezing) é feito escrevendo um arquivo de manifesto e usando-o na compilação, frequentemente como parte de uma definição de placa personalizada. Consulte o guia Arquivos de manifesto do MicroPython para mais informações.