.. _picrawler_skill:

.. start_using_picrawler

21. Controlar PiCrawler con OpenClaw
======================================


**¿Qué es OpenClaw?**

Piense en ello como una versión mejorada de ChatGPT. Mientras que los chatbots
tradicionales solo pueden hablar (generar texto), OpenClaw puede actuar.
Entiende sus instrucciones en lenguaje natural y puede realizar operaciones en
su computadora, como ejecutar comandos, gestionar archivos y llamar a varias
herramientas.

Aquí hay algunos escenarios de aplicación fantásticos:

* **Asistente personal todo en uno:** Deje que gestione su agenda, establezca
  recordatorios y haga seguimiento de tareas. Solo necesita decírselo en una
  app de chat (como Telegram, WhatsApp), y lo recordará y ejecutará.
* **"Pegamento" de automatización:** Puede actuar como un aglutinante para sus
  diversos servicios. Por ejemplo, puede hacer que supervise un sitio web en
  busca de cambios de precio. Una vez detectada una bajada de precio, puede
  activar automáticamente un flujo de trabajo de automatización n8n para
  enviarle una notificación por correo electrónico.
* **Asistente de desarrollo dedicado:** Haga que gestione servidores, ejecute
  scripts y revise registros. Puede simplemente decir: "Comprueba la carga del
  sistema", y puede conectarse por SSH a su servidor, ejecutar el comando y
  devolver los resultados.
* **"Compañero de juegos" de hardware:** Este es un caso de uso muy interesante.
  Puede hacer que OpenClaw controle hardware conectado a un Raspberry Pi. Por
  ejemplo, un desarrollador lo usó para controlar un robot aspirador con un
  brazo mecánico, o incluso para analizar datos de simulador de carreras y
  mostrarlos en una pantalla LED. ¡El equipo oficial de Raspberry Pi incluso
  lo usó para construir un fotomatón automático para una boda, solo mediante
  conversación, sin escribir una sola línea de código!


.. important::

   El Raspberry Pi Zero 2W tiene solo 512 MB de RAM, mientras que OpenClaw
   requiere un mínimo de 1 GB. Por lo tanto, no puede ejecutarse correctamente.
   Se recomienda un Raspberry Pi 4/5 o superior.

Inicio rápido de OpenClaw
----------------------------

Si desea experimentar la potencia de OpenClaw lo más rápido posible, use este
método. Instalará automáticamente OpenClaw y lanzará un asistente de
configuración interactivo.

1.  Abra la terminal en su Raspberry Pi y ejecute el siguiente comando
    directamente. Este comando descarga el script de instalación del sitio
    web oficial y lo ejecuta:

    .. code-block:: bash

       curl -fsSL https://openclaw.ai/install.sh | bash

    .. note:: Debido a que las nuevas versiones se actualizan rápidamente, es
       normal que sus pasos de instalación difieran ligeramente.

2.  El script descargará e instalará automáticamente OpenClaw.

    .. image:: /img/openclaw/install_open_claw.png


3.  Luego verá una solicitud de seguridad preguntando si confía en OpenClaw.
    Una vez que esté seguro de que es seguro y fiable, use las teclas de
    flecha para navegar a "Yes" y presione Enter.

    .. image:: /img/openclaw/security_open_claw.png


4.  Seleccione Quick Start, luego presione Enter.

    .. image:: /img/openclaw/quickstart_open_claw.png

5.  Seleccione su modelo, luego presione Enter. Aquí usamos OpenAI como
    ejemplo.

    .. image:: /img/openclaw/model_provider_open_claw.png

6.  Seleccione OpenAI API Key.

    .. image:: /img/openclaw/api_key_open_claw.png

7.  Pegue ahora la clave API.

    .. image:: /img/openclaw/paste_api_key_open_claw.png

.. |link_openai_platform| raw:: html

    <a href="https://platform.openai.com/settings/organization/api-keys" target="_blank">Plataforma OpenAI</a>

8.  Vaya a |link_openai_platform| e inicie sesión. En la página **API keys**,
    haga clic en **Create new secret key**.

    .. image:: /img/openclaw/llm_openai_create.png

