Si eres nuevo a programación, y buscas una maneera sencilla de comenzar con tu Circuit Playground Express y con CircuitPython, lo importate de saber es que esta librería provee exáctamente eso. Sin embargo, si deseas una explicación con más profundidad de como hace eso, con esto cubrimos tus necesidades. Esta sección entra en algunos concepto algo técnicos así que no te preocupes si no sigues de cerca todo. Hemos incluido esto para aclarar preguntas que usuarios más avanzados puedan tener sobre como funciona la librería por detrás del telón.

Existen múltiples capas de como esta librería funciona. La siguiente explicación es para la Librería Circuit Playground.

Note: Esta librería trabaja con la Circuit Playground Express y con la Circuit Playground Bluefruit, NOT para la Circuit Playground Classic. Cualquier referencia en esta explicación a "Circuit Playground" se refiere solo a las Express y Bluefruit.

Esta sección no está pensada para principiantes. Incluye una explicación muy técnica de como la Librería Circuit Playground trabaja. Asume que ya tienes un poco de conocimiento sobre CircuitPython, su código y como trabajan los módulos.

Módulos de Librería Circuit Playground

La librería está dividida en múltiples módulos. El módulo circuit_playground_base define una clase base llamada CircuitPlaygroundBase, la cual incluye características de la librería que están disponibles para ambas tarjetas Circuit Playground, tales como red_led, button_a, etc. El módulo de express define una clase Express, la cual es una subclase de CircuitPlaygroundBase, la cual agrega características solo disponibles en la Circuit Playground Express como son los aliases para touch.A7 hasta touch.TX (solo la CPX tiene la etiqueta A7 en el séptimo pad). El módulo bluefruit define de forma similar una clase Bluefruit, la cual agrega características disponibles solo para la Circuit Playground Bluefruit, tales como sound_level y loud_sound. Las clases de Express y de Bluefruit heredan características de la clase CircuitPlaygroundBase así que cuando cualquiera de los módulos específicos a la tarjeta sean importados, todas las características de la base y específicas a la tarjeta van a estar disponibles.

Dentro de los módulos, todas las librerías de CircuitPython necesarias son importadas. Toda la inicialización de software y de hardware se realiza en __init__() dentro del módulo, tales como inicializar el acelerómetro o creando variables que luego se van a utilizar. Luego utilizamos métodos y propiedades para exponer las características para usar en tu código.

Uso de Librería Circuit Playground

Para usar la librería, usted incluye from adafruit_circuitplayground import cp al principio de su programa. Lo primero que hace la librería es utilizar  sys.platform para determinar si la tarjeta conectada tiene una microcontroladora Atmel SAMD21 o una nRF52840. Este código está contenido dentro del archivo __init__.py, y se ejecuta al importar, antes que cualquier otro código. Basado en los resultados, importa la librería apropiada, ya sea la express o la bluefruit. Así que digamos que estás corriendo la Circuit Playground Bluefruit, todas las características de bluefruit van a ser importadas. El mecanismo de importa permite que el mismo pedazo de código funcione en todas las tarjetas Circuit Playground. Esta es la esencia de __init__.py:

Download: file
import sys
if sys.platform == 'nRF52840':
    from .bluefruit import cpb as cp
elif sys.platform == 'Atmel SAMD21':
    from .express import cpx as cp

Una vez importada, todas las características de la tarjeta conectada van a estar disponibles para usar como cp.nombre_característica. Por ejemplo, para hablarle al pequeño LED rojo, usted utilizaría cp.red_led en tu programa.

Esta librería es algo inusual en que no debes crear un objeto primario usted mismo. En cambio, el objeto es creado al importar. Cuando usted realiza un from adafruit_circuitplayground import cp, estás importando el objeto cp el cual ya ha sido creado y se le ha asignado el nombre de cp. Usted no utiliza de forma directa las clases de Express o de Bluefruit.

Esta librería fue escrita originalmente solo para la Circuit Playground Express. Anteriormente, usted hubiera podido importar from adafruit_circuitplayground.express import cpx. cpx es el nombre para el objeto clase Express que es creado dentro del módulo express.py. Cuando le agregamos a la librería capacidades para la Circuit Playground Bluefruit, hicimos que el módulo bluefruit.py cree un objeto llamado cpb, análogo a cpx. Sin embargo, nos dimos cuenta que para que el código funcionara en ambas tarjetas, iba a ser necesario cambiar todas las referencias de  cpb por cpx o vice versa. Para aliviar esto, hemos agregado __init__.py, el cual, según describimos arriba, descubre en cual tarjeta está corriendo el código, e importa ya sea cpx o cpb, renombrándolo a simplemente cp

Librería Circuit Playground vs. CircuitPython Básico

