Adicionar documentação

blog/2025-03-14-doc.md

@@ -0,0 +1,374 @@
+---
+slug: docs
+title: Guia de Configuração do LeRobot com SAM
+authors: [gabrielbosse1]
+tags: [robots, lerobot]
+---
+# Guia de Configuração do LeRobot com SAM
+
+## 1. Configuração do Ambiente
+
+Para configurar o ambiente do LeRobot, siga os passos abaixo:
+
+### 1.1 Instalar o Miniconda
+
+```bash
+mkdir -p ~/miniconda3
+wget https://repo.anaconda.com/miniconda/Miniconda3-latest-Linux-x86_64.sh -O ~/miniconda3/miniconda.sh
+bash ~/miniconda3/miniconda.sh -b -u -p ~/miniconda3
+rm ~/miniconda3/miniconda.sh
+source ~/miniconda3/bin/activate
+conda init –all
+```
+
+### 1.2 Criar e Ativar o Ambiente Conda
+
+```bash
+conda create -y -n lerobot python=3.10
+conda activate lerobot
+```
+
+### 1.3 Clonar o Repositório do LeRobot
+
+```bash
+git clone https://github.com/huggingface/lerobot.git ~/lerobot
+```
+
+### 1.4 Instalar Dependências Adicionais
+
+```bash
+cd ~/lerobot && pip install -e ".[feetech]"
+conda install -y -c conda-forge ffmpeg
+pip uninstall -y opencv-python
+conda install -y -c conda-forge "opencv>=4.10.0"
+conda install -c conda-forge jpeg libtiff
+```
+
+## 2. Ajuste de Permissões e Configuração dos Servos
+
+### 2.1 Identificação das Portas dos Adaptadores Bus
+
+Para encontrar a porta de cada adaptador de servo bus, execute o script utilitário:
+
+```bash
+python lerobot/scripts/find_motors_bus_port.py
+```
+
+**Exemplos de Saída**
+
+**Braço Líder (exemplo):**
+```bash
+Finding all available ports for the MotorBus.
+['/dev/tty.usbmodem575E0032081', '/dev/tty.usbmodem575E0031751']
+```
+Em seguida, remova o cabo USB e pressione Enter quando solicitado.
+O script indicará:
+```bash
+The port of this MotorsBus is /dev/tty.usbmodem575E0031751
+```
+Reconecte o cabo USB.
+
+**Braço Seguidor (exemplo):**
+```bash
+Finding all available ports for the MotorBus.
+['/dev/tty.usbmodem575E0032081', '/dev/tty.usbmodem575E0031751']
+```
+Remova o cabo USB e pressione Enter.
+O script exibirá:
+```bash
+The port of this MotorsBus is /dev/tty.usbmodem575E0032081
+```
+Reconecte o cabo.
+
+### 2.2 Ajustar Permissões de Acesso
+
+Execute o seguinte comando para cada braço, substituindo "x" pelo ID de cada dispositivo (por exemplo, /dev/ttyACM0 para o primeiro braço, /dev/ttyACM1 para o segundo, etc.):
+
+```bash
+sudo chmod 666 /dev/ttyACMx
+```
+
+Isso garantirá que o sistema tenha permissões adequadas para se comunicar com os motores e controladores dos braços.
+
+### 2.3 Configuração dos Motores e Definição dos IDs
+
+Para configurar os motores, conecte o primeiro motor e execute o script para definir seu ID para 1. Esse comando também definirá sua posição atual para 2048, portanto, espere que o motor se mova. Atenção: Substitua o valor após `--port` pela porta correspondente do seu board de controle (para os braços seguidores ou líderes, conforme aplicável).
+
+```bash
+python lerobot/scripts/configure_motor.py \
+  --port /dev/tty.usbmodem58760432961 \
+  --brand feetech \
+  --model sts3215 \
+  --baudrate 1000000 \
+  --ID 1
+```
+
+**Nota:**  
+Esses motores têm um range limitado de 0 a 4096, que corresponde a uma volta completa. O valor 2048 situa-se no meio dessa faixa, permitindo -2048 passos (180° no sentido anti-horário) ou +2048 passos (180° no sentido horário). A configuração também define o homing offset para 0, permitindo ajustar um deslocamento de até ±2048 passos se necessário.
+
+Após configurar o primeiro motor, desconecte-o e conecte o segundo, definindo seu ID para 2:
+
+```bash
+python lerobot/scripts/configure_motor.py \
+  --port /dev/tty.usbmodem58760432961 \
+  --brand feetech \
+  --model sts3215 \
+  --baudrate 1000000 \
+  --ID 2
+```
+
+Repita o processo para todos os motores até o ID 7 tanto para os motores dos braços líderes quanto para os dos braços seguidores.
+
+## 3. Adicionando o SAM ao LeRobot
+
+Para integrar o SAM ao LeRobot, edite o arquivo `~/lerobot/lerobot/common/robot_devices/configs.py` e adicione a seguinte configuração (substitua "x" pelos números correspondentes onde for necessário):
+
+```python
+@RobotConfig.register_subclass("sam")
+@dataclass
+class SamRobotConfig(ManipulatorRobotConfig):
+    calibration_dir: str = ".cache/calibration/sam"
+    max_relative_target: int | None = None  # Limitação da magnitude do vetor de destino posicional
+    leader_arms: dict[str, MotorsBusConfig] = field(
+        default_factory=lambda: {
+            "left": FeetechMotorsBusConfig(
+                port="/dev/ttyACMx",
+                motors={
+                    "shoulder_pan": [1, "sts3215"],
+                    "shoulder_lift": [2, "sts3215"],
+                    "elbow_flex": [3, "sts3215"],
+                    "wrist_flex": [4, "sts3215"],
+                    "wrist_pan": [5, "sts3215"],
+                    "wrist_roll": [6, "sts3215"],
+                    "gripper": [7, "sts3215"],
+                },
+            ),
+            "right": FeetechMotorsBusConfig(
+                port="/dev/ttyACMx",
+                motors={
+                    "shoulder_pan": [1, "sts3215"],
+                    "shoulder_lift": [2, "sts3215"],
+                    "elbow_flex": [3, "sts3215"],
+                    "wrist_flex": [4, "sts3215"],
+                    "wrist_pan": [5, "sts3215"],
+                    "wrist_roll": [6, "sts3215"],
+                    "gripper": [7, "sts3215"],
+                },
+            ),
+        }
+    )
+    follower_arms: dict[str, MotorsBusConfig] = field(
+        default_factory=lambda: {
+            "left": FeetechMotorsBusConfig(
+                port="/dev/ttyACMx",
+                motors={
+                    "shoulder_pan": [1, "sts3215"],
+                    "shoulder_lift": [2, "sts3215"],
+                    "elbow_flex": [3, "sts3215"],
+                    "wrist_flex": [4, "sts3215"],
+                    "wrist_pan": [5, "sts3215"],
+                    "wrist_roll": [6, "sts3215"],
+                    "gripper": [7, "sts3215"],
+                },
+            ),
+            "right": FeetechMotorsBusConfig(
+                port="/dev/ttyACMx",
+                motors={
+                    "shoulder_pan": [1, "sts3215"],
+                    "shoulder_lift": [2, "sts3215"],
+                    "elbow_flex": [3, "sts3215"],
+                    "wrist_flex": [4, "sts3215"],
+                    "wrist_pan": [5, "sts3215"],
+                    "wrist_roll": [6, "sts3215"],
+                    "gripper": [7, "sts3215"],
+                },
+            ),
+        }
+    )
+    cameras: dict[str, CameraConfig] = field(
+        default_factory=lambda: {
+            "top": OpenCVCameraConfig(
+                camera_index=x,
+                fps=30,
+                width=640,
+                height=480,
+            ),
+            "left": OpenCVCameraConfig(
+                camera_index=x,
+                fps=30,
+                width=640,
+                height=480,
+            ),
+        }
+    )
+    mock: bool = False
+```
+
+## 4. Configuração do Pi0
+
+Para configurar o Pi0, execute o seguinte comando:
+
+```bash
+pip install -e ".[pi0]"
+```
+
+## 5. Executando a Inferência
+
+Antes de executar a inferência, verifique se é necessário ajustar os arquivos de configuração do seu modelo (remova os campos "root" e "revision", se houver).
+
+### 5.1 Comando para Executar a Inferência
+
+Substitua os templates com os valores específicos do seu ambiente:
+
+```bash
+python lerobot/scripts/control_robot.py \
+  --robot.type=sam \
+  --control.type=record \
+  --control.fps=30 \
+  --control.single_task="suatask" \
+  --control.repo_id=seuusuario/eval_seudataset \
+  --control.tags='["tutorial"]' \
+  --control.warmup_time_s=1 \
+  --control.episode_time_s=30 \
+  --control.reset_time_s=30 \
+  --control.num_episodes=10 \
+  --control.push_to_hub=true \
+  --control.policy.path=caminho/para/seu/modelo \
+  --control.device=cuda
+```
+
+**Detalhes de Substituição:**
+
+- `--control.single_task`: Substitua "suatask" pelo nome da tarefa que deseja executar no robô.
+- `--control.repo_id`: Substitua `seuusuario/eval_seudataset` pelo seu usuário do Hugging Face e pelo nome do seu dataset.
+- `--control.tags`: Altere as tags conforme necessário para sua execução específica.
+- `--control.policy.path`: Substitua pelo caminho do modelo treinado que você deseja usar para a inferência.
+- `--control.device`: Defina como `cuda` se estiver usando uma GPU, ou `cpu` se estiver utilizando o processador do sistema.
+
+## 6. Calibração Manual dos Braços
+
+### 6.1 Calibração Manual do Braço Seguidor
+
+Você precisará mover o braço seguidor para as seguintes posições, em sequência:
+
+1. Posição Zero
+2. Posição Rotacionada
+3. Posição de Repouso
+
+Execute o seguinte script (certifique-se de que ambos os braços estejam conectados):
+
+```bash
+python lerobot/scripts/control_robot.py \
+  --robot.type=sam \
+  --robot.cameras='{}' \
+  --control.type=calibrate \
+  --control.arms='["main_follower"]'
+```
+
+### 6.2 Calibração Manual do Braço Líder
+
+Mova o braço para as seguintes posições, em sequência:
+
+1. Posição Zero
+2. Posição Rotacionada
+3. Posição de Repouso
+
+Execute o script:
+
+```bash
+python lerobot/scripts/control_robot.py \
+  --robot.type=sam \
+  --robot.cameras='{}' \
+  --control.type=calibrate \
+  --control.arms='["main_leader"]'
+```
+
+## 7. Operação do Robô
+
+### 7.1 Teleoperação
+
+**Teleoperação Simples**
+
+Execute o script para teleoperação simples (não exibe as câmeras):
+
+```bash
+python lerobot/scripts/control_robot.py \
+  --robot.type=sam \
+  --robot.cameras='{}' \
+  --control.type=teleoperate
+```
+
+**Teleoperação com Exibição de Câmeras**
+
+Após configurar suas câmeras, utilize o seguinte comando para teleoperação com exibição:
+
+```bash
+python lerobot/scripts/control_robot.py \
+  --robot.type=sam \
+  --control.type=teleoperate
+```
+
+### 7.2 Gravação de Dataset
+
+Após se familiarizar com a teleoperação, você pode gravar seu primeiro dataset com o SAM.
+
+1. Caso ainda não tenha feito, faça login no Hugging Face usando um token de acesso com permissão de escrita:
+
+   ```bash
+   huggingface-cli login --token ${HUGGINGFACE_TOKEN} --add-to-git-credential
+   ```
+
+2. Armazene seu nome de usuário em uma variável:
+
+   ```bash
+   HF_USER=$(huggingface-cli whoami | head -n 1)
+   echo $HF_USER
+   ```
+
+3. Grave 2 episódios e envie seu dataset para o Hub:
+
+   ```bash
+   python lerobot/scripts/control_robot.py \
+     --robot.type=sam \
+     --control.type=record \
+     --control.fps=30 \
+     --control.single_task="Grasp a lego block and put it in the bin." \
+     --control.repo_id=${HF_USER}/sam_test \
+     --control.tags='["sam","tutorial"]' \
+     --control.warmup_time_s=5 \
+     --control.episode_time_s=30 \
+     --control.reset_time_s=30 \
+     --control.num_episodes=2 \
+     --control.push_to_hub=true
+   ```
+
+**Nota:** Você pode retomar a gravação adicionando `--control.resume=true`.
+
+### 7.3 Visualização de Dataset
+
+Caso tenha enviado seu dataset para o Hugging Face Hub, visualize-o online copiando o repo id:
+
+```bash
+echo ${HF_USER}/sam_test
+```
+
+Ou visualize-o localmente (uma janela será aberta no navegador em `http://127.0.0.1:9090`):
+
+```bash
+python lerobot/scripts/visualize_dataset_html.py \
+  --repo-id ${HF_USER}/sam_test \
+  --local-files-only 1
+```
+
+### 7.4 Replay de um Episódio
+
+Para reproduzir o primeiro episódio gravado:
+
+```bash
+python lerobot/scripts/control_robot.py \
+  --robot.type=sam \
+  --control.type=replay \
+  --control.fps=30 \
+  --control.repo_id=${HF_USER}/sam_test \
+  --control.episode=0
+```