9.  Complete los detalles (Owner, Name, Project y permisos si es necesario),
    luego haga clic en **Create secret key**.

    .. image:: /img/openclaw/llm_openai_create_confirm.png

10. Una vez creada la clave, cópiela inmediatamente — no podrá verla de nuevo.
    Si la pierde, deberá generar una nueva.

    .. image:: /img/openclaw/llm_openai_copy.png

11. Pegue la clave en la configuración de OpenClaw.

    .. image:: /img/openclaw/paste_api_key_enter_open_claw.png

12. Seleccione el modelo que desea usar. En este ejemplo, usaremos **Keep
    current**.

    .. image:: /img/openclaw/model_config_open_claw.png

13. A continuación viene la selección de canales. Los canales se refieren a
    los servicios de comunicación compatibles con OpenClaw, como Telegram,
    WhatsApp, Discord y más. Use la tecla de flecha hacia abajo para
    seleccionar la opción "Skip for now", luego presione Enter.

    .. image:: /img/openclaw/channel_open_claw.png

14. A continuación, se le pedirá que configure skills inmediatamente.
    Seleccione "Yes" y presione Enter.

    .. image:: /img/openclaw/config_skill_open_claw.png

15. Instale los skills que necesite. En el siguiente ejemplo, seleccionamos
    la opción "Skip for now" (presione la barra espaciadora para seleccionar),
    luego presione Enter.

    .. image:: /img/openclaw/install_skill_open_claw.png


16. A continuación vienen los Hooks; seleccionaremos "command-logger" y
    "session-memory".

    .. image:: /img/openclaw/hooks2_open_claw.png


17. La instalación está completa. Puede iniciar OpenClaw seleccionando
    "Hatch in TUI" y presionando Enter.

   .. image:: /img/openclaw/hatch_open_claw.png


.. note::

   Puede iniciar OpenClaw ingresando el siguiente comando:

    .. code-block:: bash

       openclaw tui

   Y puede presionar Ctrl+C dos veces para salir de la interfaz TUI.

------------------------------------------------------------------------

Hacer que OpenClaw opere el PiCrawler
----------------------------------------

**¿Qué es PiCrawler Skill?**

PiCrawler Skill es una extensión para OpenClaw que le permite controlar su
robot araña SunFounder PiCrawler mediante lenguaje natural. En lugar de
escribir scripts de Python o recordar valores de coordenadas, puede
simplemente decirle a OpenClaw lo que quiere que PiCrawler haga — como
"levántate", "camina tres pasos hacia adelante" o "comprueba si hay un
obstáculo delante" — y OpenClaw ejecutará automáticamente el código Python
apropiado.

Aquí hay algunas cosas que puede hacer con PiCrawler Skill:

* **Movimientos básicos:** Caminar hacia adelante, hacia atrás, girar a la
  izquierda/derecha, giros de ángulo pequeño
* **Posturas:** Levantarse, sentarse
* **Acciones expresivas:** Saludar con una pata delantera, bailar, hacer
  flexiones, mirar en diferentes direcciones
* **Sensores:** Leer el sensor de distancia ultrasónico para detectar
  obstáculos
* **Sonido:** Reproducir efectos de sonido y música a través del altavoz del
  robot
* **Visión por cámara:** Tomar fotos, detectar rostros, rastrear colores,
  reconocer códigos QR y gestos

----------------------------------------------------------------

Requisitos previos
--------------------

Antes de poder usar PiCrawler Skill con OpenClaw, asegúrese de tener:

1. **PiCrawler** correctamente ensamblado y conectado a su Raspberry Pi
2. **OpenClaw** instalado y en funcionamiento
3. Las siguientes bibliotecas de Python instaladas:

   - ``picrawler``
   - ``robot_hat``
   - ``vilib``

Puede verificar la instalación ejecutando:

.. code-block:: bash

   python3 -c "import picrawler"

Si este comando se ejecuta sin errores, está listo para continuar.

----------------------------------------------------------------

Instalar PiCrawler Skill
--------------------------

