agentleFS
argeuthiesenargeuthiesen/claudinho/skills/configurar/SKILL.md

configurar

Skill21 starsChanged 5 days agoMITView on GitHub

Configura o Claudinho (mascote do Claude Code: placa única E32R28T, ESP32 + display Nextion, ou o Claudinho virtual no navegador, sem placa) do zero ou depois de trocar de rede - acha a placa no USB, grava o firmware, configura o Wi-Fi, grava a tela do Nextion (versão clássica), liga a status line e testa. Use também para diagnosticar quando o Claudinho não reage, para atualizar o firmware e para ligar uma impressora 3D Bambu Lab (painel e alertas da impressão).

6 other projects use a version of this.

Adopted by

Most recently taken up by

The file

Files
SKILL.md

Configurar o Claudinho

Você vai conduzir a pessoa pela configuração, rodando os scripts do plugin. Fale em linguagem simples, um passo por vez, e diga o que está fazendo antes de cada comando. Nunca peça a senha do Wi-Fi no chat: ela é digitada pela pessoa num terminal, escondida, pelo wifi.sh (passo 4), e não passa pela conversa. O mesmo vale para o código de acesso da impressora Bambu (seção própria): digitado escondido pela pessoa, gravado só na placa.

Em todo comando, use estas variáveis (já resolvidas pelo Claude Code):

export R="${CLAUDE_PLUGIN_ROOT}"; export CLAUDINHO_DADOS="${CLAUDE_PLUGIN_DATA}"

Os scripts funcionam em Linux, macOS, WSL e Windows (Git Bash). No WSL e no Windows a porta USB é do Windows (ex.: COM6) e o esptool.exe é usado automaticamente. bash "$R/scripts/comum.sh" não imprime nada; para saber o ambiente: bash -c 'source "$R/scripts/comum.sh"; ambiente'.

Antes de tudo: o ambiente foi testado?

Confira o ambiente (ambiente do comum.sh) e a placa contra esta lista.

Testado de ponta a ponta (tudo funciona):

  • WSL2 no Windows 11, ESP32-C3 Super Mini, Nextion NX3224F024_011.

Escrito para funcionar, mas ainda sem teste real:

  • Linux nativo, macOS (Intel e Apple), Windows com Git Bash.
  • ESP32-S3 DevKitC-1 (o firmware compila, o fluxo é o mesmo).
  • Qualquer outro modelo de Nextion (a tela incluída é só para o NX3224F024).

Se o ambiente ou a placa não estiver na lista testada, diga isso à pessoa antes do passo 1, em uma frase, e combine o jeito de trabalhar:

  1. Rode um passo por vez e confira a saída antes do próximo (não confie no código de saída sozinho): porta encontrada, Hash of data verified, CFG OK, "wifi":"conectado", ok, reiniciando.
  2. Se um script falhar, não repita às cegas. Leia o erro, descubra a causa no ambiente dela (nome da porta, permissão, ferramenta faltando, stty diferente, PowerShell ausente) e proponha a correção. Se precisar, escreva uma versão ajustada do script para o caso dela e explique o que mudou.
  3. Peça à pessoa para agir só no que exige mãos (trocar cabo, apertar BOOT, dar permissão, instalar algo com senha de administrador).
  4. Ao final, sugira que ela conte o que precisou mudar (issue no repositório), para o ambiente entrar na lista de testados.

Nunca afirme que algo funcionou sem ter visto a confirmação correspondente.

