Gestão de pacotes¶

Instalar pacotes com `mip`¶

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

mip («mip installs packages») é conceitualmente semelhante à ferramenta pip do Python; no entanto, não utiliza o índice PyPI, mas sim micropython-lib como índice predefinido. O mip obtém automaticamente .mpy file compilados ao descarregar a partir de micropython-lib.

A forma mais comum de utilizar 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 deteta um local adequado no sistema de ficheiros pesquisando em sys.path a primeira entrada que termina em /lib. Pode substituir o destino utilizando target, mas note que este caminho deve estar em sys.path para poder ser importado posteriormente:

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

Além de descarregar pacotes do índice micropython-lib, o mip pode também instalar bibliotecas de terceiros. A forma mais simples é descarregar diretamente um ficheiro:

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

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

O URL pode também começar com github: ou gitlab: como forma simples de apontar para conteúdo alojado 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 (isto é, com mais de um ficheiro ou com dependências) podem ser descarregados especificando o caminho para o respetivo 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 não for especificado nenhum ficheiro json, «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")

Utilizar o `mip` no port Unix¶

No port Unix, o mip pode ser utilizado no REPL como indicado acima, e também através de -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

Instalar pacotes com `mpremote`¶

A ferramenta mpremote inclui também a mesma funcionalidade que o mip e pode ser utilizada a partir de um PC anfitrião para instalar pacotes num dispositivo ligado 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 pode também instalar pacotes a partir de ficheiros armazenados no sistema de ficheiros local do anfitrião:

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

Isto é particularmente útil para testar pacotes durante o desenvolvimento e para instalar pacotes a partir de clones locais de repositórios GitHub. Note que os URLs nos ficheiros package.json devem utilizar barras oblíquas («/») como separadores de diretório, mesmo no Windows, para que sejam compatíveis com a instalação a partir da web.

Instalar pacotes manualmente¶

Os pacotes podem também ser instalados (em formato .py ou .mpy) copiando manualmente os ficheiros para o dispositivo. Dependendo da placa, isto pode ser feito via USB Mass Storage, a ferramenta mpremote (por exemplo, mpremote fs cp path/to/package.py :package.py), webrepl, etc.

Escrever e publicar pacotes¶

Publicar em micropython-lib é a forma mais fácil de tornar o seu pacote amplamente acessível aos utilizadores do MicroPython, ficando automaticamente disponível através do mip e do mpremote e compilado para bytecode. Consulte https://github.com/micropython/micropython-lib para mais informações.

Para escrever um pacote «auto-alojado» que possa ser descarregado pelo mip ou pelo mpremote, é necessário um servidor web estático (ou GitHub) para alojar um único ficheiro .py ou um ficheiro package.json juntamente com os seus ficheiros .py.

Uma biblioteca mlx90640 de exemplo alojada no GitHub pode ser instalada com:

$ mpremote mip install github:org/micropython-mlx90640

A disposição do pacote no GitHub pode ter o seguinte aspeto:

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

O package.json especifica a localização dos ficheiros a instalar 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 ficheiros a instalar de acordo com:

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

onde destination_path é a localização e o nome do ficheiro a instalar no dispositivo e source_url é o URL do ficheiro a instalar. O URL de origem é normalmente especificado relativamente ao diretório que contém o ficheiro package.json, mas pode também ser um URL absoluto, 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 de micropython-lib. A terceira dependência instala o conteúdo conforme definido pelo ficheiro package.json do ramo main do repositório GitHub org/micropython-additions.

Congelar pacotes¶

Quando um módulo ou pacote Python é importado a partir do sistema de ficheiros do dispositivo, é compilado em bytecode na RAM, pronto para ser executado pela VM. Para um .mpy file, esta conversão já foi efetuada, mas o bytecode continua a terminar na RAM.

Para dispositivos com pouca memória, ou para aplicações grandes, pode ser vantajoso executar o bytecode a partir de ROM (isto é, memória flash). Isto pode ser feito «congelando» o bytecode no firmware do MicroPython, que é depois gravado no dispositivo. O desempenho em tempo de execução é o mesmo (embora a importação seja mais rápida), mas pode libertar quantidades significativas de RAM para o seu programa utilizar.

A desvantagem desta abordagem é que o desenvolvimento é muito mais lento, porque é necessário gravar o firmware de cada vez; no entanto, pode ainda ser útil congelar dependências que não mudam com frequência.

O congelamento é feito escrevendo um ficheiro de manifesto e utilizando-o na compilação, muitas vezes como parte de uma definição de placa personalizada. Consulte o guia Ficheiros de manifesto MicroPython para mais informações.