Siga estos pasos para instalar el PiCrawler Skill para OpenClaw:

1. **Copie los archivos del skill PiCrawler** al directorio de skills de
   OpenClaw:

   .. code-block:: bash

      cp -r ~/picrawler/picrawler-control ~/.openclaw/workspace/skills/

2. **Verifique la instalación** comprobando los archivos del skill:

   .. code-block:: bash

      ls ~/.openclaw/workspace/skills/picrawler-control/

   Debería ver ``SKILL.md``, ``install.sh``, ``scripts/`` y ``references/``
   en la salida.

El archivo ``SKILL.md`` del skill contiene todas las instrucciones que
OpenClaw necesita — reglas de seguridad, plantillas de código para cada
capacidad y un mapeo de solicitudes en lenguaje natural a código Python.
OpenClaw lee este archivo y lo usa para decidir qué código ejecutar en su
PiCrawler.

----------------------------------------------------------------

Probar PiCrawler Skill desde la CLI
------------------------------------

Antes de usar el skill con OpenClaw, puede probar la funcionalidad básica
directamente desde la terminal usando la herramienta CLI incluida.

**Comprobar distancia ultrasónica:**

.. code-block:: bash

   python3 ~/.openclaw/workspace/skills/picrawler-control/scripts/pc.py sensor distance

**Hacer que PiCrawler se siente:**

.. code-block:: bash

   python3 ~/.openclaw/workspace/skills/picrawler-control/scripts/pc.py pose sit --speed 40

**Hacer que PiCrawler se levante:**

.. code-block:: bash

   python3 ~/.openclaw/workspace/skills/picrawler-control/scripts/pc.py pose stand --speed 40

**Caminar hacia adelante:**

.. code-block:: bash

   python3 ~/.openclaw/workspace/skills/picrawler-control/scripts/pc.py move forward --steps 2 --speed 60

**Girar a la izquierda:**

.. code-block:: bash

   python3 ~/.openclaw/workspace/skills/picrawler-control/scripts/pc.py move "turn left" --steps 1 --speed 60

**Reproducir un efecto de sonido:**

.. code-block:: bash

   python3 ~/.openclaw/workspace/skills/picrawler-control/scripts/pc.py sound play /home/pi/picrawler/examples/sounds/talk1.wav --volume 80

**Ejecutar calibración de servos:**

.. code-block:: bash

   python3 ~/.openclaw/workspace/skills/picrawler-control/scripts/pc.py calibrate

----------------------------------------------------------------

Usar PiCrawler Skill en OpenClaw
----------------------------------

Una vez que haya verificado que PiCrawler Skill funciona desde la línea de
comandos, puede comenzar a usarlo dentro de OpenClaw.

1. **Iniciar OpenClaw TUI**:

   .. code-block:: bash

      openclaw tui

2. **Envíe comandos en lenguaje natural** para controlar PiCrawler. Aquí hay
   algunos ejemplos:

   * "Stand up"
   * "Sit down"
   * "Walk forward three steps"
   * "Turn left"
   * "Do a dance"
   * "Do some push-ups"
   * "Wave your front leg"
   * "Look to the left"
   * "Check if there's something ahead"
   * "Take a photo"
   * "Detect faces / look at me"
   * "Find the color red"

3. **OpenClaw traducirá automáticamente** su solicitud al código Python
   apropiado y lo ejecutará en PiCrawler. Para comandos de movimiento, el
   skill siempre asegura que el robot se levante primero y se siente después
   de completar la acción.

----------------------------------------------------------------

Acciones y comandos disponibles
---------------------------------

Aquí está la lista completa de capacidades soportadas por PiCrawler Skill:

Movimientos (``pc.py move``)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. list-table::
   :widths: 30 70
   :header-rows: 1

   * - Acción
     - Descripción
   * - ``forward``
     - Caminar hacia adelante
   * - ``backward``
     - Caminar hacia atrás
   * - ``turn left``
     - Girar a la izquierda en el lugar
   * - ``turn right``
     - Girar a la derecha en el lugar
   * - ``turn left angle``
     - Giro de ángulo pequeño a la izquierda
   * - ``turn right angle``
     - Giro de ángulo pequeño a la derecha

