Implementar APIs de camada de abstração de plataforma

Ver código-fonte no GitHub

Por Mason Tran

Colaborador da SiLabs

O OpenThread é independente do SO e da plataforma, com uma camada de abstração de plataforma (PAL) estreita. Essa PAL define:

• Interface de alarme para timer de execução livre com alarme
• Interfaces de barramento (UART, SPI) para comunicar mensagens de CLI e Spinel
• Interface de rádio para comunicação IEEE 802.15.4-2006
• Rotinas de inicialização específicas do GCC
• Entropia para geração de números aleatórios reais
• Serviço de configurações para armazenamento de configuração não volátil
• Interface de registro para enviar mensagens de registro do OpenThread
• Rotinas de inicialização específicas do sistema

Todas as APIs precisam ser implementadas com base no pacote de suporte ao build (BSP, na sigla em inglês) da camada de abstração de hardware (HAL, na sigla em inglês) subjacente.

Importante: a menos que seja indicado como opcional, as APIs da camada de abstração da plataforma são obrigatórias e precisam ser implementadas de acordo com as definições em cada arquivo de cabeçalho da API.

Os arquivos da API precisam ser colocados nos seguintes diretórios:

Tipo	Diretório
Implementação de PAL específica da plataforma	/openthread/examples/platforms/platform-name
Arquivos de cabeçalho: API de armazenamento não volátil	/openthread/examples/platforms/utils
Todos os outros arquivos de cabeçalho	/openthread/include/openthread/platform
BSP do HAL	/openthread/third_party/platform-name

Alarme

Declaração de API:

/openthread/include/openthread/platform/alarm-milli.h

A API Alarm fornece serviços de temporização e alarme fundamentais para a implementação do timer da camada superior.

Há dois tipos de serviço de alarme, millissegundo e microssegundo. O milissegundo é necessário para uma nova plataforma de hardware. O microssegundo é opcional.

UART

Observação: essa API é opcional.

Declaração de API:

/openthread/examples/platforms/utils/uart.h

A API UART implementa a comunicação fundamental da porta serial pela interface UART.

Embora os complementos da CLI do OpenThread e do NCP dependam da interface UART para interagir com o lado do host, o suporte à API UART é opcional. No entanto, mesmo que você não planeje usar esses complementos no exemplo de nova plataforma de hardware, recomendamos adicionar suporte por alguns motivos:

• A CLI é útil para validar se a porta funciona corretamente
• A ferramenta de automação de chicote usa a interface UART para controlar o OpenThread para fins de teste e certificação.

Se a plataforma de hardware de destino oferecer suporte a um módulo USB CDC em vez de UART, faça o seguinte:

• Instale o driver USB CDC correto no lado do host.
• Substituir a implementação da API UART pelo driver USB CDC (junto com o BSP) no lado do OpenThread, usando os mesmos protótipos de função

Rádio

Declaração de API:

/openthread/include/openthread/platform/radio.h

A API Radio define todas as funções necessárias chamadas pela camada MAC IEEE 802.15.4 superior. O chip de rádio precisa ser totalmente compatível com a especificação IEEE 802.15.4-2006 de 2,4 GHz.

Devido ao recurso de baixo consumo aprimorado, o OpenThread exige que todas as plataformas implementem o frame automático pendente (transmissão indireta) por padrão, e a tabela de correspondência de endereços de origem também precisa ser implementada no arquivo de origem radio.h.

No entanto, se o exemplo de nova plataforma de hardware estiver limitado a recursos, a tabela de endereços de origem poderá ser definida como comprimento zero. Consulte Auto Frame Pendente para mais informações.

Observação: a API otPlatRadioGetIeeeEui64 Radio PRECISA retornar um EUI-64 IEEE único administrado e atribuído pela fábrica que inclui o OUI do fabricante. O EUI-64 é usado para corresponder aos dados de direção durante a fase de descoberta do participante.

Diversos/Redefinir

Declaração de API:

/openthread/include/openthread/platform/misc.h

A API Misc/Reset oferece um método para redefinir o software no chip e consultar o motivo da última redefinição.

Entropia

Observação: a implementação dessa API é necessária em todas as portas do OpenThread.

Declaração de API:

/openthread/include/openthread/platform/entropy.h

A API Entropy fornece um gerador de números aleatórios verdadeiros (TRNG, na sigla em inglês) para a camada superior, que é usada para manter os recursos de segurança de toda a rede OpenThread. A API precisa garantir que um novo número aleatório seja gerado para cada chamada de função. Os recursos de segurança afetados pelo TRNG incluem:

• Valor de uso único AES CCM
• Instabilidade com atraso aleatório
• Endereço completo dos dispositivos
• O período aleatório inicial no timer de gotejamento
• IDs de token/mensagem CoAP

Muitas plataformas já integraram um gerador de números aleatórios, exibindo a API no pacote BSP. Caso a plataforma de hardware de destino não ofereça suporte a TRNG, considere usar a amostragem de módulo ADC para gerar um número aleatório de comprimento fixo. Faça a amostragem em várias iterações, se necessário, para atender aos requisitos de TRNG (uint32_t).

Quando a macro MBEDTLS_ENTROPY_HARDWARE_ALT é definida como 1, essa API também precisa fornecer um método para gerar a entropia de hardware usada na biblioteca mbedTLS.

Armazenamento não volátil

Observação: apenas uma dessas APIs precisa ser implementada em cada porta do OpenThread.

Declarações de API:

/openthread/include/openthread/platform/flash.h

ou

/openthread/include/openthread/platform/settings.h

O requisito de armazenamento não volátil pode ser atendido implementando uma das duas APIs listadas acima. A API Flash implementa um driver de armazenamento flash, enquanto a API Settings fornece funções para uma implementação de operação flash para a camada superior.

Essas APIs são expostas à camada superior:

• O tamanho de armazenamento não volátil disponível usado para armazenar dados do aplicativo (por exemplo, conjunto de dados operacionais ativo/pendente, parâmetros de rede atuais e credenciais de dispositivos de linha de execução para reassociação após a redefinição)
• Ler, gravar, apagar e consultar operações de status da memória flash

Use OPENTHREAD_CONFIG_PLATFORM_FLASH_API_ENABLE no arquivo de configuração principal do exemplo da plataforma para indicar qual API ela precisa usar. Se definido como 1, a API Flash precisa ser implementada. Caso contrário, a API Settings precisa ser implementada.

Essa flag precisa ser definida no arquivo /openthread/examples/platforms/platform-name/openthread-core-platform-name-config.h.

Logging

Observação: essa API é opcional.

Declaração de API:

/openthread/include/openthread/platform/logging.h

A API Logging implementa a funcionalidade de registro e depuração do OpenThread, com vários níveis de saída de depuração disponíveis. Essa API é opcional se você não planejar usar o registro do OpenThread no exemplo de nova plataforma de hardware.

O nível mais alto e mais detalhado é OPENTHREAD_LOG_LEVEL_DEBG, que imprime todas as informações de pacote bruto e registra linhas pela porta serial ou no terminal. Escolha um nível de depuração que atenda melhor às suas necessidades.

Específico do sistema

Declaração de API:

/openthread/examples/platforms/openthread-system.h

A API específica do sistema fornece principalmente operações de inicialização e desativação para a plataforma de hardware selecionada. Essa API não é chamada pela biblioteca OpenThread, mas pode ser útil para seu sistema/RTOS. Também é possível implementar a inicialização de outros módulos (por exemplo, UART, Radio, Random, Misc/Reset) neste arquivo de origem.

A implementação dessa API depende do seu caso de uso. Se você quiser usar os aplicativos CLI e NCP gerados para uma plataforma de exemplo, implemente essa API. Caso contrário, qualquer API pode ser implementada para integrar os drivers de exemplo da plataforma ao sistema/RTOS.