Guía para desarrolladores de ProffiePlaca V2 / ProffieOS

1. Alcance y versiones

El manual proporcionado documenta un flujo de trabajo para ProffiePlaca V2 basado en Arduino IDE, ProffieOS, un config.h archivo, el contenido de la tarjeta SD, los presets y los Blade Estilos.

La documentación actual de ProffieOS mantiene el mismo flujo de trabajo fundamental: instalar el soporte de Arduino, obtener ProffieOS, crear una configuración específica para la placa, seleccionarla mediante CONFIG_FILE, compilar y cargar el firmware y, a continuación, iterar sobre la configuración.

Fuentes de referencia prioritarias

1. Código/configuración específicos de la placa: El árbol de código fuente de ProffieOS y la configuración de la placa para el objetivo exacto.
2. Documentación oficial actual: Documentación de ProffieOS.
3. Referencia de la placa: Documentación de referencia de ProffiePlaca V2.
4. Historial del repositorio: Commits de GitHub y notas de versión cuando el comportamiento difiera entre versiones.

2. Arquitectura del firmware y modelo de fuente de verdad

Un sable de luz SUPERNEOX basado en Proffie debe tratarse como un sistema por capas: cableado del hardware → configuración específica de la placa → definiciones de funciones de ProffieOS → definiciones de hojas → presets/estilos/props → recursos de la tarjeta SD.

Un fallo en una capa puede manifestarse como un fallo en otra, por lo que el diagnóstico debe comenzar por la capa de dependencias más baja y avanzar hacia arriba.

3. Hardware de ProffiePlaca V2

ProffiePlaca V2 es un controlador de código abierto para sables de luz, diseñado para una personalización avanzada del firmware. Proporciona conexiones para alimentación, botones, LED direccionables, pantallas, sensores de movimiento, depuración y periféricos adicionales.

3.1 Hardware principal

• Controlador ProffiePlaca V2/V2.2
• Batería de ion-litio de 3,7 V
• Altavoz
• Hoja direccionable o hardware LED compatible
• Conexión Micro-USB para desarrollo
• Tarjeta microSD para sound fonts y recursos

3.2 Pines importantes

3.3 Consideraciones sobre el cableado

La mayoría de las conexiones de señal pueden utilizar cables de menor sección, pero las líneas de alimentación de la batería y los LED deben dimensionarse en función de la corriente prevista.

4. Entorno de desarrollo

4.1 Software necesario

• Arduino IDE
• Plugin de Arduino para ProffiePlaca
• Paquete de código fuente de ProffieOS
• Herramientas de controladores USB cuando sean necesarias
• Editor de texto plano/código para editar la configuración

4.2 Selección de la placa en Arduino

Para ProffiePlaca V2, selecciona el objetivo de placa correspondiente:

Tools → Placa → Proffieboard V2

5. Instalación de ProffieOS

5.1 Obtener ProffieOS

Para garantizar una configuración y compilación estables del firmware de los sables de luz SUPERNEOX, utiliza ProffieOS 5.9. Después de descargarlo, extrae los archivos de código fuente de ProffieOS en una carpeta de usuario con permisos de escritura, como Documentos o el Escritorio. No guardes el código fuente en ubicaciones protegidas, como Program Files, ni en otros directorios gestionados por el sistema, ya que los permisos de Windows pueden restringir el acceso a los archivos y provocar problemas de compilación.

El árbol de código fuente contiene el sketch principal de Arduino:

ProffieOS/ProffieOS.ino

Los directorios habituales incluyen:

config/
blades/
styles/
props/
sound/
motion/
functions/

5.2 Abrir el sketch de Arduino

Abrir:

ProffieOS/ProffieOS.ino

5.3 Utilizar el configurador V2

La documentación oficial de ProffieOS recomienda utilizar el configurador diseñado para tu versión específica de ProffiePlaca. Para los sables de luz SUPERNEOX equipados con ProffiePlaca V2.x, utiliza el siguiente configurador: Configurador de ProffiePlaca V2.x

Configura el código generado de acuerdo con el cableado real del sable, sus componentes de hardware y las funciones instaladas. El configurador proporciona un punto de partida fiable, pero las configuraciones avanzadas o personalizadas pueden requerir edición manual adicional después de la generación.

6. Crear y seleccionar un archivo de configuración

6.1 Crear un archivo de configuración

1. Abre el directorio config/ de ProffieOS.
2. Copia una plantilla de configuración existente.
3. Cámbiale el nombre por uno descriptivo.
4. Edita la configuración con un editor de texto plano.
5. Guarda el archivo.

6.2 Seleccionar la configuración mediante CONFIG_FILE

Abre ProffieOS.ino y activa exactamente un archivo de configuración:

// #define CONFIG_FILE "config/example.h"

#define CONFIG_FILE "config/my_saber_config.h"

Todas las definiciones de configuración que no utilices deben permanecer comentadas.

7. Comprender las secciones de configuración

Un archivo de configuración de ProffieOS contiene varias secciones que se procesan durante la compilación.

8. Parámetros principales de configuración

#ifdef CONFIG_TOP

#include "proffieboard_v2_config.h"

#define NUM_BLADES 1
#define NUM_BUTTONS 2
#define VOLUME 1000

const unsigned int maxLedsPerStrip = 144;

#define CLASH_THRESHOLD_G 1.0

#define ENABLE_AUDIO
#define ENABLE_MOTION
#define ENABLE_WS2811
#define ENABLE_SD
#define SAVE_STATE

#endif

9. Configuración de la hoja (* Nota: Actualmente no compatible con los sables de luz SUPERNEOX.)

La configuración de la hoja define el hardware LED físico, la detección de la hoja y su comportamiento lógico.

9.1 Ejemplo de una sola hoja