Posturas (``pc.py pose``)
^^^^^^^^^^^^^^^^^^^^^^^^^^

.. list-table::
   :widths: 30 70
   :header-rows: 1

   * - Postura
     - Descripción
   * - ``stand``
     - Levantarse de la posición sentada
   * - ``sit``
     - Sentarse de la posición de pie

Acciones adicionales (vía lenguaje natural / exec)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. list-table::
   :widths: 30 70
   :header-rows: 1

   * - Acción
     - Descripción
   * - ``dance``
     - Realizar un movimiento de baile
   * - ``push_up``
     - Hacer flexiones
   * - ``wave``
     - Saludar con una pata delantera
   * - ``look_left``
     - Girar el cuerpo para mirar a la izquierda
   * - ``look_right``
     - Girar el cuerpo para mirar a la derecha
   * - ``look_up``
     - Inclinar el cuerpo para mirar arriba
   * - ``look_down``
     - Inclinar el cuerpo para mirar abajo

Sensores
^^^^^^^^

.. list-table::
   :widths: 30 70
   :header-rows: 1

   * - Comando
     - Descripción
   * - ``sensor distance``
     - Leer el sensor de distancia ultrasónico (devuelve cm)

Sonido (``pc.py sound``)
^^^^^^^^^^^^^^^^^^^^^^^^^^

.. list-table::
   :widths: 30 70
   :header-rows: 1

   * - Comando
     - Descripción
   * - ``sound play <archivo>``
     - Reproducir un archivo de efecto de sonido
   * - ``sound music <archivo>``
     - Reproducir música de fondo
   * - ``sound volume <0-100>``
     - Ajustar el volumen del altavoz
   * - ``sound stop``
     - Detener la reproducción

Cámara y visión (vía lenguaje natural / exec)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. list-table::
   :widths: 30 70
   :header-rows: 1

   * - Capacidad
     - Descripción
   * - Tomar foto
     - Capturar y guardar una foto en ``~/Pictures/``
   * - Detección de rostros
     - Detectar rostros humanos e informar la posición
   * - Detección de color
     - Localizar objetos por color (rojo, azul, verde, etc.)
   * - Reconocimiento de gestos
     - Reconocer gestos de piedra/papel/tijera
   * - Detección de señales de tráfico
     - Reconocer señales de stop/izquierda/derecha/adelante
   * - Escaneo de códigos QR
     - Leer datos y posición de códigos QR

----------------------------------------------------------------

Solución de problemas
----------------------

Problemas de OpenClaw
^^^^^^^^^^^^^^^^^^^^^

P: Durante la instalación, obtengo el error ``Error: systemctl is-enabled unavailable: Command failed: systemctl --user is-enabled openclaw-gateway.service``. ¿Qué debo hacer?

   Puede ignorar esto por ahora, pero podría encontrar problemas en los
   siguientes pasos. Consúltelos uno por uno en ese momento.


P: Cuando ejecuto ``openclaw tui``, obtengo el error ``-bash: openclaw: command not found``. ¿Qué debo hacer?

   Ejecute el siguiente comando:

   .. code-block:: bash

      echo 'export PATH="$HOME/.npm-global/bin:$PATH"' >> ~/.bashrc
      source ~/.bashrc

   Ahora debería poder iniciar la interfaz TUI con ``openclaw tui``.


P: En ``openclaw tui``, encuentro ``not connected to gateway — message not sent`` o el mensaje ``gateway disconnected: closed``.

   Esto se debe a que su servicio OpenClaw Gateway no está iniciado. Abra otra
   terminal y ejecute el siguiente comando para iniciar el OpenClaw Gateway:

   .. code-block:: bash

      openclaw gateway

   Luego reinicie ``openclaw tui``, y podrá usarlo directamente.