Como funcionam as atualizações

  • Primeira gravação: sempre pelo USB (passo 3). A placa nova não tem Wi-Fi configurado nem o servidor HTTP do Claudinho.
  • Depois: pela rede (OTA), com claudinho.sh atualizar. O PC envia o firmware por HTTP direto para a placa (POST /ota, com o segredo). Nada de servidor ou nuvem. Leva ~20 s e a placa reinicia sozinha.
  • Precisa de alguém na frente do Claudinho (firmware 1.0.9 em diante): o script pede, a tela mostra "Toque na tela para permitir" e a pessoa tem 1 minuto para tocar (ou apertar BOOT na placa). Avise antes de rodar atualizar ou tela. Sem o toque nada é enviado. Isso impede que alguém que descubra o segredo na rede grave outro firmware de longe.
  • É seguro: o ESP32 grava o firmware novo na partição reserva e só troca se a gravação terminar e for validada. Se a rede cair no meio, continua rodando o firmware antigo; basta repetir.
  • A tela do Nextion também vai pela rede (claudinho.sh tela), passando pelo ESP32. Se falhar no meio aparece "System Data Error": repita, não estraga.
  • Quando o OTA não é possível: placa fora da rede, IP mudou (rode esta skill de novo para achar o IP pelo USB), segredo diferente (reconfigure pelo passo 4), ou firmware anterior a 1.0.0 (grave pelo USB). Nesses casos, volte ao USB.
  • Firmware de outra fonte pode tirar o OTA; se a pessoa gravar outro programa na placa, a volta é sempre pelo USB (passo 3).

Pasta do projeto: LittleClaude

A configuração deve ser feita numa pasta só dela, chamada LittleClaude (ex.: ~/LittleClaude no Linux/macOS/WSL, C:\Users\<nome>\LittleClaude no Windows). Assim o que for feito para o Claudinho (arquivos, anotações, testes) fica junto e não se mistura com outros projetos.

Se o diretório de trabalho desta sessão não se chamar LittleClaude, antes do passo 0 oriente a pessoa, em poucas palavras, a criar a pasta, sair do Claude Code e abri-lo de novo dentro dela (mkdir ~/LittleClaude && cd ~/LittleClaude && claude), e então pedir a configuração de novo. Se ela preferir seguir onde está, siga; não é obrigatório.

0. Já está configurado?

bash "$R/scripts/claudinho.sh" info

Se responder um JSON com "versao":"virtual", é o Claudinho virtual (seção própria, no fim). Se responder um JSON com "versao", o Claudinho está na rede: pule para o que a pessoa pediu (diagnóstico → passo 7; atualizar → claudinho.sh atualizar; trocar tela → passo 5). Se disser "ainda não configurado" ou não responder, siga do passo 1.

1. Hardware

