MÓDULO 2.7

Soporte para Hardware Custom

Cómo crear definiciones de placa para hardware personalizado

Santi Scagliusi, PhD

Comenzar arrow_downward
developer_board
Board Definition
Carpeta con archivos
account_tree
Jerarquía HW
Board → SoC → Arch
description
Archivos Clave
board.yml, .dts, Kconfig
pin_drop
Pinctrl
Asignación de pines

¿Por qué definir una placa custom?

Escenarios en los que necesitas crear tu propia definición de placa.

check_circle Necesitas una board definition cuando...

  • check Hardware propio: Has diseñado tu propia PCB con un SoC Nordic
  • check Pinout diferente: Usas pines distintos a los de los kits de desarrollo
  • check Periféricos específicos: Tu placa tiene sensores o componentes únicos
  • check Producción: Necesitas definir el hardware de tu producto final

inventory_2 El SDK ya proporciona...

  • done_all Definición del SoC: nRF52833, nRF5340, nRF9160, etc.
  • done_all Familias y series: Agrupaciones de SoCs relacionados
  • done_all Arquitectura CPU: ARM Cortex-M4, Cortex-M33
  • done_all Drivers de periféricos: GPIO, UART, SPI, I2C, etc.
lightbulb
Solo defines lo específico de tu hardware: La definición de placa describe qué pines usas, qué periféricos están conectados y cómo se configuran. Todo lo demás (SoC, drivers, arquitectura) ya está en el SDK.

¿Qué es una board definition?

Una carpeta con archivos de configuración que describen tu hardware.

Componentes principales

description Devicetree (.dts, .dtsi)
Descripción del hardware: pines, periféricos, direcciones de memoria.
settings Kconfig
Configuración del RTOS y software: opciones habilitadas, valores por defecto.
info Metadatos (board.yml)
Nombre, vendor, SoCs soportados, variantes de la placa.
code Código C (opcional)
Inicialización especial que no se puede expresar en devicetree.

Estructura de carpeta

boards/vendor/myboard/
boards/vendor/myboard/
board.yml # Metadatos
Kconfig.myboard # Selección SoC
myboard_nrf52833.dts # Devicetree
myboard-pinctrl.dtsi # Pin control
myboard_defconfig # Kconfig defaults
Kconfig.defconfig # Valores default
board.c # Init especial
Obligatorio
Opcional
info
HWMv2: Esta estructura corresponde al Hardware Model v2 (HWMv2) introducido en Zephyr 3.x. El formato anterior (HWMv1) es diferente y está obsoleto.

Jerarquía de hardware (HWMv2)

El SDK proporciona todo excepto la definición de tu placa.

developer_board Board LO DEFINES TÚ
keyboard_arrow_down Usa
memory SoC nRF52833, nRF5340, nRF9160
keyboard_arrow_down Pertenece a
family_restroom SoC Family nRF52, nRF53, nRF91
keyboard_arrow_down Parte de
view_list SoC Series nRF52 Series, nRF91 Series
keyboard_arrow_down Implementa
hub CPU Core Cortex-M4, Cortex-M33
keyboard_arrow_down Es
architecture Architecture ARM, RISC-V, x86
auto_awesome
El SDK hace el trabajo pesado: Solo necesitas decir qué SoC usas y cómo están conectados los periféricos. Todo lo demás (registros, drivers, configuración de la CPU) ya está definido.

Estructura de archivos

Archivos obligatorios y opcionales de una board definition.

check_circle Archivos obligatorios

board.yml Obligatorio

Metadatos: nombre legible, vendor, lista de SoCs soportados, variantes y revisiones.

Kconfig.myboard Obligatorio

Selecciona el SoC correcto (SOC_NRF52833_QIAA, etc.) cuando se elige esta placa.

myboard_nrf52833.dts Obligatorio

Devicetree de la placa: incluye el DTSI del SoC y define LEDs, botones, periféricos.

myboard-pinctrl.dtsi Obligatorio

Mapea señales de periféricos (UART TX/RX, SPI MOSI/MISO) a pines físicos del chip.

star Archivos opcionales (pero recomendados)

myboard_defconfig Recomendado