P: Quiero configurar el servicio OpenClaw Gateway para que se ejecute en segundo plano / se inicie automáticamente al arrancar. ¿Cómo lo hago?

   Normalmente, su servicio OpenClaw Gateway debería iniciarse automáticamente
   al arrancar. Si no lo hace, puede iniciarlo manualmente con el siguiente
   comando.

   1. Cree el directorio ``~/.config/systemd/user``:

   .. code-block:: bash

      mkdir -p ~/.config/systemd/user


   2. Cree el archivo ``openclaw-gateway.service``:

   .. code-block:: bash

      cat > ~/.config/systemd/user/openclaw-gateway.service << EOF
      [Unit]
      Description=OpenClaw Gateway
      After=network.target

      [Service]
      Type=simple
      ExecStart=$HOME/.npm-global/bin/openclaw gateway run
      Restart=on-failure
      RestartSec=10
      Environment="PATH=$HOME/.npm-global/bin:/usr/local/bin:/usr/bin:/bin:/usr/sbin"
      Environment="NODE_ENV=production"

      [Install]
      WantedBy=default.target
      EOF


   3. Luego recargue la configuración de systemd:

   .. code-block:: bash

      systemctl --user daemon-reload

   4. Inicie el servicio:

   .. code-block:: bash

      systemctl --user start openclaw-gateway

   En este punto, reinicie ``openclaw tui``, y podrá usarlo directamente.

   5. Actívelo para que se inicie al arrancar:

   .. code-block:: bash

      systemctl --user enable openclaw-gateway


P: Mi OpenClaw no puede operar el sistema, ¿qué debo hacer?

   Un OpenClaw recién instalado puede no tener permiso para operar su sistema
   Raspberry Pi por defecto; solo puede chatear. Necesitamos configurar
   manualmente los permisos.

   1.  Abra el archivo de configuración de OpenClaw:

      .. code-block:: bash

         nano ~/.openclaw/openclaw.json

   2.  Encuentre la opción ``tools`` y cambie ``profile`` y ``exec`` como se
       muestra.

      .. code-block:: json

        "tools": {
            "profile": "coding",
            "exec": {
                "secrity": "full"
            }
        },

   3.  Guarde y salga.

   4.  Ingrese el siguiente comando en la terminal para reiniciar el OpenClaw
       Gateway:

      .. code-block:: bash

         openclaw gateway restart

   Ahora, OpenClaw debería tener permisos de lectura y escritura y poder
   operar su sistema Raspberry Pi.

Problemas de PiCrawler
^^^^^^^^^^^^^^^^^^^^^^


P: PiCrawler no responde a los comandos. ¿Qué debo hacer?

   Primero, verifique que PiCrawler esté correctamente conectado y encendido.
   Luego pruebe la funcionalidad básica:

   .. code-block:: bash

      python3 ~/.openclaw/workspace/skills/picrawler-control/scripts/pc.py pose sit --speed 40

   Si esto falla, asegúrese de que las bibliotecas Python requeridas estén
   instaladas:

   .. code-block:: bash

      python3 -c "import picrawler; import robot_hat; import vilib"

P: La prueba ``import picrawler`` falla.

   Esto significa que la biblioteca Python de PiCrawler no está correctamente
   instalada. Consulte la guía de instalación oficial de PiCrawler para
   instalar las bibliotecas necesarias. También puede ejecutar el script de
   instalación incluido:

   .. code-block:: bash

      bash ~/.openclaw/workspace/skills/picrawler-control/install.sh

P: OpenClaw no reconoce el skill de PiCrawler.

   Recuerde a OpenClaw que sincronice los skills diciendo en el TUI:
   *"Please rsync my skills"* o reinicie el OpenClaw Gateway:

   .. code-block:: bash

      openclaw gateway restart

P: Los movimientos de PiCrawler parecen inestables o bruscos.

   Esto generalmente se debe a ejecutar acciones a una velocidad demasiado
   alta o sin permitir que la acción anterior se complete. El skill aplica
   reglas de seguridad (levantarse antes de moverse, sentarse después del
   movimiento) y recomienda rangos de velocidad. Intente reducir el parámetro
   de velocidad (por ejemplo, ``--speed 40``), o agregue pequeñas pausas
   entre comandos consecutivos.

----------------------------------------------------------------

.. end_using_picrawler