Central de Ajuda para Desenvolvedores SUPERNEOX

Guia do Desenvolvedor ProffieBoard V2 / ProffieOS

Referência técnica para desenvolvedores de firmware, engenheiros de configuração, técnicos de produto e integradores avançados que trabalham com sabres de luz SUPERNEOX baseados no ProffieBoard V2/V2.2 e no ProffieOS.

Perfil da documentação: Português do Brasil Desenvolvedor / Técnico ProffieBoard V2/V2.2 ProffieOS

Documentação dependente da versão. O ProffieOS está em desenvolvimento contínuo. A sintaxe de configuração, props, styles, menus, comandos seriais e suporte de hardware podem mudar entre diferentes versões. Para cada compilação, considere a árvore de código-fonte exata do ProffieOS e a documentação oficial correspondente como referência final.

1. Escopo e controle de versões

Este manual apresenta um fluxo de trabalho para ProffieBoard V2 baseado no Arduino IDE, ProffieOS, um arquivo config.h, conteúdo do cartão SD, presets e Blade Styles.

A documentação atual do ProffieOS mantém esse fluxo fundamental: instalar o suporte do Arduino, obter o ProffieOS, criar uma configuração específica para a placa, selecioná-la por meio de CONFIG_FILE, compilar e fazer o upload e, em seguida, ajustar a configuração conforme necessário.

Referências prioritárias

  1. Código/configuração específica da placa: A árvore de código-fonte do ProffieOS e a configuração da placa correspondente ao hardware exato utilizado.
  2. Documentação oficial atual: Documentação do ProffieOS.
  3. Referência da placa: Documentação de referência do ProffieBoard V2.
  4. Histórico do repositório: Commits e notas de versão do GitHub quando houver diferenças de comportamento entre versões.

2. Arquitetura do firmware e modelo de referência

Um sabre SUPERNEOX baseado em Proffie deve ser tratado como um sistema em camadas: fiação do hardware → configuração específica da placa → definições de recursos do ProffieOS → definições de lâmina → presets/styles/props → arquivos armazenados no cartão SD.

Uma falha em determinada camada pode se manifestar como um problema em outra camada. Por isso, o diagnóstico deve começar pela camada de menor dependência e avançar progressivamente para as superiores.

Camada de hardware

Bateria, alto-falante, botões, dados/alimentação NeoPixel, identificação da lâmina, cartão SD, display, LEDs auxiliares e periféricos opcionais.

Camada de compilação

Arduino IDE, pacote/plugin da placa, árvore de código-fonte do ProffieOS e CONFIG_FILE selecionado.

Camada de execução

BladeConfig, presets, styles, props, comportamento de movimento/áudio, menus e estado persistente.

Camada de recursos

Sound fonts, faixas de áudio, arquivos de configuração, imagens, recursos de display e outros arquivos utilizados pelo sistema no cartão SD.

Boa prática recomendada: Para cada revisão de um sabre destinado à produção, arquive a versão ou commit exato do ProffieOS, o arquivo de configuração completo, o pacote de arquivos do cartão SD, a revisão da fiação e uma compilação conhecida como funcional.

3. Hardware do ProffieBoard V2

O ProffieBoard V2 é um controlador de sabres de luz de código aberto desenvolvido para permitir ampla personalização de firmware. A placa oferece conexões para alimentação, botões, LEDs endereçáveis, displays, sensores de movimento, depuração e outros periféricos.

3.1 Hardware principal

  • Controlador ProffieBoard V2/V2.2
  • Bateria Li-ion de 3,7 V
  • Alto-falante
  • Lâmina endereçável ou hardware LED compatível
  • Conexão Micro-USB para desenvolvimento
  • Cartão microSD para sound fonts e outros recursos

3.2 Pinos importantes

Conexão Função
BATT+ Entrada de alimentação da bateria para a placa.
BATT- Retorno da alimentação dos LEDs e caminho de retorno para correntes elevadas.
GND Conexão de terra para os circuitos eletrônicos da placa.
Button 1/2/3 Entradas para os botões físicos.
Data 1 / ID Medição do ID da lâmina e/ou saída de dados do primeiro LED endereçável.
Data 2 / Data 3 Saídas adicionais para LEDs endereçáveis.
Data4 / DAC Saída de dados adicional ou DAC de áudio, dependendo da configuração.
LED 1-6 Conexões para canais de LED compatíveis.
SDA / SCL Comunicação I²C para sensores de movimento e periféricos.
SWDIO / SWDCLK Interface de depuração ST-LINK.
Atenção à alimentação e à polaridade: A proteção contra polaridade reversa protege a placa, mas os componentes NeoPixel conectados ainda podem ser danificados pela conexão incorreta da polaridade da bateria.