Kconfig defaults: habilita drivers necesarios, configura opciones típicas de la placa.

Kconfig.defconfig Opcional

Valores por defecto condicionales: solo aplican cuando la placa está seleccionada.

board.yml

El archivo de metadatos que identifica tu placa.

Ejemplo básico

board.yml
board:
name: "Mi Placa Custom"
vendor: miempresa
socs:
- name: nrf52833
variants:
- name: ns
qualifier: ns

Campos explicados

name
Nombre legible para humanos. Aparece en la documentación y herramientas.
vendor
Identificador del fabricante. Usado para organizar en boards/vendor/.
socs
Lista de SoCs soportados. Cada uno puede tener variantes (ns, xip, etc.).
variants
Variantes de build: ns = TrustZone Non-Secure, xip = Execute-in-place.
info
Board target: El nombre completo para compilar es myboard/nrf52833 o myboard/nrf52833/ns para la variante non-secure.

Kconfig y defconfig

Archivos de configuración del sistema operativo.

Kconfig.myboard (selección de SoC)

Kconfig.myboard
# Selección del SoC para esta placa
config BOARD_MYBOARD
select SOC_NRF52833_QIAA

Este archivo indica qué SoC específico usa la placa. El sufijo (QIAA, QFAA) indica el package y variante.

myboard_defconfig (valores por defecto)

myboard_nrf52833_defconfig
# Configuración por defecto
CONFIG_GPIO=y
CONFIG_SERIAL=y
CONFIG_CONSOLE=y
CONFIG_UART_CONSOLE=y
CONFIG_LOG=y
CONFIG_I2C=y

Habilita drivers y features que siempre se necesitan en esta placa. Evita repetir estas opciones en cada proyecto.

tips_and_updates
Convención de nombres: El archivo defconfig debe llamarse {board}_{soc}_defconfig para que el build system lo encuentre automáticamente.

Devicetree de placa

Describe el hardware específico de tu placa: includes y nodo raíz.