Existem duas versões. Pergunte qual a pessoa tem. Se ela ainda não tem placa (ou quer ver antes de comprar), ofereça o Claudinho virtual: o mesmo rosto numa aba do navegador, reagindo ao Claude Code dela de verdade. Vá para a seção "Claudinho virtual (sem placa)" e volte aqui quando a placa chegar.

  • E32R28T (placa única: ESP32 com tela de 2,8" embutida, da LCDWiki). Não tem fios para ligar: é só plugar no USB. Pule para o passo 2. Nessa placa não existe o passo 5 (tela do Nextion). O conversor USB dela é um CH340: no Windows, se a porta não aparecer, instale o driver do CH340. Abrir a porta USB reinicia a placa (é assim que ela grava sem botão): é normal a tela piscar.
  • Nextion + ESP32-C3 Super Mini (ou S3): a versão clássica, com fios.

Para a versão clássica, confirme as ligações (mostre a tabela se ela ainda não montou):

Fio do NextionESP32-C3 Super MiniESP32-S3 DevKitC-1
vermelho 5V5V5V
preto GNDGNDGND
azul TXpino RX (GPIO 20)GPIO 18
amarelo RXpino TX (GPIO 21)GPIO 17

Peça para ligar o ESP32 no computador com um cabo USB de dados (cabo só de carga não funciona).

Fonte depois de montado: ESP32 e Nextion juntos pedem uma fonte de 5 V de pelo menos 1 A; fonte fraca pode derrubar o Wi-Fi nos picos de consumo. Nunca ligar a fonte e o USB do PC ao mesmo tempo. Se atualizar ou tela falhar com resposta vazia: é Wi-Fi perdendo pacotes. Não estraga nada (a placa descarta o envio incompleto). Olhe o sinal no claudinho.sh log (linha wifi:), confira a fonte, e repita; se continuar, claudinho.sh reiniciar e tente de novo (a placa reconecta ao Wi-Fi).

2. Achar a placa

bash "$R/scripts/porta.sh"

Guarde a porta impressa (ex.: COM6, /dev/ttyACM0, /dev/cu.usbmodem101). Se falhar: trocar o cabo; segurar o botão BOOT enquanto pluga o USB e tentar de novo; no Linux, se der permissão negada, sudo usermod -aG dialout $USER e sair/entrar da sessão.

3. Gravar o firmware (~30 s)

bash "$R/scripts/gravar.sh" PORTA

Se sair PRECISA_BOOT, é o caso mais comum com placa que já tinha outro programa (visto em teste real): peça para segurar BOOT, tirar e pôr o USB, soltar BOOT, e rode de novo. A porta pode mudar de número; rode o passo 2 de novo.

Espere ver Hash of data verified. O script reconhece sozinho a placa (C3, S3 ou E32R28T) e grava o firmware certo. Isso apaga qualquer configuração anterior da placa. O display vai mostrar "Olá! Sou o Claudinho." (ou lixo, se o Nextion ainda tiver a tela de fábrica — normal, o passo 5 resolve).

4. Wi-Fi e segredo

Liste as redes que a placa enxerga (só 2,4 GHz):

bash "$R/scripts/serial.sh" PORTA SCAN REDE "SCAN FIM" 40

Pergunte só o nome da rede. A senha a pessoa digita ela mesma, num terminal, sem aparecer: assim ela não passa pela conversa e fica gravada só na placa. Monte o comando com o caminho real (resolva $R e $CLAUDINHO_DADOS antes de mostrar) e peça para a pessoa abrir um terminal fora do Claude Code (no Windows, o mesmo tipo de terminal em que o Claude Code roda: WSL ou Git Bash) e rodar:

CLAUDINHO_DADOS="<dados>" bash "<R>/scripts/wifi.sh" PORTA "NOME DA REDE"

O script pede a senha escondida, gera o segredo do PC, envia pela USB, espera a placa entrar no Wi-Fi e grava IP, segredo e MAC no computador. Ele termina com Pronto!, o IP e o MAC; peça para a pessoa avisar quando aparecer (ou colar o erro). Se disser que não entrou no Wi-Fi: senha errada ou rede de 5 GHz, e é só rodar de novo. Confira do seu lado com bash "$R/scripts/claudinho.sh" info.

Se a pessoa não tiver como abrir outro terminal e fizer questão de passar a senha pelo chat, avise uma vez que ela ficará registrada na conversa, e só então rode você mesmo, passando a senha pela entrada padrão: printf '%s\n' 'SENHA' | bash "$R/scripts/wifi.sh" PORTA "NOME DA REDE".

Diga à pessoa o MAC e o IP e recomende reservar esse IP no roteador (DHCP estático); se o IP mudar, o Claudinho para de reagir até rodar esta skill de novo.

Idioma da tela (logo depois do Wi-Fi)

Os textos da tela do Claudinho existem em vários idiomas (inglês é o padrão de fábrica). Não pergunte do zero: você já sabe o idioma em que a pessoa está conversando. Veja os disponíveis com bash "$R/scripts/claudinho.sh" idioma (mostra o atual e a lista, como en,pt-BR) e proponha o da conversa, por exemplo: "Vi que você está falando português; deixo a tela do Claudinho em português?". Com o sim (ou se a pessoa pedir outro da lista), grave:

bash "$R/scripts/claudinho.sh" idioma pt-BR

Se o idioma da pessoa ainda não existir, deixe em inglês e convide para traduzir: é só copiar idiomas/en.txt para o código do idioma e traduzir; o guia está em idiomas/TRANSLATING.md (em português: idiomas/TRANSLATING.pt-BR.md). O mesmo comando serve depois, quando a pessoa pedir "muda o idioma do Claudinho". As palavras que dão humor ao prompt (português e inglês) não dependem disso.

5. Tela do Nextion (~40 s, pela rede)

Só na versão clássica. Na E32R28T não existe esse passo (o próprio ESP32 desenha a tela, com as fontes dentro do firmware): pule para o 6.

O plugin traz a tela pronta para o NX3224F024 (Discovery 2,4"). A imagem é feita para a tela girada 270, que é a única montagem possível: a área útil do Nextion não fica no centro da placa, e só nessa posição ela fica centralizada na caixa. Não existe versão para outra orientação.

Avise que vai pedir um toque na tela e rode:

bash "$R/scripts/claudinho.sh" tela

A tela mostra "Toque na tela para permitir"; depois do toque, responde ok, reiniciando. Se o Nextion mostrar "System Data Error", repita o comando (é upload incompleto, não estraga nada). Tela branca depois: claudinho.sh reiniciar.

6. Status line

Os hooks do plugin já estão ativos. A status line (que manda o uso do plano) o plugin não pode ligar sozinho; este script liga, com backup, e preserva uma status line que a pessoa já tenha:

python3 "$R/scripts/instalar-statusline.py" "$CLAUDINHO_DADOS"

Atalho no terminal (oferecer no fim)

Dentro do Claude Code, o comando claudinho já está no PATH (pasta bin/ do plugin). Ofereça criar o atalho para o terminal da pessoa, fora do Claude Code, e só crie se ela aceitar:

bash "$R/scripts/claudinho.sh" atalho

Cria ~/.local/bin/claudinho (acha sozinho a versão mais nova do plugin). Se avisar que ~/.local/bin não está no PATH, mostre a linha para o ~/.bashrc ou ~/.zshrc. Para tirar: claudinho.sh atalho remover.

7. Testar

bash "$R/scripts/claudinho.sh" cara prompt feliz
bash "$R/scripts/claudinho.sh" info

Pergunte se o Claudinho fez > < (olhos apertados de alegria). O info deve mostrar "local":true e os números do plano depois da próxima resposta. Para diagnóstico sem cabo: claudinho.sh log, ou o painel web (claudinho.sh web, abre no navegador o estado, os últimos eventos e os ajustes inofensivos; "abre o painel do Claudinho").

Mudar a cor do rosto

Quando a pessoa quiser trocar a cor (por exemplo, para combinar com o filamento), rode bash "$R/scripts/claudinho.sh" cor e explique o que vai aparecer na tela: 6 cores base; tocando numa, 12 tons dela numa moldura em volta da tela, com o tom tocado grande no centro. Com a tela montada, os tons da borda ficam colados na moldura impressa da caixa: diga que dá para comparar cada um direto com o filamento, lado a lado; tocando no centro, uma prévia do rosto com Gravar, Voltar (à moldura) ou Cancelar (volta à cor de antes). 1 minuto sem toque cancela. A cor gravada continua depois de reiniciar. Os olhos ficam sempre pretos. Quem souber a cor exata: claudinho.sh cor R G B salvar.

Jogo da velha

Quando a pessoa quiser jogar ("vamos jogar velha", "quero jogar com o Claudinho"), rode bash "$R/scripts/claudinho.sh" velha. É um passatempo que roda inteiro na placa: quem joga contra a pessoa é o próprio ESP32, sem gastar token. Explique em uma frase: ela é o X, toca nos quadrados; no fim o Claudinho reage (triste se ela ganhar, empolgado se ele ganhar) e começa outra partida sozinho; para sair, 3 toques rápidos no mesmo quadrado (ou 2 minutos sem tocar).

Genius

Quando a pessoa quiser jogar Genius (ou "o jogo das cores", "Simon"), rode bash "$R/scripts/claudinho.sh" genius. Também roda inteiro na placa, sem token. Explique em uma frase: o Claudinho acende uma sequência de cores e ela repete tocando; a cada acerto a sequência cresce uma cor; errou, ele mostra o placar e começa de novo; para sair, 3 toques rápidos no mesmo quadrante (ou 2 minutos sem tocar).

Impressora Bambu Lab (opcional)

Quando a pessoa disser que tem uma impressora Bambu ("tenho uma Bambu", "liga minha impressora no Claudinho"). Testado na P2S (com AMS). Outros modelos Bambu que aceitam conexão local (X1, P1, A1) devem funcionar, mas ainda não foram testados: diga isso à pessoa.

O Claudinho conecta direto na impressora, pela rede local (sem nuvem, sem servidor, sem token). Ele mostra:

  • um painel (modelo e estado, umidade e temperatura do AMS, 3 colunas: %, tempo restante e camada; barra na cor do filamento, temperaturas do bico, da mesa e da câmara, as 4 cores do AMS com a atual em destaque). Imprimindo, aparece sozinho a cada 5 minutos por 15 s. No cartão de consumo e no painel há botões embaixo: Tokens | Impressora | Manter (a tela fica ligada; o botão vira Dormir, que volta ao rosto). Bom para usar o Claudinho como monitor portátil da impressora. O nome da impressão não aparece: pela rede local só vem "projeto + placa" ou o perfil do MakerWorld;
  • alertas; os importantes ficam na tela até um toque (o toque quer dizer "li"): começou, pausou (com o motivo: acabou o filamento, bico entupido, erro na 1ª camada...), retomou, faltam 5 min, trocou o filamento, terminou (com a duração), falhou/cancelada, avisos HMS da impressora e AMS úmido (≥ 50 %). Os de andamento (começou, retomou, faltam 5 min, trocou o filamento) saem sozinhos em 20 s, e um alerta novo da impressão tira da fila os de andamento que ficaram velhos (e a pausa que voltou ou acabou). Voltou a imprimir = problema resolvido: pausa, avisos HMS e o fim da impressão anterior saem da fila sem toque. Aviso HMS que chega com a impressora imprimindo sai sozinho, o que a impressora tira da lista sai da fila, e código sem descrição da Bambu no nível "aviso" vai só pro log. Em jogo, paleta ou atualização, os alertas esperam a volta ao rosto. Os avisos HMS aparecem em português (categoria + frase curta + código pequeno), com a lista oficial da Bambu embutida; os informativos (sem internet, relógio, câmera ao vivo...) saem sozinhos em 20 s e não se repetem por 30 min. claudinho.sh alerta bom|ruim|filamento|hms mostra um exemplo.

Passos:

  1. Na impressora, em Configurações > Rede (WLAN), anote o IP e o código de acesso (8 caracteres). Se a conexão for recusada, ligue o modo LAN (e o modo desenvolvedor, conforme o firmware da impressora). Recomende reservar o IP da impressora no roteador.
  2. O código de acesso é um segredo, como a senha do Wi-Fi: nunca peça no chat. Monte o comando com o caminho real (resolva $R e $CLAUDINHO_DADOS) e peça para a pessoa rodar num terminal fora do Claude Code:

    CLAUDINHO_DADOS="<dados>" bash "<R>/scripts/claudinho.sh" bambu IP_DA_IMPRESSORA

    O script pede o código escondido e envia para a placa, que grava na memória dela. O computador não guarda o código.

  3. Confira do seu lado com bash "$R/scripts/claudinho.sh" log: deve aparecer bambu: conectado e bambu: impressora <número de série>. Se aparecer codigo de acesso recusado, o código está errado ou falta ligar o modo LAN; é só rodar o passo 2 de novo. Se nada aparecer, confira o IP (a impressora tem de estar ligada e na mesma rede).
  4. claudinho.sh painel mostra o painel na hora (bom para testar).

Se a pessoa fizer questão de passar o código pelo chat, avise uma vez que ele ficará registrado na conversa, e só então rode você mesmo, pela entrada padrão: printf '%s\n' 'CODIGO' | bash "$R/scripts/claudinho.sh" bambu IP. Para desligar (apaga o código da placa): claudinho.sh bambu desligar.

O código vai do computador para a placa pela rede local, junto com o segredo do Claudinho (como os outros comandos): protegido contra quem não tem o segredo, mas sem criptografia na rede de casa.

Cenas

Enquanto o Claude usa ferramentas, a tela mostra uma cena em vez da cara de trabalhando: editor de código (editar arquivo), terminal (comandos), chuva do Matrix (ler/procurar), organograma (subagentes) e conversa (o Claude pedindo uma segunda opinião a outra IA, como o plugin do Codex), com um mini Claudinho no canto. É tudo de mentira: o hook manda só a categoria, nunca arquivo ou comando. Se a pessoa perguntar, explique isso; para mostrar uma: claudinho.sh cena codando|terminal|lendo|agente|conversa. Embaixo da cena fica o letreiro: o resumo que o Claude escreve para cada comando e agente (a descrição que a pessoa vê ao aprovar) ou a tarefa em andamento da lista dele. Para testar: claudinho.sh cena terminal "texto"; para desligar, se a pessoa não quiser esse texto na tela: claudinho.sh letreiro desliga. As cenas usam a fonte 5 (JetBrains Mono) da tela: quem atualizar o firmware para 1.6 ou mais precisa também da tela nova (claudinho.sh tela, pede um toque).

Som e bateria (só E32R28T)

Na placa única, o Claudinho fala um idioma de robô gerado na hora (nunca gravado, nunca igual), conforme o humor. Comandos: claudinho.sh som desliga|liga, som volume N (10 a 200), som <humor> para ouvir (feliz, pergunta, sono, bravo, pronto, pensando, empolgado, preocupado, susto, trabalhando, desconfiado, zonzo, cansado, nervoso). A placa também aceita um som enviado pela rede no lugar do acordar/dormir (som envia acordar|dormir arq.wav, até ~5 s; som padrao volta ao gerado): é escolha de quem usa e nunca vai para o repositório. Bateria: ícone no cartão de consumo; claudinho.sh desligar põe a placa em sono profundo (BOOT acorda): sugira antes de a pessoa guardar o Claudinho por dias.

Modo demonstração

Quando a pessoa quiser filmar ou mostrar o Claudinho ("roda a demo", "modo demonstração"), rode bash "$R/scripts/claudinho.sh" demo: um passeio de ~2 min por tudo, sozinho, com dados de mentira (nada real é alterado; tudo volta como estava). Um toque na tela para; ou claudinho.sh demo parar. Usa o idioma da tela; para um vídeo em outro idioma, troque antes com claudinho.sh idioma.

Claudinho virtual (sem placa)

Para quem ainda não tem a placa: um servidorzinho local (Python, só em 127.0.0.1, nada sai do computador) faz o papel da placa e o navegador mostra o Claudinho em 3D (a caixa impressa, com a tela viva) ou só a tela. Reage aos mesmos eventos, sem gastar tokens. Ligue a status line (passo 6) e rode:

bash "$R/scripts/claudinho.sh" virtual

Ele abre o navegador sozinho (o endereço aparece na saída). Diga à pessoa que ele reage a partir da próxima ação do Claude, e que depois de reiniciar o computador é preciso rodar de novo (ou pedir "liga o Claudinho virtual"). Quando a placa chegar: claudinho.sh virtual parar e siga do passo 1; o wifi.sh grava o endereço da placa por cima.

O virtual ainda não conversa com a impressora Bambu (nem tem os jogos): se a pessoa pedir a impressora sem ter placa, explique que por enquanto isso é só na placa.

Quem só quer ver, sem instalar nada: a demonstração online, em https://argeuthiesen.github.io/claudinho/ (eventos de mentira).

Referência rápida

claudinho.sh info | log | cara <tipo> [humor] | cor [R G B [salvar]] | velha | genius | bambu IP|desligar | painel | idioma [código] | demo [parar] | som [humor|liga|desliga|volume N] | desligar | alerta [tipo] | cena <tipo> | reiniciar | consumo [s] | atualizar [bin] | tela [tft] | virtual [parar] | web | atalho [remover]

atualizar e tela pedem um toque na tela do Claudinho (avise a pessoa antes). Tipos de cara: inicio, prompt, ferramenta, erro, parou, atencao, compact, commit, teste_ok, teste_falhou, fim, dormir. Humor (com prompt): feliz, preocupado, susto.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.