Depuração e calibração dos servos SCS0009

A versão SCS0009 tem dois tipos de conteúdo de depuração:

1. Montagem TTL e depuração da posição central: cablagem, definição do ID dos servos, fixação dos braços dos servos, ajuste fino da posição central, execução de testes.
2. Ferramenta de depuração SCS0009: GUI em Python + PySide6, procura no barramento, leitura/escrita de todos os registos, controlo de posição, baudrate/repor de fábrica, backup da EEPROM em xdat.

Para detalhes do protocolo e dos registos, ver Mapa de memória de registos do SCS0009.
Para cablagem Arduino/expansão, ver Arduino Nano.

1. Depuração TTL: montagem, ID e posição central

Primeiro, descarregue o arquivo 灵巧手调试.zip; depois de o extrair, pode seguir o documento «Depuração da mão robótica com o programa Arduino (servos TTL)» para definir o ID dos servos, calibrar, ajustar a posição central e executar o programa de demonstração, ou consultar o código de código aberto oficial.

Com o produto acabado e sem desmontagem (o ID, a calibração e a posição central dos servos já vêm ajustados de fábrica), pode saltar diretamente para o ponto 6 — executar o "02 programa de demonstração" e para o seguimento de mãos.

1. Modo de cablagem para depurar a mão robótica

Uma opção é usar um PC para executar software de PC como Python, por exemplo o software de PC dos servos Feetech ou código Python.

Outra opção é usar um microcontrolador como o MEGA328P, ou uma placa de desenvolvimento ou controlador adquirido à parte.

O modo de cablagem é o seguinte:

(1) Cablagem ao depurar por Python (apenas a placa controladora dos servos):

(2) Cablagem ao depurar com a placa de desenvolvimento MEGA328P (placa controladora dos servos + placa de desenvolvimento 328P):

Verifique bem a posição dos pinos da placa de desenvolvimento MEGA328P!

A descrição seguinte refere-se ao processo de depuração com microcontrolador; o microcontrolador executa continuamente o programa de demonstração em ciclo, bastando desligar o cabo de dados para parar.

2. Definir o ID dos servos

Uma única mão robótica utiliza 8 servos; os IDs da mão direita devem ser definidos de 1 a 8 e os da mão esquerda de 11 a 18.

Calibração da posição central: de fábrica, mão direita [451,571,451,571,451,571,451,571], mão esquerda [571,451,571,451,571,451,571,451]

1. Ligação: ligue um único servo de cada vez à placa controladora dos servos.

2. Utilize o software de PC FD1.9.8.2 fornecido pelo fabricante dos servos para configurar.

FD.rar

3. Fixar o braço do servo

1. Carregue o programa "usado ao instalar o braço branco do servo" para a placa de desenvolvimento.

Função do programa: colocar a posição da engrenagem do servo numa posição aproximadamente central; os ângulos de movimento seguintes baseiam-se nesta posição intermédia.

(1) Instale o software Arduino; de acordo com o seu sistema, consulte o tutorial de instalação. Para compilar e descarregar o programa Arduino, é necessário primeiro instalar as bibliotecas FTServo e SCServo no Gestor de Bibliotecas.

(2) Tipo de placa de desenvolvimento: escolha "Arduino Nano".

2. Depurar os servos 1 e 2

(1) Editar: de acordo com o ID do servo a depurar, altere a posição abaixo. Por exemplo, para depurar o indicador, defina o ID como 1 e 2.

(2) Carregar o programa para a placa de desenvolvimento

(3) Ligação: ligue a placa de desenvolvimento à placa controladora dos servos e aos servos 1 e 2; ouve-se a engrenagem do servo rodar um certo ângulo e parar.

(4) Instale o braço do servo na engrenagem, mantendo-o o mais paralelo possível.

3. Depurar os servos 3 e 4

(1) Desligue a ligação entre a placa de desenvolvimento 328P e a placa controladora dos servos (caso contrário não é possível carregar)

(2) Editar: defina o ID como 3 e 4

(3) Carregar o programa para a placa de desenvolvimento

(4) Ligação: ligue a placa de desenvolvimento à placa controladora dos servos e aos servos 3 e 4; ouve-se a engrenagem do servo rodar um certo ângulo e parar.

