codepretzel / codepretzel_framework

Una infraestructura libre (O/S) de herramientas, técnicas y configuraciones que nos permita desarrollar software embebido de calidad, con facilidad de replicación, modularidad y con un proceso de desarrollo establecido.

El sueño de CoDe Pretzel (CoDe Pretzel Framework)

Soñamos construir una infraestructura de herramientas, documentación, técnicas y configuraciones que nos permita desarrollar software embebido de calidad, con facilidad de replicación, modularidad y con un proceso de desarrollo establecido.

Los 5 principios del Framework de CoDe Pretzel

1. Crear tu propio código reusable, (No empezar de cero cada vez)
2. Organizar tu proyecto (dónde va qué cosa)
3. Tener un proceso de desarrollo (cómo configurar tus compilaciones, pruebas y desplegue)
4. Reusar periféricos y técnicas implementados en industria (mejoras tu CV y no reinventas la rueda)
5. Tener cierta independencia de hardware en el código

El cómo vamos a lograr ésto está estipulado en el archivo de versiones.md donde se explica:

• Lógica de versionamiento
• Reglas de colaboración con ramas en github
• Propuesta de funcionalidades por versión

Algunos ejemplos de aplicación de los principios se pueden consultar aqui

Prioridad de funcionalidades para el Framework de CoDe Pretzel

• Reusabilidad
• Estandarización de un proceso de desarrollo
• Mantenibilidad

La documentación del framework es parte del mismo!

❕ Necesitamos ayuda para conseguirle un SSL a nuestro subdominio de documentación!

Se puede acceder desde el sitio framework.codepretzel.org

La documentación está dividida en secciones:

• Estructura, componentes y herramientas del framework
• Instalación, dependencias y requerimientos
• API
• Ejemplos de código de aplicación
• Scripts de configuración, integración y automatización
• Cómo contribuir al framework
  • Actualización de la documentación
    • Agregar/Editar secciones y contenido al proyecto de Sphynx
    • Generar documentación de código con Doxygen y Breathe
  • Procedimiento para crear nuevas ramas y Pull Requests

codepretzel_framework's Issues

Documentar cómo configurar Unity para empezar a hacer pruebas (con MPLABX)

Este issue incluye agregar a la documentación una guía para