3.3 Considerações sobre a fiação

A maioria das conexões de sinal pode utilizar fios de bitola menor, mas os caminhos de alimentação da bateria e dos LEDs devem ser dimensionados de acordo com a corrente esperada.

4. Ambiente de desenvolvimento

4.1 Software necessário

  • Arduino IDE
  • Plugin do Arduino para ProffieBoard
  • Pacote de código-fonte do ProffieOS
  • Drivers USB, quando necessários
  • Editor de texto simples ou editor de código para editar a configuração

4.2 Seleção da placa no Arduino

Para o ProffieBoard V2, selecione o alvo de placa correspondente:


Tools → Board → Proffieboard V2
Configuração do Arduino Valor recomendado
Placa Proffieboard V2
USB Type Serial + WebUSB + Mass Storage, quando compatível
DOSFS SDCARD (SPI)
CPU Speed 80 MHz
Optimize Smallest Code, Fast, Faster ou Fastest, dependendo da configuração e dos requisitos de recursos
Port Porta COM da placa conectada

5. Instalação do ProffieOS

5.1 Obter o ProffieOS

Para garantir uma configuração e compilação de firmware estáveis nos sabres SUPERNEOX, utilize o ProffieOS 5.9. Após o download, extraia os arquivos do código-fonte do ProffieOS para uma pasta de usuário com permissão de escrita, como Documentos ou Área de Trabalho. Evite armazenar o código-fonte em locais protegidos, como Program Files ou outros diretórios gerenciados pelo sistema, pois as permissões do Windows podem restringir o acesso aos arquivos e causar problemas durante a compilação.

A árvore de código-fonte contém o sketch principal do Arduino:


ProffieOS/ProffieOS.ino

Alguns diretórios comuns incluem:


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

5.2 Abrir o sketch do Arduino

Abra:


ProffieOS/ProffieOS.ino

5.3 Usar o configurador V2

A documentação oficial do ProffieOS recomenda utilizar o configurador correspondente à versão específica do ProffieBoard. Para sabres SUPERNEOX equipados com ProffieBoard V2.x, utilize o seguinte configurador: Configurador do ProffieBoard V2.x

Configure o código gerado de acordo com a fiação real do sabre, os componentes de hardware instalados e os recursos disponíveis. O configurador oferece um ponto de partida confiável, mas configurações avançadas ou personalizadas podem exigir edições manuais adicionais após a geração do código.

6. Criar e selecionar um arquivo de configuração

6.1 Criar o arquivo de configuração

  1. Abra o diretório config/ do ProffieOS.
  2. Copie um modelo de configuração existente.
  3. Renomeie o arquivo usando um nome descritivo.
  4. Edite a configuração usando um editor de texto simples.
  5. Salve o arquivo.
Não use o Microsoft Word. Os arquivos de configuração são código-fonte e devem permanecer em formato de texto simples.

6.2 Selecionar a configuração com CONFIG_FILE

Abra o ProffieOS.ino e habilite exatamente um arquivo de configuração:


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

#define CONFIG_FILE "config/my_saber_config.h"

Todas as definições de configuração que não estiverem em uso devem permanecer comentadas.

7. Entendendo as seções de configuração

Um arquivo de configuração do ProffieOS contém diversas seções processadas durante a compilação.

CONFIG_TOP

Definições globais de hardware, ativação de recursos, quantidade de lâminas, botões, áudio, movimento e suporte ao cartão SD.

CONFIG_STYLES

Disponível no ProffieOS 7.x e versões posteriores. Armazena modelos de estilos reutilizáveis e aliases.

CONFIG_PRESETS

Define presets, sound fonts, faixas de áudio, styles e nomes dos presets.

CONFIG_PROP

Define o comportamento do prop e os controles personalizados.

8. Principais parâmetros de configuração


#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
Parâmetro Função
NUM_BLADES Número de definições de lâmina.
NUM_BUTTONS Quantidade de botões físicos configurados.
VOLUME Nível de volume padrão.
maxLedsPerStrip Número máximo de LEDs.
CLASH_THRESHOLD_G Limite de detecção de impacto. Valores menores geralmente tornam a detecção de impacto mais sensível.
ENABLE_AUDIO Ativa as funções de áudio.
ENABLE_MOTION Ativa o sensor de movimento.
ENABLE_WS2811 Ativa a funcionalidade WS2811/LED endereçável utilizada em configurações NeoPixel comuns.
ENABLE_SD Ativa o suporte ao cartão SD.
SAVE_STATE Ativa a persistência de estado para configurações compatíveis.

9. Configuração da lâmina (* Observação: atualmente não compatível com os sabres SUPERNEOX.)

