Ioruba / docs

Precision control for tactile audio workflows

pt-BR

Inicio Rapido

Editar no GitHub English hub

Inicio Rapido

Este e o caminho mais rapido de um clone limpo para uma sessao Ioruba funcionando na stack Linux ativa.

Atencao O controle real de audio do sistema atualmente depende do backend Linux com pactl. No macOS e Windows, o shell desktop ainda e util para revisao de UI e modo demo, mas o controle de audio ainda nao foi implementado.

1. O que voce precisa

Software

  • Node.js 22 recomendado (mesma major usada na CI)
  • npm
  • Rust stable + Cargo
  • arduino-cli
  • pactl disponivel no PATH

Hardware

  • Arduino Nano ATmega328P
  • 3 potenciometros lineares de 10k
  • cabo USB de dados
  • fios jumper e protoboard ou case

Check rapido de versao:

node --version
npm --version
rustc --version
cargo --version
arduino-cli version
pactl info

2. Instalar dependencias do repositorio

npm install

3. Preparar permissoes seriais no Linux

Dependendo da distro, adicione seu usuario em dialout ou uucp:

sudo usermod -a -G dialout $USER
sudo usermod -a -G uucp $USER

Saia da sessao e entre novamente apos mudar grupos.

4. Ligar e gravar o controlador

Se voce ainda precisa montar o hardware, comece por:

Detecte a placa:

arduino-cli board list

Compile o firmware atual:

arduino-cli compile --fqbn arduino:avr:nano firmware/arduino/ioruba-controller

Upload para Nano padrao:

arduino-cli upload -p /dev/ttyUSB0 --fqbn arduino:avr:nano firmware/arduino/ioruba-controller

Upload para clones comuns de Nano com old bootloader:

arduino-cli upload -p /dev/ttyUSB0 --fqbn arduino:avr:nano:cpu=atmega328old firmware/arduino/ioruba-controller

5. Validar o repositorio

Rode os checks automatizados principais antes de subir o shell desktop:

npm run verify

Se voce so quiser garantir que o firmware ainda compila pela raiz:

npm run firmware:compile

6. Iniciar o app desktop

Somente frontend:

npm run desktop:dev

Shell desktop Tauri completo:

npm run desktop:watch

Use o shell Tauri para sessoes seriais reais, persistencia e validacao de backend.

7. Confirmar que esta tudo funcionando

Quando o app abrir, o fluxo esperado e:

  • o app descobre portas seriais ou respeita sua porta preferida
  • o card de status passa pelos estados de conexao em vez de ficar parado
  • o runtime recebe handshake de firmware antes ou junto dos frames de knob
  • a aba Watch mostra frames como 512 768 1023
  • o grafico de telemetria reage quando voce gira os knobs
  • o perfil ativo e salvo como JSON e sobrevive a reinicios
  • Atualizar audio atualiza o inventario de audio Linux
  • girar os knobs atualiza alvos como master, apps ou entrada de microfone

Mapeamento do perfil padrao:

Knob Alvo padrao
1 Saida padrao / volume master
2 Spotify, Google Chrome, Firefox
3 default_microphone

8. Onde o app salva dados

O app desktop persiste dois arquivos importantes:

  • ioruba-state.json - perfil ativo e estado de runtime
  • ioruba-watch.log - eventos estruturados da watch, com trim automatico para cerca de 1 MiB

Locais:

  • Linux: ~/.config/io.ioruba.desktop/
  • macOS: ~/Library/Application Support/io.ioruba.desktop/
  • Windows: %APPDATA%\io.ioruba.desktop\

9. Build local do app desktop

Para build local Tauri sem instaladores finais:

npm run desktop:tauri:build

Se voce mudar o source do icone em apps/desktop/src-tauri/icons/app-icon.svg, regenere todos os assets derivados antes:

npm run desktop:icons

10. Solucao rapida de problemas

Tauri falha para compilar no Linux

Instale os pacotes de desenvolvimento WebKit/GTK exigidos pelo Tauri:

sudo pacman -S --needed \
  webkit2gtk-4.1 \
  gtk3 \
  librsvg \
  appmenu-gtk-module \
  libappindicator-gtk3 \
  xdotool

No Arch, o caminho de tray depende de libappindicator-gtk3. Isso bate com os prerequisitos Linux atuais do Tauri 2.

11. Smoke test como usuario final no Arch

Tente gerar um artefato Linux instalavel pela raiz do repositorio:

npm --workspace @ioruba/desktop run tauri build -- --bundles appimage

O AppImage fica em:

apps/desktop/src-tauri/target/release/bundle/appimage/

Execute como um usuario final faria:

./apps/desktop/src-tauri/target/release/bundle/appimage/Ioruba_*.AppImage

O que verificar:

  • o app abre normalmente fora do tauri dev
  • fechar a janela principal nao mata o processo
  • o app continua disponivel no tray
  • clique esquerdo ou a acao Abrir Ioruba no tray restaura a janela
  • Sair pelo tray realmente encerra o processo
  • persistencia, conexao serial e Atualizar audio continuam iguais

Limitacao conhecida em hosts Arch atuais:

  • o passo de bundling AppImage ainda pode falhar dentro do linuxdeploy porque o strip embutido nao entende libs novas do Arch com .relr.dyn
  • quando isso acontecer, trate o binario de release em apps/desktop/src-tauri/target/release/ioruba-desktop como alvo local de smoke test para tray/background
  • para artefatos AppImage publicos, prefira build em CI ou em imagem Linux mais antiga em vez de um Arch bleeding-edge

O app abre mas nenhum pacote chega

  • confirme que a placa esta com o sketch atual
  • confirme que a placa responde com HELLO board=…; fw=…; protocol=…; knobs=…
  • confirme que a placa esta enviando 512 768 1023
  • confirme 9600 baud
  • confira a ligacao dos knobs em A0, A1 e A2
  • verifique a porta serial selecionada no app
  • tente o perfil old bootloader se voce usa clone

Alvos de audio nao se movem

  • confirme que pactl info funciona
  • garanta que apps alvo estao reproduzindo audio
  • atualize o inventario pelo app desktop
  • inspecione o perfil JSON na aba Config

Voce esta em macOS ou Windows

Esse caminho hoje deve ser tratado como validacao parcial de UI/demo. O shell desktop pode compilar e abrir, mas o backend real de audio esta explicitamente sem suporte fora do Linux.

Leituras seguintes