myboard_nrf52833.dts - Parte 1: Estructura base
/* Incluir definición del SoC */
/dts-v1/;
#include <nordic/nrf52833_qiaa.dtsi>
#include "myboard-pinctrl.dtsi"
/ {
model = "Mi Placa Custom";
compatible = "miempresa,myboard";
/* Alias para acceso fácil */
chosen {
zephyr,console = &uart0;
zephyr,shell-uart = &uart0;
};
/* ... continúa en siguiente slide */
input
Includes

Incluye el DTSI del SoC (define periféricos base) y el pinctrl de la placa (asignación de pines).

tune
chosen

Define qué periférico usa Zephyr para consola, shell, flash, etc. Son aliases del sistema.

Devicetree: Periféricos

Definición de LEDs, botones y habilitación de periféricos.

LEDs y Botones
/* LEDs de la placa */
leds {
compatible = "gpio-leds";
led0: led_0 {
gpios = <&gpio0 13 GPIO_ACTIVE_LOW>;
label = "LED Verde";
};
};
/* Botones */
buttons {
compatible = "gpio-keys";
button0: button_0 {
gpios = <&gpio0 11 ...>;
};
};
Habilitar UART0
/* Habilitar UART0 */
&uart0 {
status = "okay";
pinctrl-0 = <&uart0_default>;
pinctrl-names = "default";
};
lightbulb
gpio-leds / gpio-keys

Compatibles estándar de Zephyr para LEDs y botones conectados a GPIO.

power_settings_new
status = "okay"

Habilita un periférico definido en el DTSI del SoC. Sin esto, queda deshabilitado.

Pinctrl: asignación de pines

Mapea señales de periféricos a pines físicos del chip.

Sintaxis NRF_PSEL

NRF_PSEL(función, puerto, pin)
  • arrow_right función: UART_TX, UART_RX, TWIM_SDA, SPIM_MOSI, etc.
  • arrow_right puerto: 0 o 1 (según el SoC)
  • arrow_right pin: Número de pin (0-31)

Flexibilidad Nordic

swap_horiz

A diferencia de otros microcontroladores, los nRF permiten mapear casi cualquier periférico a casi cualquier pin.

GPIOTE: GPIO Task and Events permite esta flexibilidad mediante una matriz de conexiones programable.
tips_and_updates
Ventaja: Simplifica el ruteo de PCB al poder elegir los pines más convenientes para tu diseño.

Ejemplo de Pinctrl

Configuración de pines para UART e I2C.

UART0 pins
&pinctrl {
uart0_default: uart0_default {
group1 {
psels = <NRF_PSEL(UART_TX, 0, 6)>;
};
group2 {
psels = <NRF_PSEL(UART_RX, 0, 8)>;
bias-pull-up;
};
};
};
I2C0 pins
&pinctrl {
i2c0_default: i2c0_default {
group1 {
psels = <NRF_PSEL(TWIM_SDA, 0, 26)>,
<NRF_PSEL(TWIM_SCL, 0, 27)>;
};
};
};
layers
Groups

Agrupa pines con configuración similar. TX y RX van en grupos separados porque RX necesita pull-up.

tune
bias-pull-up

Habilita resistencia pull-up interna en el pin. Común para RX y señales I2C.

¿Dónde colocar la definición?

Opciones para ubicar tu board definition.

folder_special

Directorio dedicado

RECOMENDADO
~/custom-boards/
boards/miempresa/myboard/
board.yml
...

Mantiene las definiciones separadas del proyecto y del SDK.

west build -b myboard/nrf52833 \
  -DBOARD_ROOT=~/custom-boards
folder

Carpeta boards/ del proyecto

PARA PROTOTIPADO
mi-proyecto/
boards/miempresa/myboard/
board.yml
...
src/main.c
CMakeLists.txt

La definición vive junto con el código de la aplicación.

west build -b myboard/nrf52833
warning
VS Code: Para que la extensión nRF Connect encuentre tus placas, configura nrf-connect.boardRoots en settings.json con la ruta a tu directorio de boards.

Ejercicio: Crear una placa con VS Code

Usa el asistente de nRF Connect for VS Code.

Pasos del ejercicio

1
Abre la paleta de comandos
Ctrl+Shift+P / Cmd+Shift+P
2
Busca "Create a new board"
nRF Connect: Create a new board
3
Selecciona el SoC base
Elige nRF52833 o el SoC de tu proyecto
4
Completa el formulario
Nombre, vendor, ubicación de archivos
5
Revisa los archivos generados
board.yml, .dts, Kconfig, pinctrl
6
Personaliza el devicetree
Ajusta pines, añade periféricos

Consejos

tips_and_updates Buenas prácticas
  • check Usa un kit de desarrollo existente como referencia
  • check Copia el pinctrl de una placa similar y modifícalo
  • check Compila "blinky" primero para verificar la configuración básica
  • check Añade periféricos gradualmente y prueba cada uno
Verificar compilación
# Compilar blinky para tu placa
west build -b myboard/nrf52833 \
zephyr/samples/basic/blinky

Resumen del módulo

Conceptos clave para crear definiciones de placa personalizadas.

developer_board

Board definition

Carpeta con board.yml, devicetree, Kconfig y pinctrl que describe tu hardware.

account_tree

Jerarquía HWMv2

Board → SoC → Family → Series → CPU → Arch. Solo defines el nivel Board.

pin_drop

Pinctrl

NRF_PSEL() mapea señales de periféricos a pines físicos del SoC.

Referencia rápida

Archivos obligatorios
Metadatos board.yml
SoC selection Kconfig.myboard
Devicetree myboard_nrf52833.dts
Comandos útiles
west build -b myboard/nrf52833
-DBOARD_ROOT=/path/to/boards
NRF_PSEL(UART_TX, 0, 6)
tips_and_updates

"Una buena definición de placa es la base de un producto robusto."

Invierte tiempo en definir correctamente tu hardware desde el principio. Facilita el desarrollo, testing y mantenimiento a largo plazo.

arrow_forward Siguiente módulo

2.8 Bootloaders y DFU

Cómo actualizar el firmware de forma segura en dispositivos desplegados.

arrow_back Módulo 2.6 home Índice del curso Siguiente: Bootloaders arrow_forward