A configuração da lâmina define o hardware físico de LEDs, a detecção da lâmina e seu comportamento lógico.

9.1 Exemplo de lâmina única


BladeConfig blades[] = {

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

};

O primeiro valor corresponde à resistência do Blade ID utilizada para a detecção da lâmina. O valor 0 é normalmente utilizado quando não é necessária uma seleção baseada no Blade ID.

9.2 Configurações com múltiplas lâminas

Várias entradas de BladeConfig permitem selecionar diferentes configurações físicas por meio da identificação da lâmina.

9.3 SubBlade

O SubBlade permite dividir LEDs endereçáveis em várias zonas lógicas, como crossguards, câmaras de cristal e pixels auxiliares.

10. Configuração de presets

Um preset combina:

  • Sound font
  • Faixa de áudio
  • Blade Style
  • Nome do preset

Preset presets[] = {

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

};
Campo Significado
Sound font Diretório que contém os arquivos de som.
Track Caminho do arquivo de música.
Style Comportamento visual da lâmina.
Name Nome exibido para o preset.

11. Cartão SD e gerenciamento de Sound Fonts

O cartão microSD armazena os recursos utilizados pelo ProffieOS durante a execução, incluindo sound fonts, faixas de áudio, arquivos de configuração e recursos opcionais de display.

11.1 Estrutura recomendada do cartão SD


CARTÃO SD

├── SOUND/
│
├── TRACKS/
│
├── CONFIG/
│
├── DIRETÓRIO DE FONT 1/
│   ├── hum.wav
│   ├── swingl.wav
│   ├── swingh.wav
│   ├── clash.wav
│   └── blst.wav
│
└── DIRETÓRIO DE FONT 2/

11.2 Diretório da Sound Font

Cada sound font é armazenada em um diretório próprio. O nome desse diretório é referenciado pela configuração do preset.

Exemplo:


Preset presets[] = {

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

};
Os nomes dos arquivos são importantes. O ProffieOS procura nomes específicos para os arquivos de som. Nomes incorretos ou arquivos ausentes podem resultar em ausência de áudio ou efeitos que não funcionam corretamente.

12. Botões e Props

Os botões determinam a interação do usuário. O sistema de props interpreta as combinações de botões e as converte em ações do sabre.

12.1 Ações comuns

Ação Entrada típica
Ignição Pressionamento curto do botão Power/Ativação.
Retração da lâmina Pressionamento curto do botão Power/Ativação enquanto a lâmina está acesa.
Ignição silenciosa Dois cliques no botão Power.
Próximo preset Lâmina apagada: pressionamento curto do botão AUX.
Preset anterior Mantenha AUX pressionado e pressione Power.
Clash Golpeie a lâmina enquanto ela estiver acesa.
Lockup Mantenha Power pressionado e, em seguida, acione um clash.
Drag Use o gesto de Lockup enquanto aponta o sabre para baixo.
Efeito Force Pressionamento longo do botão AUX.
Blaster Block Pressionamento curto de AUX enquanto a lâmina está acesa.
Alteração de cor Mantenha AUX pressionado e pressione rapidamente Power; em seguida, gire o punho.
Controle de volume / menu Pressionamentos longos e combinações de botões para acessar configurações e ajustes.

O comportamento exato é determinado pelo prop selecionado e pela configuração dos botões. O ProffieOS inclui vários props para sabres, incluindo implementações padrão e avançadas de botões e recursos. Não presuma que todos os props atuais utilizem o mesmo mapa de botões.

12.2 Configuração do Prop

O prop selecionado define:

  • Tempo de acionamento dos botões
  • Interpretação de gestos
  • Comportamento dos menus
  • Funções especiais

#include "props/saber.h"

Props personalizados podem ser criados para hardware especializado ou controles específicos de determinado produto.

13. Depuração com o Monitor Serial

O manual fornecido documenta os seguintes comandos de uso comum:

Comando Função
battery_voltage Lê a tensão da bateria.
get_volume Lê o volume atual.
pow Alterna o estado de alimentação.
on Liga o sabre.
off Desliga o sabre.
set_volume 500 Define o volume.
play Reproduz/interrompe a faixa padrão.
force Aciona o som de Force.
drag Aciona o som de Drag.
blast Aciona o som de Blaster.

13.1 Ativar a saída Serial


#define ENABLE_SERIAL

13.2 Informações de depuração comuns

  • Mensagens de inicialização
  • Detecção do cartão SD
  • Inicialização da lâmina
  • Carregamento de presets
  • Status do sensor de movimento
  • Eventos dos botões
Fluxo de trabalho recomendado: Ao diagnosticar um sabre destinado à produção, capture o log completo de inicialização via Serial antes de alterar as configurações do firmware.