(5) Instale o braço do servo na engrenagem, mantendo-o o mais paralelo possível.

4. Depurar os servos 5 e 6

Passos iguais aos anteriores

5. Depurar os servos 7 e 8

Passos iguais aos anteriores

4. Ajuste fino do valor intermédio

1. Carregue o programa "01 usado ao ajustar o valor MiddlePos" para a placa de desenvolvimento.

2. Quando o dedo estiver na posição fechada, pare imediatamente o programa (basta desligar o cabo de dados) e verifique se o braço do servo está corretamente alinhado (como na figura abaixo). Se não estiver alinhado, ajuste os valores MiddlePos_1 e MiddlePos_2 no programa até ficar alinhado. Registe este valor (8 servos correspondem a 8 valores), que será usado no programa final.

5. Executar o programa de teste

1. Preencha os valores MiddlePos_1 e MiddlePos_2 guardados acima no array abaixo e descarregue o programa.

6. Executar o "02 programa de demonstração"

(1) Instale o software Arduino; de acordo com o seu sistema, consulte o tutorial de instalação

(2) No diretório 灵巧手调试\00 TTL串口舵机\arduino程序（MEGA328P开发板）\02 演示程序, abra o ficheiro .ino correspondente à mão esquerda ou direita.

(3) Para compilar e carregar o programa Arduino para a placa de desenvolvimento, instale primeiro as bibliotecas FTServo e SCServo no Gestor de Bibliotecas.

(4) Tipo de placa de desenvolvimento: escolha "Arduino Nano".

(5) Compile e carregue.

Atenção: nesta altura, o PC está ligado apenas à placa de desenvolvimento, que ainda não está ligada à placa controladora dos servos (ou seja, não está ligada à mão robótica).

Após o carregamento ser bem-sucedido, ligue a placa de desenvolvimento à placa controladora dos servos com três cabos jumper; os servos ligam-se à placa controladora dos servos. Consulte Modo de cablagem ao depurar com a placa de desenvolvimento MEGA328P.

A mão robótica executa continuamente o "02 programa de demonstração".

O resultado é o seguinte:

---

2. Ferramenta de depuração SCS0009

Aplicável a Windows 10 / 11; para diferenças em Linux e macOS, ver secção 8. Este tutorial cobre cada passo, desde a instalação do ambiente até à depuração completa.

⚠️ Nota de compatibilidade: esta ferramenta suporta atualmente apenas servos Feetech SCS0009 (série SCS, feedback de posição por potenciómetro, resolução de 10 bits 0–1023). A tabela de registos e o formato dos parâmetros xdat foram concebidos especificamente para o Feetech SCS0009; não há garantia de compatibilidade com outras marcas/modelos.

1. Requisitos de ambiente

Dependência	Versão	Descrição
Python	>= 3.8	Recomenda-se 3.10+, descarregue de python.org
PySide6	>= 6.0	Framework da GUI
pyserial	>= 3.5	Comunicação série
Sistema	Win10 / Win11	Qualquer versão

2. Instalar o Python

1. Aceda a https://www.python.org/downloads/
2. Descarregue o instalador do Python 3.10+
3. Durante a instalação, marque obrigatoriamente "Add Python to PATH" (caso contrário, a linha de comandos não encontra o python)

Verificar a instalação:

python --version

3. Instalar as dependências

Recomenda-se instalar num ambiente virtual, para não contaminar o Python do sistema:

# entrar no diretório do projeto
cd SCS0009_ServoController

# criar o ambiente virtual
python -m venv .venv

# ativar o ambiente virtual (Windows)
.venv\Scripts\activate

# instalar as dependências
pip install -r requirements.txt

⚠️ O ambiente virtual só precisa de ser criado uma vez. Executar novamente substitui o ambiente original (apaga as dependências instaladas). A partir daí, basta activate para ativar.

Dica: após a ativação, aparece o prefixo (.venv) na linha de comandos.

4. Verificar o ambiente

python setup.py

Quando aparecer [OK] 环境检查通过，可以运行项目, o ambiente está correto.

5. Ligar o hardware