BladeConfig blades[] = {

 {
  0,
  WS2811BladePtr<144>(),
  CONFIGARRAY(presets)
 }

};

El primer valor es la resistencia del ID de la hoja utilizada para su detección. Normalmente se utiliza el valor 0 cuando no se requiere seleccionar un ID de hoja.

9.2 Configuraciones de varias hojas

Varias entradas BladeConfig permiten seleccionar diferentes configuraciones físicas mediante la identificación de la hoja.

9.3 SubBlade

SubBlade permite dividir los LED direccionables en varias zonas lógicas, como guardas laterales, cámaras de cristal y píxeles de acento.

10. Configuración de presets

Un preset combina:

• Sound font
• Pista de música
• Blade Estilo
• Nombre del preset

Preset presets[] = {

 {
  "TeensySF",
  "tracks/theme.wav",
  EstiloNormalPtr<CYAN>(),
  "cyan"
 }

};

11. Gestión de la tarjeta SD y los sound fonts

La tarjeta microSD almacena los recursos de ejecución utilizados por ProffieOS, incluidos sound fonts, pistas, recursos de configuración y recursos de pantalla opcionales.

11.1 Estructura recomendada de la tarjeta SD

SD CARD

├── SOUND/
│
├── TRACKS/
│
├── CONFIG/
│
├── FONT DIRECTORY 1/
│   ├── hum.wav
│   ├── swingl.wav
│   ├── swingh.wav
│   ├── clash.wav
│   └── blst.wav
│
└── FONT DIRECTORY 2/

11.2 Directorio de sound fonts

Cada sound font se almacena dentro de un directorio independiente. El nombre del directorio se referencia desde la configuración del preset.

Preset presets[] = {

 {
  "DarkLord",
  "tracks/theme.wav",
  EstiloNormalPtr<RED>(),
  "Dark Lord"
 }

};

12. Botones y props

Los botones determinan la interacción del usuario. El sistema de props interpreta las combinaciones de botones y las convierte en acciones del sable.

12.1 Acciones habituales

El comportamiento exacto viene determinado por el prop y la configuración de botones seleccionados. ProffieOS incluye varios props para sables, con implementaciones de botones/funciones estándar y avanzadas. No des por hecho que todos los props actuales de ProffieOS utilizan el mismo mapa de botones.

12.2 Configuración del prop

El prop seleccionado define:

• Temporización de los botones
• Interpretación de gestos
• Comportamiento del menú
• Funciones especiales

#include "props/saber.h"

Se pueden crear props personalizados para hardware especializado o controles específicos del producto.

13. Depuración mediante el monitor serie

El manual proporcionado documenta los siguientes comandos de uso habitual:

13.1 Activar la salida serie

#define ENABLE_SERIAL

13.2 Información de depuración habitual

• Mensajes de arranque
• Detección de la tarjeta SD
• Inicialización de la hoja
• Carga de presets
• Estado del sensor de movimiento
• Eventos de botones

14. Blade Estilos

Los Blade Estilos son el mecanismo principal que utiliza ProffieOS para definir el comportamiento visual de la hoja. Controlan el color, la animación, el encendido, la retracción, la respuesta a impactos, los efectos de bláster, el lockup, el drag, las transiciones y otros efectos interactivos.

14.1 Ejemplo de estilo básico

EstiloNormalPtr<RED>()

Los estilos básicos definen la apariencia predeterminada de una hoja. Las configuraciones más avanzadas utilizan funciones de estilo anidadas y capas de efectos para crear animaciones complejas.

14.2 Estructura de EstiloPtr

EstiloPtr<
  InOutHelper<GREEN, 300, 800, BLACK>()
>()

EstiloPtr se utiliza habitualmente para asignar un Blade Estilo completo. Los efectos complejos se crean combinando varias funciones, capas y transiciones.

14.3 Colores RGB

Rgb<255, 50, 0>

Los valores de los canales RGB van de 0 a 255. También pueden utilizarse colores con nombre, como RED, GREEN, BLUE, WHITE, and CYAN cuando sean compatibles.

14.4 Funciones de efectos habituales

14.5 Composición avanzada de estilos

Los usuarios avanzados pueden combinar funciones, capas, transiciones y efectos aleatorios para crear un comportamiento de hoja totalmente personalizado.

Layers<
 RED,
 AudioFlicker<RED,WHITE>,
 Impacto
>()

14.6 Varias hojas / píxeles de acento

Un preset puede contener varios Blade Estilos correspondientes a distintas definiciones lógicas de hojas. Esto permite utilizar estilos independientes para una hoja principal, guardas laterales, cámaras de cristal, tiras de acento y otros grupos de píxeles configurados.

14.7 Recursos para editar estilos

• Página principal de ProffieOS - Nota: Utiliza ProffieOS 5.9 para los sables de luz SUPERNEOX.
• Archivo de configuración de la SD
• ProffieOS Documentation
• Foro de soporte The Crucible
• Recursos de estilos de Fett263
• Documentación de configuración de hojas

15. Integración avanzada

15.1 Pantallas

Los módulos de pantalla compatibles pueden proporcionar:

• Información de la batería
• Selección de presets
• Navegación por el menú
• Estado durante la ejecución

15.2 Periféricos adicionales

Las configuraciones avanzadas pueden integrar:

• LED de acento
• Cámaras de cristal
• Iluminación de la guarda lateral
• Sensores personalizados
• Controladores externos

15.3 Flujo de trabajo recomendado para producción

16. Solución de problemas

17. Referencias para desarrolladores

• Guía oficial de instalación
• Repositorio de ProffieOS en GitHub
• Código fuente de configuración de la placa V2
• Página oficial de ProffieOS
• ProffieOS.ino / punto de entrada CONFIG_FILE