14. Blade Styles

Blade Styles são o principal mecanismo utilizado pelo ProffieOS para definir o comportamento visual da lâmina. Eles controlam cor, animações, ignição, retração, resposta a clashes, efeitos de blaster, lockup, drag, transições e outros efeitos interativos.

14.1 Exemplo básico de Style


StyleNormalPtr<RED>()

Styles básicos definem a aparência padrão da lâmina. Configurações mais avançadas utilizam funções aninhadas de estilo e camadas de efeitos para criar animações complexas.

14.2 Estrutura do StylePtr


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

StylePtr é normalmente utilizado para atribuir um Blade Style completo. Efeitos complexos são criados combinando várias funções, camadas e transições.

14.3 Cores RGB


Rgb<255, 50, 0>

Os valores de cada canal RGB variam de 0 a 255. Cores nomeadas como RED, GREEN, BLUE, WHITE e CYAN também podem ser utilizadas quando houver suporte.

14.4 Funções de efeitos comuns

Função Descrição
InOutHelper<base, extension, retraction, offColor> Controla o tempo de extensão e retração da lâmina, incluindo a cor quando ela está apagada.
AudioFlicker<A, B> Cria uma oscilação de brilho responsiva ao áudio entre duas cores para simular instabilidade de energia.
OnSpark<base, spark, duration> Adiciona um efeito de faísca durante a ignição da lâmina.
SimpleClash<base, clash, duration> Cria um efeito de flash quando a lâmina detecta um impacto.
Lockup<base, lockup> Define o comportamento contínuo de Lockup e a resposta de cor durante o efeito.
Blast<base, blast> Define os efeitos de flash de deflexão de disparos e suas respectivas cores.

14.5 Composição avançada de Styles

Usuários avançados podem combinar funções, camadas, transições e efeitos aleatórios para criar comportamentos totalmente personalizados para a lâmina.


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

14.6 Múltiplas lâminas / Pixels auxiliares

Um preset pode conter vários Blade Styles correspondentes a múltiplas definições lógicas de lâmina. Isso permite configurar estilos independentes para a lâmina principal, quillons, câmaras de cristal, faixas de LEDs auxiliares ou outros grupos de pixels configurados.

14.7 Recursos para edição de Styles

15. Integração avançada

15.1 Displays

Módulos de display compatíveis podem fornecer:

  • Informações da bateria
  • Seleção de presets
  • Navegação pelos menus
  • Status durante a execução

15.2 Periféricos adicionais

Configurações avançadas podem integrar:

  • LEDs auxiliares
  • Câmaras de cristal
  • Iluminação de crossguard
  • Sensores personalizados
  • Controladores externos

15.3 Fluxo de trabalho recomendado para produção

  1. Congele a revisão do hardware.
  2. Arquive o diagrama da fiação.
  3. Arquive a versão do ProffieOS.
  4. Arquive o arquivo de configuração.
  5. Arquive o conteúdo do cartão SD.
  6. Teste o firmware em hardware representativo.
  7. Libere o pacote final para produção.

16. Solução de problemas

Problema Possível causa Solução
Placa não detectada Problema no driver, cabo USB, bootloader ou porta. Verifique a conexão USB, os drivers e a seleção da porta no Arduino.
Falha na compilação Versão incorreta do ProffieOS, configuração ausente ou erro de sintaxe. Verifique o CONFIG_FILE, a seleção da placa e a sintaxe da configuração.
Sem som Arquivos ausentes no cartão SD, diretório de font incorreto ou configuração de volume. Verifique a estrutura do cartão SD, os nomes das sound fonts e a configuração de áudio.
A lâmina não acende Configuração incorreta da lâmina ou problema na fiação. Verifique o BladeConfig, a conexão dos dados dos LEDs e o caminho de alimentação.
Efeitos de movimento indisponíveis Suporte a movimento desativado ou problema no sensor. Verifique ENABLE_MOTION e a conexão do hardware.
Antes de fazer um novo flash: Sempre salve a configuração funcional e faça um backup do cartão SD. Uma atualização do firmware pode substituir comportamentos personalizados.

17. Referências para desenvolvedores

Nota de engenharia: Para o desenvolvimento de sabres destinados à produção, mantenha o firmware, as configurações, as revisões de hardware e os arquivos do cartão SD sob controle de versão e arquivados em conjunto.

Observação:
ProffieBoard e ProffieOS são projetos de código aberto. Este documento é uma referência técnica compilada a partir do manual fornecido e da documentação pública do ProffieOS. Ele não é um documento oficial do projeto ProffieOS.
Sempre valide as versões destinadas à produção de acordo com a versão exata do ProffieOS e a revisão de hardware que será utilizada.