Introducción a Silicon Labs BGAPI: ¿cómo controlar un módulo Bluetooth Mesh desde un host Linux por puerto serie?
Guía de BGAPI y NCP de Silicon Labs en Linux: firmware, XAPI, control de flujo UART, eventos de arranque y roles de nodo y provisionador Bluetooth Mesh.
Al hablar de la selección de chips para una pasarela Bluetooth Mesh, mencioné una división de tareas: el host Linux se encarga de la lógica de la aplicación, el módulo de Silicon Labs ejecuta la pila inalámbrica y ambos se comunican por puerto serie.
Dicho así, parece sencillo. Pero al empezar a conectarlos es fácil quedarse atascado en una situación: «el puerto serie se abre, pero el módulo no responde a las órdenes».
A menudo no falta un comando mágico para encender la luz. Lo que falta es alinear varios requisitos previos: el firmware instalado en el módulo, las definiciones de API que usa el host, el control de flujo del puerto serie y el papel del dispositivo Mesh dentro de la red.
Este artículo desglosa esa conexión a partir de la documentación oficial de NCP y los ejemplos en Python. Es una guía de integración basada en el código fuente; no se han realizado pruebas de integración con una placa de desarrollo física. Los pines, la velocidad en baudios y los componentes del firmware deben comprobarse según el hardware y el SDK que se utilicen.
El host Linux controla un punto de acceso a la pila de protocolos
En modo NCP, es decir, como coprocesador de red, la lógica de la aplicación se ejecuta en el host y la pila Bluetooth, en el chip de destino. Silicon Labs utiliza BGAPI para definir los comandos, las respuestas y los eventos entre ambos; UART es una forma habitual de comunicación.[1][2]
La ruta puede entenderse así:
Aplicación del host Linux → biblioteca BGAPI del host → puerto serie → firmware NCP de Silicon Labs → red Bluetooth Mesh.
BGAPI es el protocolo de interfaz de host de Silicon Labs. No es el protocolo Mesh que se transmite por radio ni un conjunto de comandos AT que pueda interpretar cualquier módulo Bluetooth con puerto serie.
Después de que el host envía un comando, el dispositivo de destino devuelve una respuesta y también puede comunicar eventos de forma asíncrona. No basta con escribir un bucle que «envía bytes y espera un segundo» y considerar que la operación terminó porque no hubo excepciones.
Además, hay distintos niveles de finalización: que la escritura en el puerto serie se complete, que el dispositivo de destino acepte el comando, que el dispositivo Mesh remoto devuelva un estado y que la luz cambie realmente no son el mismo resultado. Los registros de diagnóstico deben distinguirlos.
Primer paso: confirmar que el firmware y la API del host corresponden entre sí
Que un modelo de chip admita Bluetooth no significa que el firmware instalado proporcione la funcionalidad Mesh NCP necesaria.
Los ejemplos oficiales de pyBGAPI distinguen entre ejemplos de Bluetooth convencional y de Bluetooth Mesh. Los ejemplos Mesh utilizan dos definiciones de API, sl_bt.xapi y sl_btmesh.xapi. Tampoco se pueden intercambiar sin más un firmware BLE convencional, un firmware de nodo Mesh y uno destinado a gestionar el aprovisionamiento solo porque todos incluyan «NCP» en su nombre.[1]
XAPI describe cómo la biblioteca del host codifica los comandos e interpreta las respuestas. Si las definiciones de API del host no corresponden al firmware de destino, pueden aparecer comandos no admitidos, parámetros ausentes o errores de interpretación. Los ejemplos oficiales comparan cierta información de versiones al arrancar y muestran advertencias, pero esa comprobación no sustituye una verificación completa de compatibilidad.
Antes de empezar, conviene anotar cuatro cosas:
- La placa de desarrollo y el modelo de chip, así como la interfaz de hardware utilizada.
- El nombre del ejemplo de firmware, la versión del SDK y los componentes Mesh habilitados.
- La versión del programa del host, el origen de los archivos de definición de API y la versión de la biblioteca Python.
- El papel previsto: actuar como nodo que se incorpora a una red o como Provisioner que administra otros nodos.
Esta breve lista resulta más útil que actualizar repetidamente todos los componentes después de que surja un problema. Una actualización puede cambiar las interfaces; no se debe suponer que la biblioteca de host más reciente siempre será compatible con un firmware antiguo.
Segundo paso: alinear UART y el control de flujo
Que exista un dispositivo de puerto serie en Linux solo indica que el sistema ha reconocido la interfaz; no demuestra que el firmware de destino esté listo.
Antes de conectar los cables, hay que comprobar en la documentación de la placa los niveles eléctricos, la tierra, TX/RX y, si se habilita el control de flujo por hardware, RTS/CTS. No se debe conectar directamente una interfaz con niveles RS-232 a los pines UART del chip. Si se utiliza el puerto serie virtual de una placa de desarrollo, también hay que verificar la configuración serie del depurador integrado.
Los ejemplos NCP de la versión antigua de AN1259 habilitan el control de flujo por hardware de forma predeterminada y recalcan que los ajustes de control de flujo del dispositivo de destino y de la placa de desarrollo deben coincidir.[2] Esto puede explicar un síntoma frecuente: el puerto serie se abre, pero los datos no avanzan porque un extremo espera las señales de control de flujo del otro.
Sin embargo, esto no convierte «todas las interfaces BGAPI requieren cuatro cables» en una regla del protocolo. El transporte y la configuración de control de flujo concretos dependen del firmware y del hardware. La recomendación aquí es que, si se parte de un ejemplo que habilita RTS/CTS de forma predeterminada, se conserve y reproduzca inicialmente toda esa configuración. No se deben conectar solo los dos cables de datos mientras el software sigue esperando el control de flujo.
También hay que confirmar que un programa de terminal y el proceso de la aplicación no estén usando simultáneamente el puerto serie, y que el usuario actual tenga permisos de acceso. Ante un problema de permisos, primero se deben revisar los permisos del dispositivo y los grupos del usuario, en lugar de adoptar como solución predeterminada ejecutar el programa permanentemente como root.
Tercer paso: verificar la secuencia de arranque con el ejemplo oficial mínimo
El commit del repositorio oficial pybgapi-examples revisado para este artículo es 87d004f.[1] Fijar un commit facilita la reproducción, pero no garantiza que sea compatible con todos los SDK. Primero hay que comprobar las definiciones de API incluidas y el firmware de destino.
En un directorio local nuevo, se puede preparar un entorno Python independiente y consultar los parámetros del ejemplo:
git clone https://github.com/SiliconLabs/pybgapi-examples.git
cd pybgapi-examples
git checkout 87d004f1db3993bfa35783bec1ac58c32b5303e4
python3 -m venv .venv
. .venv/bin/activate
python -m pip install pybgapi
python example/btmesh_empty/app.py -h
Tras instalarla, hay que registrar la versión de la biblioteca que se instaló realmente. Aquí no se propone una «combinación universal de versiones» sin verificar. Si el SDK no corresponde, se deben utilizar el ejemplo y los archivos de API asociados al firmware y volver a comprobar las interfaces.
Una vez confirmado que se usa una placa de pruebas que puede reiniciarse, que el firmware corresponde y que la configuración serie coincide, el ejemplo oficial permite indicar el puerto serie como argumento posicional, por ejemplo:
python example/btmesh_empty/app.py /dev/ttyACM0
/dev/ttyACM0 es solo una ruta de ejemplo y debe sustituirse por el dispositivo real. La función auxiliar de conexión del repositorio está orientada a la configuración predeterminada de la placa de desarrollo. Para personalizar los parámetros serie hay que ajustarse a la interfaz de la biblioteca; no se puede añadir arbitrariamente al comando una opción de velocidad en baudios o de control de flujo que no exista.[3]
Este programa actúa sobre el dispositivo de destino; no es una consulta de solo lectura. En el código revisado, la secuencia de arranque solicita un reinicio, llama a btmesh.node.init() tras recibir bt_evt_system_boot y después el ejemplo procesa el evento de inicialización del nodo. Si el nodo aún no está aprovisionado, inicia la publicidad de dispositivo no aprovisionado.[3][4]
El objetivo de este paso es observar que el host y el dispositivo de destino completan el arranque y la inicialización del nodo, no controlar inmediatamente las luces de casa.
El README del repositorio oficial todavía afirma que el reset del ejemplo Mesh borra la configuración anterior del nodo, mientras que, en el código revisado, BtMeshApp.reset() llama a bt.system.reboot(). Ambas descripciones no coinciden. Este artículo explica el código del commit fijado y no equipara directamente el arranque del ejemplo con un restablecimiento de fábrica. Aun así, hay que revisar la versión que se utilice y, en particular, no experimentar con un reset de semántica incierta en un dispositivo que ya forme parte de una red de producción.[1][3]
Cuarto paso: decidir quién aprovisiona y quién controla
La clase base de btmesh_empty inicializa el papel de Node. La publicidad de dispositivo no aprovisionado significa «este nodo espera incorporarse a una red», no «ha empezado a aprovisionar otras luces».
Si la pasarela debe buscar dispositivos no aprovisionados, asignarles una identidad de red y configurarlos, hay que diseñarla siguiendo la ruta Host Provisioner del SDK y comprobar el firmware, el papel y la aplicación de host correspondientes. No basta con añadir una llamada para encender la luz al final del ejemplo Empty.[1][2]
Incluso después de aprovisionar correctamente un dispositivo, la configuración de la capa de aplicación no queda hecha automáticamente. Para controlar una luz hay que saber qué elementos y modelos admite, qué AppKey se utilizará, cómo se vinculan los modelos, si los comandos se enviarán a una dirección unicast o de grupo y si las suscripciones son correctas.
Estas relaciones se explican en ¿Por qué la luz sigue sin responder después de aprovisionarla en Bluetooth Mesh?. El NCP conectado por puerto serie solo proporciona acceso a la pila de protocolos; no omite esos pasos por ti.
Para la primera ronda de integración, conviene utilizar un único controlador y un único nodo de pruebas: primero definir la configuración de los modelos y luego completar una operación y comprobar el estado resultante. Una vez entendida la conexión con un solo dispositivo, se pueden incorporar la multidifusión, los reintentos y la sincronización de varios dispositivos.
Quinto paso: dejar libre el bucle de eventos para la comunicación
La clase común de los ejemplos oficiales recibe los eventos y los entrega a sus funciones de procesamiento correspondientes.[1][3] Aquí es donde más fácilmente puede complicarse el programa del host: recibe un mensaje, aprovecha para consultar una API en la nube, escribir en la base de datos y realizar un cálculo costoso, y todos los eventos posteriores quedan bloqueados.
Mi recomendación es mantener breve el procesamiento de la comunicación: interpretar y validar el mensaje, registrar el contexto necesario y delegar el trabajo costoso a otras unidades de ejecución. Es una sugerencia de diseño de la aplicación, no una garantía de rendimiento sobre todos los comportamientos de los hilos del ejemplo.
También hay que definir qué hacer cuando vence el tiempo de espera de un comando. No recibir un resultado no significa necesariamente que el dispositivo de destino no haya ejecutado la operación; reenviar el comando directamente puede provocar una segunda ejecución. La decisión de reintentar y la forma de relacionar solicitudes con estados deben diseñarse según la API, el modelo y la semántica de la aplicación.
Tampoco se debe confundir el reinicio del proceso del host con el reinicio del NCP. Tras reconectar, primero hay que confirmar el estado del dispositivo de destino y después decidir qué restaurar. No se deben borrar nodos, reconstruir la red ni repetir el aprovisionamiento incondicionalmente en cada reconexión. Antes de pasar a varios dispositivos, hay que definir dónde se guardarán las claves, la asignación de direcciones y el mapeo de dispositivos, y cómo se harán las copias de seguridad.
Si algo se atasca, diagnosticar por capas
| Síntoma observado | Qué comprobar primero | Conclusión que todavía no se puede sacar |
|---|---|---|
| No aparece el dispositivo serie o no se puede abrir | Controlador, conexión, permisos, dispositivo ocupado | El chip no admite Mesh |
| El puerto serie se abre, pero no llega el evento de arranque | Tipo de firmware, velocidad en baudios, control de flujo, forma de reinicio, interpretación de la API | La señal inalámbrica es demasiado débil |
| Se recibe el evento de arranque, pero el comando no está admitido | Versiones de la API y el firmware, componentes, papel, orden de inicialización | Aumentar el número de envíos resolverá el problema |
| Mesh se inicializa correctamente, pero la luz no responde | Aprovisionamiento, AppKey, vinculación de modelos, dirección de destino, suscripciones | La conexión BGAPI está necesariamente averiada |
| Funciona a pequeña escala, pero se vuelve inestable al aumentar la carga | Tiempo dedicado a procesar eventos, búferes, control de flujo y estrategia de reintentos | Todos los problemas proceden de los retransmisores inalámbricos |
Dejar un resultado observable en cada paso facilita localizar los problemas más que intentar construir una pasarela completa desde el principio. Primero hay que demostrar que el host y el NCP se comunican correctamente; después, que la configuración Mesh es correcta; solo entonces conviene conectarlos con Matter y la lógica de aplicación de nivel superior.
Esto enlaza también con la anterior lista de comprobación para la aceptación de la integración de la pasarela: entre un «envío por puerto serie completado» y ver el estado correcto del dispositivo en el teléfono hay varias etapas que deben verificarse por separado.
Fuentes
Fecha de consulta: 2026-11-09. La lectura de las páginas de documentación en línea del SDK oficial agotó el tiempo de espera en esta ocasión. Por ello, este artículo se basa en los ejemplos oficiales de un commit fijado y en una nota de aplicación cuya versión se indica expresamente; no afirma cubrir todas las interfaces del SDK más reciente.
- Silicon Labs pyBGAPI Examples: README del commit fijado, división de tareas del NCP, correspondencia de API, papeles Node y Provisioner y descripción de los ejemplos.
- AN1259: Bluetooth Stack v3.x and Higher in NCP Mode, Rev. 1.5, páginas 2, 16, 41 y 47 a 49, entre otras. La primera página del PDF indica que quedó obsoleto tras la publicación de Simplicity SDK Suite 2024.12.2; aquí solo se utiliza para explicar la arquitectura y el control de flujo de los ejemplos antiguos, sin presentar sus interfaces, rutas o comandos como válidos garantizados para la versión más reciente.
- Clase común del host y conector serie oficiales.
- Ejemplo oficial Bluetooth Mesh Empty.
Ilustración conceptual generada con IA; no es una prueba de producto, una interfaz real ni un diagrama de cableado.
Discussion
Share a question or your experience. Comments appear after moderation. Your email is never displayed publicly. Comment privacy
Loading comments…