Sin esta librería, cada funcionalidad de la tarjeta requeriría configuración individual en tu código, pudiendo ser de un cambio a varias líneas adicionales en tu código. Considera los siguientes ejemplos.

El primer ejemplo prende el LED rojo sin utilizar la Librería Circuit Playground.

Download: file
import digitalio
import board

led = digitalio.DigitalInOut(board.D13)
led.direction = digitalio.Direction.OUTPUT

led.value = True

Este segundo ejemplo prende el LED rojo utilizando la Librería Circuit Playground:

Download: file
from adafruit_circuitplayground import cp

cp.red_led = True

En lugar de incluir la configuración en el programa, la Librería Circuit Playground incluye toda la configuración en __init__() dentro del módulo, por lo que la configuración se realiza automáticamente cuando importas la librería. Este es un ejemplo sencillo para comparación; algún hardware requiere considerablemente más configuración que el LED rojo.

La Librería en una Circuit Playground Express

La Librería Circuit Playground siempre ha empujado las barreras en cuanto a límites de memoria se refiere en la Circuit Playground Express. Esto nos hizo que incluyéramos la Librería Circuit Python y todas sus dependencias en la versión de CircuitPython que se prepara para la Circuit Playground Express, como módulos congelados.

Los módulos congelados son librerías que están "congelados" o  integrados en CircuitPython. El congelar un módulo dentro de CircuitPython mueve la ejecución hacia el flash para ahorrar RAM. Normalmente cuando un módulo es importado, lo siguiente sucede:

  • Si es un archivo .py, es compilado en "byte codes", que se colocan en RAM y se ejecutan ahí
  • Si es un archivo .mpy, ya se encuentra compilado hacia "byte codes" los cuales se ponen en RAM

Ambas de estas opciones utilizan RAM disponible. Este módulo es lo suficientemente complejo que rápidamente se quedó corta la memoria RAM de la Circuit Playground Express. Por lo que congelamos el archivo .mpy dentro de CircuitPython. Un .mpy congelado ya se encuentra compilado en byte codes como cualquier otro archivo .mpy, pero los byte codes ya están disponibles en memoria que se puede accesar directamente (flash), así que no deben ser copiados en RAM. Esto ahorra algo de RAM.

Dicho de otra forma, nos permite correr un módulo que normalmente se quedaría sin memoria a la hora de importar y te causaría un fallo al solicitar memoria. Esto también significa que para usar la librería con la Circuit Playground Express, solamente necesitas instalar CircuitPython ya que la librería y todas sus dependencias están incluidas en su versión de CircuitPython.

Normalmente, usted carga módulos de librerías a su microcontroladora y las pone en la carpeta lib. Sin embargo, según explicamos, este módulo no va a funcionar si está corriendo como una copia local. El módulo express utiliza sys.path al importar para especificar de donde se debe jalar el módulo de la librería. El va a preferir módulos congelados a los que se encuentran en la carpeta /lib para asegurarse de que si un usuario instala una librería local en la carpeta /lib, todavía va a seguir usando el módulo congelado. Sin embargo, también revisa el directorio raíz primero. En orden, primero revisa la raíz, luego revisa los congelados y luego la carpeta /lib. Este orden se definió para asegurarse que puedas cargar librerías de forma local para probarlas si necesidad de modificar la librería. Si deseas probar modificaciones a uno de los módulos congelados en CircuitPython para la Circuit Playground Express, coloque esa librería en su directorio raíz, y va a utilizar esta versión.

 

Errores al Solicitar Memoria en la Circuit Playground Express

Puede que te pase con grandes cantidades de código o con proyectos un poco más complicados que usan dispositivos externos, que tu código falla en correr y recibes un error de MemoryError en la consola serial. La Librería Circuit Playground incluye todos los imports y configuración necesaria para usar la funcionalidad que provee. Esto significa que tiene una huella de memoria relativamente grande. La Circuit Playground Express tiene su memoria disponible limitada. Esta librería se diseñó para hacer sencillo el comenzar con una Circuit Playground y todas las cosas divertidas que trae integradas. Si la tratas de utilizar con una cantidad significativa de código o con muchas otras librerías, es posible que encuentres que se te acaba la memoria de la tarjeta. Si esto sucede en cualquiera de estos escenarios, es posible que ya estás listo para utilizar las librerías individuales necesarias para el hardware que estás tratando de usar en tu código. Esto significa que usarías el CircuitPython básico para manualmente inicializar todo el hardware que deseas utilizar, en lugar de depender de la Librería Circuit Python. Esto te permite inicializar solo el hardware que vas a utilizar en tu proyecto, versus a la Librería CircuitPython inicializando todas las características disponibles en la CPX.

This guide was first published on Jul 28, 2020. It was last updated on Jul 28, 2020.

This page (El Lado Técnico) was last updated on Nov 06, 2020.