1. Ligue o adaptador USB-série (por exemplo CH340 / CP2102) ao computador
2. Ligue o controlador dos servos (placa de controlo do braço robótico)
3. Alimente os servos (recomenda-se DC 5V 5A; versão Pro DC 12V 5A)

Abra o Gestor de Dispositivos (Win+X → Gestor de Dispositivos) e confirme o número da porta:

端口 (COM 和 LPT)
  └─ USB-SERIAL CH340 (COM3)     ← a porta série dos seus servos

Anote o número COM para o selecionar ao iniciar o programa.

6. Iniciar a GUI

python -m src.gui.factory_calibration_tool

Ou especifique manualmente a porta (quando a porta série está ocupada):

python -m src.gui.factory_calibration_tool --port COM3

Ver as portas disponíveis:

python -m src.gui.factory_calibration_tool --list-ports

7. Fluxo de operação da interface

A interface tem um layout de painel único; quando a altura da janela é insuficiente aparece automaticamente uma barra de deslocamento, e ao maximizar adapta-se.

7.1 Ligação à porta série

• Escolha a porta e o baudrate (predefinido 1M) e clique em Ligar
• O estado mostra 🟢 Ligado

7.2 Procurar servos

• Clique em Procurar servos para detetar servos online com ID 1-254
• O resultado da procura aparece em tempo real na lista de servos (com o modelo)
• Clique numa linha da lista de servos → preenche automaticamente a lista pendente de servos

7.3 Leitura e escrita de parâmetros

• Ler parâmetros: lê todos os 44 registos (EEPROM + SRAM); o registo mostra os resultados em tempo real
• Tabela de parâmetros: apresentação em 5 colunas (endereço/registo/valor/área de armazenamento/leitura-escrita), com cores distintas para EPROM/SRAM/DEFAULT
• Seleção interligada: clique numa linha da tabela de parâmetros → preenche automaticamente "endereço de escrita", "comprimento" e "valor"
• Escrita: após alterar o valor, clique em escrever; o programa desbloqueia/escreve/bloqueia automaticamente
• Janela de resultado da escrita: em caso de sucesso aparece um aviso verde "✅ Escrita efetuada com sucesso"; em caso de falha, um aviso vermelho "❌ Falha na escrita" (com o motivo)

7.4 Alterar o ID do servo

1. Ligue apenas este servo cujo ID vai ser alterado ao barramento, para evitar conflitos com IDs existentes.
2. Na tabela de parâmetros, encontre e selecione a linha "ID do servo" (endereço 0x05).
3. Altere o "valor" para o ID pretendido e clique em ✏️ Escrever; o programa desbloqueia → escreve → volta a bloquear automaticamente.
4. Após a alteração, volte a procurar no barramento para confirmar. Mão direita 1–8, mão esquerda 11–18.

7.5 Controlo de posição

1. Arraste o slider ou introduza diretamente a posição alvo (0–1023); a caixa numérica e o slider estão sincronizados.
2. Clique em ▶ Mover; a barra de estado mostra "a mover…".
3. Ao chegar, aparece "movimento concluído, desligue o binário"; clique em ⏹ Desligar binário.

7.6 Baudrate/repor de fábrica

• Alterar o baudrate: escolha o novo baudrate (38400–1000000 bps) e escreva; o programa muda o baudrate da porta série e verifica com ping, revertendo automaticamente em caso de falha.
• Repor de fábrica: repõe os valores de fábrica (ID=1, baudrate 1M); depois é necessário voltar a procurar.

7.7 Parâmetros xdat (guarda apenas a EEPROM)

1. 💾 Guardar servo atual: guarda os parâmetros EEPROM do servo com o ID atual num ficheiro xdat (backup)
2. 📂 Abrir xdat: carrega o ficheiro de backup
3. 📤 Restaurar parâmetros no servo: escreve o backup de volta no servo

8. Diferenças entre Linux e macOS

Linux

