por Tiago Silva

O MyArduinoLibs organiza o desenvolvimento de várias bibliotecas Arduino em um único repositório. Cada diretório representa uma biblioteca independente, com seu próprio código, manifesto, versão e pacote.

O objetivo é manter um ambiente de trabalho padronizado sem obrigar o usuário a instalar o monorepo inteiro. Depois de publicada no PlatformIO Registry, cada biblioteca pode ser adicionada individualmente a outro projeto.

Estrutura e responsabilidades

Cada biblioteca segue a mesma organização:

<LIBRARY>/
├── README.md
├── assets/
├── development/
│   ├── DEVELOPMENT.md
│   ├── platformio.ini
│   ├── src/
│   │   └── main.cpp
│   └── test/
└── package/
    ├── library.json
    ├── library.properties
    ├── keywords.txt
    ├── examples/
    └── src/
  • package/: conteúdo entregue ao usuário, incluindo implementação, API, manifesto e exemplos públicos;
  • development/: projeto PlatformIO completo usado para compilar, gravar e depurar diretamente no hardware;
  • assets/: datasheets, diagramas e outros materiais internos que não precisam acompanhar a instalação.

library.json é o manifesto do PlatformIO. library.properties e keywords.txt são usados quando também se deseja compatibilidade com ferramentas do ecossistema Arduino. O README.md e os arquivos em assets/ documentam a biblioteca dentro do repositório, mas não acompanham o pacote instalado porque estão fora de package/.

O código da biblioteca existe somente em package/src/. Para utilizá-lo sem criar uma cópia, development/platformio.ini declara uma dependência local:

[env:development]
platform = <platform-id>
board = <board-id>
framework = arduino

lib_deps =
    symlink://../package

O protocolo symlink:// faz o projeto de desenvolvimento usar diretamente o pacote local e funciona sem a criação manual de links simbólicos no sistema operacional.

Manifesto library.json

Cada package/ possui um manifesto independente. Um modelo mínimo é:

{
  "$schema": "https://raw.githubusercontent.com/platformio/platformio-core/develop/platformio/assets/schema/library.json",
  "name": "LibraryName",
  "version": "0.1.0",
  "description": "Descrição objetiva da biblioteca",
  "keywords": ["arduino", "embedded"],
  "repository": {
    "type": "git",
    "url": "https://github.com/OwnerName/RepositoryName.git"
  },
  "authors": [
    {
      "name": "Author Name",
      "maintainer": true
    }
  ],
  "frameworks": ["arduino"],
  "platforms": "*"
}

Nome, versão e compatibilidade devem representar o pacote publicado. Quando o suporte estiver delimitado, prefira informar somente as plataformas realmente validadas. O campo opcional export controla inclusões e exclusões. Consulte o formato de library.json e as regras de exportação.

Versionamento

Cada biblioteca evolui de forma independente usando Semantic Versioning:

MAJOR.MINOR.PATCH
  • MAJOR: mudança incompatível na API;
  • MINOR: nova funcionalidade compatível;
  • PATCH: correção compatível.

Uma convenção de tag adequada ao monorepo é <LIBRARY>-v<VERSION>. A versão da tag deve coincidir com package/library.json.

Desenvolvimento local

development/ deve ser aberto como o projeto PlatformIO. Ele contém o ambiente completo para compilar, gravar e depurar diretamente no hardware, mas não contém a implementação da biblioteca.

O driver é editado em package/src/. Em development/src/main.cpp fica somente o firmware de bancada que utiliza esse driver.

1. Preparar o ambiente

Acesse o projeto da biblioteca:

cd <LIBRARY>\development

No platformio.ini, configure plataforma, placa, framework e a dependência do pacote local:

lib_deps =
    symlink://../package

2. Compilar

pio run

3. Gravar no target

pio run --target upload
pio debug

4. Gerar o pacote de publicação

Acesse o diretório que contém library.json e execute:

cd ..\package
pio pkg pack

pio pkg pack aplica as regras do manifesto e cria localmente um arquivo como LibraryName-0.1.0.tar.gz. Ele não compila, não exige login e não publica nada. Consulte a documentação de pio pkg pack.

5. Conferir o conteúdo de publicação

Liste o pacote sem extraí-lo:

tar -tf .\LibraryName-0.1.0.tar.gz

Na estrutura atual, o arquivo deve conter somente:

library.json
library.properties
keywords.txt
examples/
src/

Ele não contém o README.md, os arquivos de assets/ ou qualquer outro conteúdo mantido fora de package/. O .tar.gz é um artefato local de conferência e normalmente não deve ser versionado.

6. Publicar

A publicação exige uma conta autenticada. Para uso manual:

pio account login
pio account show

Depois do login, publique a partir de package/:

pio pkg publish --no-interactive

--no-interactive remove a confirmação do terminal, mas não substitui o login.

Criar uma tag ou gerar o .tar.gz não publica a biblioteca.

Além disso, uma combinação de nome e versão já publicada não pode ser reutilizada; uma correção exige nova versão.

Consulte pio account login, pio pkg publish.

Utilização em outro projeto

Depois da publicação, o consumidor declara somente o pacote necessário:

[env:application]
platform = <platform-id>
board = <board-id>
framework = arduino

lib_deps =
    controlandoeletrons/P4RTC @ 0.1.0

Informar proprietário, nome e requisito de versão evita ambiguidades e mantém o projeto reproduzível. Os demais diretórios do monorepo não são instalados.