• Descargar unity test framework
• Agregarlo a la estructura de carpetas de un proyecto
• Agregar el contenido de los archivos necesarios (test_harness.c y main.c)
• Cómo agregar esos archivos al proyecto de mplabx para que el proceso de make los vea
• Una manera de obtener los resultados de los tests
• Una descripción de qué tests y dónde se hacen esos tests
• en el dispositivo, fuera del dispositivo, en el simulador, etc
• Cómo incluirla en la compilación de pruebas, pero no en la de producción (con #ifdef)
• Un repositorio con el ejemplo enlazado a la documentación

Posible trabajo futuro
Una evolución de este issue podría ser el incluir al build system en el proceso de agregar/no agregar las pruebas y ejecutarlas por separado (esto probablemente sea resuelto con platformio test), en vez de usar un #ifdef

Verificar compatibilidad de Doxygen con readthedocs.org

Verificar si es compatible usar una estrategia de documentación por comentarios como Doxygen para implementar una documentación
readthedocs.org

Determinar dónde guardar las configuraciones de Platformio para Devices-Boards-Platforms-Frameworks en nuestro repositorio

Crear y configurar el toolchain y archivos de configuración para ATMega2560 para PIO CLI

Crear los archivos necesarios de PIO para

• Boards
• Platforms
• Devices

Así como agregar las configuraciones necesarias y los ejecutables correspondientes (compilador, linker, assembler, linker scripts, etc), tal que se pueda compilar programas para el ATMega2560 usando PIO CLI

Además de asegurar que se pueda replicar fácilmente esta configuración

Restricciones:

• Este issue necesita llevar su documentación asociada correspondiente en readthedocs.org, donde se explique cuáles son los archivos requeridos para soportar este dispositivo, las configuraciones, cómo usarlas en PIO y los ejemplos de archivos
• Si hay alguna anomalía requerida para poder flashear el dispositivo es importante agregar ese apéndice a la documentación, ya sea particular al board usado o a la herramienta usada (ej. OpenOCD, MPLABX, etc)

Guía de configuración y prueba inicial del framework 0.1.0

Describe cómo:

• Descargar, configurar, instalar y usar el framework.
• Dónde encontrar sus recursos.
• Qué guía usar para modificar la documentación.
• Cuál es la organización del proyecto
• Cómo compilar y usar el programa de prueba de "hola led"

Configurar Doxygen + Breathe + Sphynx + Readthedocs en el repo principal usando los ejemplos de código existentes

Objetivo
Configurar y documentar la forma en que se van a conectar dichas herramientas para que se pueda generar la documentación directamente del código en las API

Preferente pero no obligatorio
Adjuntar un github hook o una github task para que se compile la documentación con doxygen y se haga el pipeline automaticamente, de ser el caso, este agregado DEBE estar documentado en el framework, en caso de quererse duplicar en otra cuenta de github

Parece ser que el soporte principal es para sphynx

Si se quisiera usar con Doxygen, es posible, pero probablemente tenga que usarse un intermediario

• Ejemplos de uso de Doxygen + Breathe + Sphynx + Readthedocs
• Articulo Integrate Doxygen into Sphynx using Doxygen and Breath

Nota: Aún no queda claro si Sphynx soporta directamente C, para poder reemplazar a Doxygen, pero por lo pronto se hará la secuencia de Doxygen a Sphynx y readthedocs

---

Para usar read the docs, tenemos:

• Usando sphynx + readthedocs para documentar

• El tutorial principal de readthedocs.org

• La herramienta para importar un repo a read the docs

• El proyecto template en github o crear el propio desde cero

---

Conclusión:
No soporta Doxygen, solo Sphynx.
Se puede utilizar usando Breath.

Guia que estipula la nomenclatura inicial de la interface portable para aquellas funciones que no pudieron ser generados con un `custom name`

Crear una guía para la documentación en codepretzel.framework.org que estipule la nomenclatura de las funciones que se van a usar en el código de la aplicación o de las bibliotecas.

En esta fase el programa es un hola led solamente, que utiliza los siguientes recursos de MCC

• Inicialización del sistema (no cuentan con custom name, necesita incluirse en la interface portable)
• Funciones para poner en alto y en bajo un GPIO (si cuentan con custom name)
• Funciones de delay (investigar si cuentan con custom name)

Los nombres que asignen a las funciones, a las variables y a los enum debenseguir las referencias siguientes

• Recomendaciones del libro "Reusable firmware APIs"
• Consistentes con el estándar BARR-C2018

Notas:

• La política de nombramiento se va a conservar, tanto como sea posible.
• En esta ocasión solo es necesario asignar nombres a las funciones que están enlistadas arriba para el programa de hola led, más adelante se irán viendo según las aplicaciones que se escriban, los nombres de los demás componentes del MCU

Crear, documentar y configurar el toolchain y archivos de configuración para MangoPI MQPro para PIO CLI

Nota:
Este board tiene RISCV
No sabemos si esto traiga configuraciones extras no previstas

Crear los archivos necesarios de PIO para

• Boards
• Platforms
• Devices

Así como agregar las configuraciones necesarias y los ejecutables correspondientes (compilador, linker, assembler, linker scripts, etc), tal que se pueda compilar programas para el AVR128DA48 usando PIO CLI

Además de asegurar que se pueda replicar fácilmente esta configuración

Restricciones:

• Este issue necesita llevar su documentación asociada correspondiente en readthedocs.org, donde se explique cuáles son los archivos requeridos para soportar este dispositivo, las configuraciones, cómo usarlas en PIO y los ejemplos de archivos
• Si hay alguna anomalía requerida para poder flashear el dispositivo es importante agregar ese apéndice a la documentación, ya sea particular al board usado o a la herramienta usada (ej. OpenOCD, MPLABX, etc)

Crear un archivo de propuestas o backlog para agregar mejoras

Un archivo que originalmente fué llamado "propuestas.md", pero que puede ser llamado backlog.md o de alguna manera que represente que es un archivo de mejoras al framework que pueden ser implementadas en futuras versiones.

Eventualmente este archivo se puede convertir en varios, un "backlog" para cada sección del framework, sin embargo no se creó un issue para la creación de esos nuevos archios, porque aún no se decide si será necesario.

Las secciones del framework son las siguientes:

• Documentación general del mismo (cómo usarlo, cómo usar las herramientas aledañas de las que depende)
• Documentación del código (nombres de funciones, implementaciones y parámetros, documentados con doxygen)
• Herramientas de desarrollo (migración a herramientas más complejas, como jira o similares)
• Código de aplicación (API de abstracción de hardware, código de prueba del framework como el hola led o el bootloader)
• Configuración y compilación (archivos de configuración, archivos de boards, proceso de administración de la compilación como makefiles o WAF)

Guía de edición de la documentación para agrega nuevas secciones o funcionalidades al framework

Guía para editar documentación pricinpal del framework y la documentación específica del API (ej. editar comentarios que use Doxygen para la API y editar directamente entradas de readthedocs para el resto de la documentación)

• Agrega / Editar secciones o subsecciones en sphynx para mostrarlas en readthedocs, para explicaciones de funcionalidades o configuraciones
• Agregar / Editar secciones basadas en Doxygen + Breathe + Sphynx + readthedocs

Documentar cómo agregar un framework personalizado a Platformio

Hasta ahora, parece que para lograr dicho objetivo es necesario cumplir con lo siguientes elementos:

• Crear un package para codepretzel_framework, incluye solo el folder interface_portable, solo las que no tienen custom name
• Crear un package para el código de MCC, todo el código generado por MCC
• Cómo relacionas ambos package en el mismo framework?, solo lo que asignes en el "platform"?
• Crear un ejemplo de uso del framework y del package MCC unidos, el hola led y agregarlo como ejemplo al framework package
• Crear un platform para AVR128DA copiando lo de AtmelMegaAVR y alguna si encuentro, agregarle soporte a Arduino y al de CoDe Pretzel
• Agregar los scripts de build para para los packages de MCC y del framework, que se usarán en el platform (no es seguro que tengan que tener uno diferente, a lo mejor se puede usar el mismo o se pueden integrar en un package de packages)
• Crear un board (si es que no existe ya el AVR128DA48 Curiosity Nano), para agregarle soporte a Arduino y al de CoDe Pretzel
• Crear un proyecto nuevo, seleccionar la board custom y seleccionar el ejemplo que incluye el framework, debería de funcionar la compilación

Nota:
Es posible que por ende, otros issues que originalmente estaban separados, se vean resueltos implicitamente, hay que tener precaución de hacer la nota y la referencia en ellos de que fueron cubiertos por este

Cómo subir nuestro propio board o framework o platform al repositorio de Platformio para poder descargarlos automáticamente en un nuevo proyecto en cualquier computadora

Revisar documentación de RIOT para saber qué se puede reutilizar de su perspectiva

https://www.riot-os.org/

Ver qué se puede reutilizar

• De su forma de administrar comunidad de hobbistas, industria y academia
• Forma de soportar diferentes arquitecturas
• Estructura principal modularizable
• Open Standards

Crear la estructura base del proyecto (nombres de carpetas y distribución de archivos)

Estructura de archivos y carpetas para un proyecto básico incluyendo la división por componentes de:

• Código fuente de aplicación (.c, .h, .a)
• Código fuente de periféricos (.c, .h, .a)
• Código fuente del API agnóstica al hardware (que conecta aplicación y drivers del fabricante)
• Toolchain, configuración y administración de compilación del proyecto (ej. pio y su estructura de archivos)

Crear un programa "Hola LED" para AVR128DA

Un programa que permita conectar una resistencia y un LED a un puerto y verlo parpadear cada segundo aproximadamente.
No hay restricción en la implementación, puede ser bloqueando el proceso con una función tipo delay() o usando un Timer, lo que facilite y sea más rápido de implementar.

Las restricciones son:

• El código debe estar documentado con Doxygen siguiendo la guía de documentación
• La compilación y flasheo del programa debe estar documentado en la guía de inicio de la version 0.1.0
• El proceso de compilación debe estar integrado con PIO CLI

Crear el proyecto ejemplo de Sphynx, incluirlo en CoDe Pretzel Docs repo y subirlo a read the docs

Para tener una idea de cómo se ve y qué es necesario mínimamente para tener la documentación.

Esto implica que se usaría el template de read the docs, que está basado en python y puede tener un par de diferencias importantes con la documentación de C, principalmente la habilidad de generar la documentación "automáticamente", según Sphynx, aunque no está claro aún qué significa.

Crear una sección en Readme.md principal para indicar las formas en las que se puede contribuir al proyecto del framework

Esta sección estaría enfocada a gente de fuera del equipo de administración, que está buscando formas de contribuir.
Puede ser

• Agregar una sugerencia en el archivo de sugerencias_y_mejoras.md a través de una pull request
• Ir a discord y comentar en el canal de "ideas y mejoras"
• Crear un fork, implementar una mejora y abrir un pull request de funcionalidad

Integrar estructuras de carpetas de Documentación al repositorio

Definir la estructura de carpetas a utilizar en la documentación para los proyectos ejemplo( ej. Hola Led para ATMega2560)
Una carpeta para

• Requerimientos
• Hardware
• Software.

Crear un programa "Hola LED" para ATMega 2560

Un programa que permita conectar una resistencia y un LED a un puerto y verlo parpadear cada segundo aproximadamente.
No hay restricción en la implementación, puede ser bloqueando el proceso con una función tipo delay() o usando un Timer, lo que facilite y sea más rápido de implementar.

Las restricciones son:

• El código debe estar documentado con Doxygen siguiendo la guía de documentación
• La compilación y flasheo del programa debe estar documentado en la guía de inicio de la version 0.1.0
• El proceso de compilación debe estar integrado con PIO CLI

Integrar el uso de read the docs en el repo principal de CoDePretzel_Framework

Es importante confirmar si la estructura que usa Sphynx (y por tanto read the docs) incluye el código fuente y otros elementos de documentación en el mismo repositorio.
Nosotros tenemos 2 repositorios diferentes, uno para código y el otro para pura documentación.

Sin embargo, de ser necesario serán unidos en el repo principal y CoDePretzel_Framework_Docs se eliminaría.

Para asegurar que este paso se aclare, es necesario:

1. Seguir el tutorial sphynx
2. Revisar si la documentación y el código viven en el mismo repo
3. Importar la documentación al repo principal CoDe Pretzel Framework
4. Eliminar el proyecto anterior de read the docs
5. Importar el repo principal a read the docs
6. Re compilar la documentación
7. Seguir el tutorial principal de read the docs

Crear y configurar el toolchain y archivos de configuración para AVR128DA48 para PIO CLI

Crear los archivos necesarios de PIO para

• Boards
• Platforms
• Devices

Así como agregar las configuraciones necesarias y los ejecutables correspondientes (compilador, linker, assembler, linker scripts, etc), tal que se pueda compilar programas para el AVR128DA48 usando PIO CLI

Además de asegurar que se pueda replicar fácilmente esta configuración

Restricciones:

• Este issue necesita llevar su documentación asociada correspondiente en readthedocs.org, donde se explique cuáles son los archivos requeridos para soportar este dispositivo, las configuraciones, cómo usarlas en PIO y los ejemplos de archivos
• Si hay alguna anomalía requerida para poder flashear el dispositivo es importante agregar ese apéndice a la documentación, ya sea particular al board usado o a la herramienta usada (ej. OpenOCD, MPLABX, etc)