• Tipos de letra: sudo apt install fonts-noto-cjk fonts-noto-color-emoji; caso contrário, a interface em chinês pode aparecer em branco e os emoji como quadrados.
• Permissões da porta série: sudo usermod -a -G dialout $USER; só tem efeito após terminar e reiniciar a sessão; groups deve incluir dialout. Temporariamente pode usar sudo chmod 666 /dev/ttyUSB0.
• Nome do dispositivo: /dev/ttyUSB* (CH340 / CP2102 / PL2303) ou /dev/ttyACM* (porta série USB integrada); use lsusb, dmesg | grep -i tty para ver o fabricante.
• Nome de dispositivo fixo (opcional): escreva SUBSYSTEM=="tty", ATTRS{idVendor}=="1a86", ATTRS{idProduct}=="7523", SYMLINK+="ttyServo" em /etc/udev/rules.d/99-servo.rules e depois use /dev/ttyServo.
• Arranque: python -m src.gui.factory_calibration_tool --port /dev/ttyUSB0.
• Problemas comuns: se o pip reportar externally-managed-environment, use um venv ou acrescente --break-system-packages.

macOS

• Python: recomenda-se instalar com Homebrew brew install python; não use a versão antiga do sistema.
• Nomes das portas série: use /dev/cu.*, não /dev/tty.* (este último pode bloquear); ls /dev/cu.* para ver.
• Driver USB: a maioria dos CH340 / CP2102 / FTDI não precisa de driver; lotes antigos de CH340 requerem o driver WCH; use system_profiler SPUSBDataType para diagnosticar.
• Arranque: python -m src.gui.factory_calibration_tool --port /dev/cu.usbserial-0001.
• Apple Silicon: use Python 3.10+ nativo, evitando Python antigo sob Rosetta; na primeira execução, se aparecer "não é possível verificar o programador", permita em "Privacidade e Segurança".
• Poupança de energia: a suspensão do macOS pode desligar a porta série; mantenha o sistema acordado durante a operação.

9. Notas

1. A escrita é persistente: após escrever os parâmetros na EEPROM, os valores originais são substituídos e não é possível desfazer; faça primeiro um backup em xdat.
2. Alimentação estável: alimentação insuficiente provoca perda de passos, falhas de comunicação ou perda do servo; alimente conforme os requisitos de Cablagem e alimentação SCS0009.
3. Porta série exclusiva: a mesma porta não pode ser aberta por dois programas ao mesmo tempo; feche antes o monitor de porta série, o software de PC ou outros programas que a ocupem.
4. Risco na alteração do ID: ligue ao barramento apenas um servo cujo ID vai ser alterado; se perder a ligação após a alteração, experimente "repor as definições de fábrica" (o ID volta a 1).
5. Sobretemperatura/sobretensão: a ferramenta monitoriza tensão e temperatura (alarme acima de 60 °C); em caso de temperatura elevada persistente, pare para arrefecer.
6. Ligação a quente: após retirar o USB, o programa tenta voltar a ligar; depois de reinserir, clique em atualizar portas.
7. Caracteres ilegíveis na consola Windows: se a ferramenta de linha de comandos mostrar emoji ilegíveis, defina PYTHONIOENCODING=utf-8 antes de executar.

10. Perguntas frequentes

Problema	Solução
Porta série não encontrada	Verifique o driver no Gestor de Dispositivos; mude de porta USB; instale o driver CH340
Porta série ocupada	Feche programas como o monitor de porta série; reinicie a ferramenta
Tipos de letra chineses em branco	O sistema usa Microsoft YaHei por omissão; se houver anomalia, instale tipos de letra chineses
Servos não detetados na procura	Verifique alimentação/cablagem; confirme o baudrate 1M
Falha na escrita	Verifique a alimentação e a ligação dos servos; confirme que o registo de destino permite escrita
PermissionError ao abrir a porta série	Garanta que nenhum outro processo ocupa essa porta COM
Linux: Permission denied: /dev/ttyUSB0	Não está no grupo dialout; ver a secção Linux acima
macOS: bloqueio com o nome de porta tty.	Use o dispositivo correspondente /dev/cu.*

11. Linha de comandos (opcional)

# listar as portas disponíveis
python -m src.gui.factory_calibration_tool --list-ports

# iniciar com uma porta específica
python -m src.gui.factory_calibration_tool --port COM3

Páginas relacionadas

• Cablagem, ID e alimentação SCS0009
• Início rápido SCS0009
• Aplicação de desktop SCS0009
• Controlo web SCS0009