.. _picrawler_skill:

.. start_using_picrawler

21. Controllare PiCrawler con OpenClaw
=======================================


**Cos'è OpenClaw?**

Pensalo come una versione migliorata di ChatGPT. Mentre i chatbot tradizionali
possono solo parlare (generare testo), OpenClaw può agire. Comprende le tue
istruzioni in linguaggio naturale e può effettivamente eseguire operazioni sul
tuo computer, come eseguire comandi, gestire file e chiamare vari strumenti.

Ecco alcuni fantastici scenari applicativi:

* **Assistente personale tuttofare:** Lascia che gestisca il tuo calendario,
  imposti promemoria e tenga traccia delle attività. Devi solo dirglielo in
  un'app di chat (come Telegram, WhatsApp), e lui ricorderà ed eseguirà.
* **"Collante" di automazione:** Può fungere da legante per i tuoi vari
  servizi. Ad esempio, puoi fargli monitorare un sito web per variazioni di
  prezzo. Una volta rilevato un calo di prezzo, può attivare automaticamente
  un flusso di lavoro di automazione n8n per inviarti una notifica email.
* **Assistente di sviluppo dedicato:** Fagli gestire server, eseguire script
  e controllare i log. Puoi semplicemente dire: "Controlla il carico di
  sistema per me", e lui può connettersi via SSH al tuo server, eseguire il
  comando e restituire i risultati.
* **"Compagno di giochi" hardware:** Questo è un caso d'uso molto interessante.
  Puoi far controllare a OpenClaw l'hardware collegato a un Raspberry Pi. Ad
  esempio, uno sviluppatore l'ha usato per controllare un aspirapolvere robot
  con un braccio meccanico, o persino per analizzare i dati di un simulatore
  di corse e visualizzarli su uno schermo LED. Il team ufficiale di Raspberry
  Pi l'ha persino usato per costruire un photobooth automatico per un
  matrimonio, solo conversando, senza scrivere una sola riga di codice!


.. important::

   Il Raspberry Pi Zero 2W ha solo 512 MB di RAM, mentre OpenClaw richiede
   un minimo di 1 GB. Pertanto, non può funzionare correttamente. Si consiglia
   un Raspberry Pi 4/5 o superiore.

Avvio rapido di OpenClaw
--------------------------

Se desideri sperimentare la potenza di OpenClaw il più rapidamente possibile,
usa questo metodo. Installerà automaticamente OpenClaw e avvierà una
procedura guidata di configurazione interattiva.

1.  Apri il terminale sul tuo Raspberry Pi ed esegui direttamente il seguente
    comando. Questo comando scarica lo script di installazione dal sito web
    ufficiale e lo esegue:

    .. code-block:: bash

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

    .. note:: Poiché le nuove versioni vengono aggiornate rapidamente, è normale
       che i tuoi passaggi di installazione differiscano leggermente.

2.  Lo script scaricherà e installerà automaticamente OpenClaw.

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


3.  Vedrai quindi una richiesta di sicurezza che chiede se ti fidi di OpenClaw.
    Una volta sicuro che sia sicuro e affidabile, usa i tasti freccia per
    navigare su "Yes" e premi Invio.

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


4.  Seleziona Quick Start, quindi premi Invio.

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

5.  Seleziona il tuo modello, quindi premi Invio. Qui usiamo OpenAI come
    esempio.

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

6.  Seleziona OpenAI API Key.

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

7.  Incolla ora la chiave 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">Piattaforma OpenAI</a>

8.  Vai su |link_openai_platform| e accedi. Nella pagina **API keys**, clicca
    su **Create new secret key**.

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

9.  Compila i dettagli (Owner, Name, Project e permessi se necessario), poi
    clicca su **Create secret key**.

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

10. Una volta creata la chiave, copiala immediatamente — non potrai più
    visualizzarla. Se la perdi, dovrai generarne una nuova.

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

11. Incolla la chiave nella configurazione di OpenClaw.

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

12. Seleziona il modello che desideri utilizzare. In questo esempio, useremo
    **Keep current**.

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

13. Successivamente c'è la selezione dei canali. I canali si riferiscono ai
    servizi di comunicazione supportati da OpenClaw, come Telegram, WhatsApp,
    Discord e altri. Usa il tasto freccia giù per selezionare l'opzione
    "Skip for now", quindi premi Invio.

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

14. Successivamente, ti verrà chiesto di configurare subito le competenze.
    Seleziona "Yes" e premi Invio.

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

15. Installa le competenze di cui hai bisogno. Nell'esempio seguente,
    selezioniamo l'opzione "Skip for now" (premi la barra spaziatrice per
    selezionare), quindi premi Invio.

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


16. Successivamente ci sono gli Hooks; selezioneremo "command-logger" e
    "session-memory".

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


17. L'installazione è ora completa. Puoi avviare OpenClaw selezionando
    "Hatch in TUI" e premendo Invio.

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


.. note::

   Puoi avviare OpenClaw inserendo il seguente comando:

    .. code-block:: bash

       openclaw tui

   E puoi premere Ctrl+C due volte per uscire dall'interfaccia TUI.

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

Far funzionare PiCrawler con OpenClaw
----------------------------------------

**Cos'è PiCrawler Skill?**

PiCrawler Skill è un'estensione per OpenClaw che ti permette di controllare
il tuo robot ragno SunFounder PiCrawler tramite linguaggio naturale. Invece
di scrivere script Python o ricordare valori di coordinate, puoi semplicemente
dire a OpenClaw cosa vuoi che PiCrawler faccia — come "alzati", "cammina tre
passi in avanti" o "controlla se c'è un ostacolo davanti" — e OpenClaw
eseguirà automaticamente il codice Python appropriato.

Ecco alcune cose che puoi fare con PiCrawler Skill:

* **Movimenti di base:** Camminare in avanti, indietro, girare a
  sinistra/destra, virate a piccolo angolo
* **Posizioni:** Alzarsi, sedersi
* **Azioni espressive:** Salutare con una zampa anteriore, ballare, fare
  flessioni, guardare in diverse direzioni
* **Sensori:** Leggere il sensore di distanza a ultrasuoni per rilevare
  ostacoli
* **Suono:** Riprodurre effetti sonori e musica attraverso l'altoparlante
  del robot
* **Visione con fotocamera:** Scattare foto, rilevare volti, tracciare
  colori, riconoscere codici QR e gesti

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

Prerequisiti
--------------

Prima di poter utilizzare PiCrawler Skill con OpenClaw, assicurati di avere:

1. **PiCrawler** correttamente assemblato e collegato al tuo Raspberry Pi
2. **OpenClaw** installato e in esecuzione
3. Le seguenti librerie Python installate:

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

Puoi verificare l'installazione eseguendo:

.. code-block:: bash

   python3 -c "import picrawler"

Se questo comando viene eseguito senza errori, sei pronto per procedere.

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

Installare PiCrawler Skill
----------------------------

Segui questi passaggi per installare PiCrawler Skill per OpenClaw:

1. **Copia i file del PiCrawler Skill** nella directory delle competenze di
   OpenClaw:

   .. code-block:: bash

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

2. **Verifica l'installazione** controllando i file della competenza:

   .. code-block:: bash

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

   Dovresti vedere ``SKILL.md``, ``install.sh``, ``scripts/`` e
   ``references/`` nell'output.

Il file ``SKILL.md`` della competenza contiene tutte le istruzioni di cui
OpenClaw ha bisogno — regole di sicurezza, modelli di codice per ogni
capacità e una mappatura dalle richieste in linguaggio naturale al codice
Python. OpenClaw legge questo file e lo usa per decidere quale codice
eseguire sul tuo PiCrawler.

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

Testare PiCrawler Skill dalla CLI
-----------------------------------

Prima di utilizzare la competenza con OpenClaw, potresti voler testare le
funzionalità di base direttamente dal terminale usando lo strumento CLI
incluso.

**Controllare la distanza ultrasonica:**

.. code-block:: bash

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

**Far sedere PiCrawler:**

.. code-block:: bash

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

**Far alzare PiCrawler:**

.. code-block:: bash

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

**Camminare in avanti:**

.. code-block:: bash

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

**Girare a sinistra:**

.. code-block:: bash

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

**Riprodurre un effetto sonoro:**

.. code-block:: bash

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

**Eseguire la calibrazione dei servi:**

.. code-block:: bash

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

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

Usare PiCrawler Skill in OpenClaw
------------------------------------

Una volta verificato che PiCrawler Skill funziona dalla riga di comando, puoi
iniziare a usarlo all'interno di OpenClaw.

1. **Avvia OpenClaw TUI**:

   .. code-block:: bash

      openclaw tui

2. **Invia comandi in linguaggio naturale** per controllare PiCrawler. Ecco
   alcuni esempi:

   * "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 tradurrà automaticamente** la tua richiesta nel codice Python
   appropriato e lo eseguirà su PiCrawler. Per i comandi di movimento, la
   competenza assicura sempre che il robot si alzi prima e si sieda dopo aver
   completato l'azione.

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

Azioni e comandi disponibili
------------------------------

Ecco l'elenco completo delle capacità supportate da PiCrawler Skill:

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

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

   * - Azione
     - Descrizione
   * - ``forward``
     - Camminare in avanti
   * - ``backward``
     - Camminare all'indietro
   * - ``turn left``
     - Ruotare a sinistra sul posto
   * - ``turn right``
     - Ruotare a destra sul posto
   * - ``turn left angle``
     - Virata a piccolo angolo a sinistra
   * - ``turn right angle``
     - Virata a piccolo angolo a destra

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

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

   * - Posizione
     - Descrizione
   * - ``stand``
     - Alzarsi dalla posizione seduta
   * - ``sit``
     - Sedersi dalla posizione in piedi

Azioni aggiuntive (via linguaggio naturale / exec)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

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

   * - Azione
     - Descrizione
   * - ``dance``
     - Eseguire un movimento di danza
   * - ``push_up``
     - Fare flessioni
   * - ``wave``
     - Salutare con una zampa anteriore
   * - ``look_left``
     - Girare il corpo per guardare a sinistra
   * - ``look_right``
     - Girare il corpo per guardare a destra
   * - ``look_up``
     - Inclinare il corpo per guardare in alto
   * - ``look_down``
     - Inclinare il corpo per guardare in basso

Sensori
^^^^^^^

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

   * - Comando
     - Descrizione
   * - ``sensor distance``
     - Leggere il sensore di distanza a ultrasuoni (restituisce cm)

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

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

   * - Comando
     - Descrizione
   * - ``sound play <file>``
     - Riprodurre un file di effetto sonoro
   * - ``sound music <file>``
     - Riprodurre musica di sottofondo
   * - ``sound volume <0-100>``
     - Impostare il volume dell'altoparlante
   * - ``sound stop``
     - Fermare la riproduzione

Fotocamera e visione (via linguaggio naturale / exec)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

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

   * - Capacità
     - Descrizione
   * - Scattare foto
     - Catturare e salvare una foto in ``~/Pictures/``
   * - Rilevamento volti
     - Rilevare volti umani e segnalare la posizione
   * - Rilevamento colore
     - Localizzare oggetti per colore (rosso, blu, verde, ecc.)
   * - Riconoscimento gesti
     - Riconoscere gesti carta/sasso/forbice
   * - Rilevamento segnali stradali
     - Riconoscere segnali di stop/sinistra/destra/avanti
   * - Scansione codici QR
     - Leggere dati e posizione dei codici QR

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

Risoluzione dei problemi
--------------------------

Problemi di OpenClaw
^^^^^^^^^^^^^^^^^^^^^

D: Durante l'installazione, ricevo l'errore ``Error: systemctl is-enabled unavailable: Command failed: systemctl --user is-enabled openclaw-gateway.service``. Cosa devo fare?

   Puoi ignorarlo per ora, ma potresti incontrare problemi nei passaggi
   successivi. Consultali uno per uno in quel momento.


D: Quando eseguo ``openclaw tui``, ricevo l'errore ``-bash: openclaw: command not found``. Cosa devo fare?

   Esegui il seguente comando:

   .. code-block:: bash

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

   Ora dovresti essere in grado di avviare l'interfaccia TUI con
   ``openclaw tui``.


D: In ``openclaw tui``, incontro ``not connected to gateway — message not sent`` o il messaggio ``gateway disconnected: closed``.

   Questo perché il tuo servizio OpenClaw Gateway non è avviato. Apri un altro
   terminale ed esegui il seguente comando per avviare l'OpenClaw Gateway:

   .. code-block:: bash

      openclaw gateway

   Quindi riavvia ``openclaw tui`` e potrai usarlo direttamente.


D: Voglio impostare il servizio OpenClaw Gateway per l'esecuzione in background / avvio automatico all'accensione. Come faccio?

   Normalmente, il tuo servizio OpenClaw Gateway dovrebbe avviarsi
   automaticamente all'accensione. In caso contrario, puoi avviarlo
   manualmente con il seguente comando.

   1. Crea la directory ``~/.config/systemd/user``:

   .. code-block:: bash

      mkdir -p ~/.config/systemd/user


   2. Crea il file ``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. Quindi ricarica la configurazione di systemd:

   .. code-block:: bash

      systemctl --user daemon-reload

   4. Avvia il servizio:

   .. code-block:: bash

      systemctl --user start openclaw-gateway

   A questo punto, riavvia ``openclaw tui`` e potrai usarlo direttamente.

   5. Attivalo per l'avvio automatico:

   .. code-block:: bash

      systemctl --user enable openclaw-gateway


D: Il mio OpenClaw non può operare sul sistema, cosa devo fare?

   Un OpenClaw appena installato potrebbe non avere il permesso di operare
   sul tuo sistema Raspberry Pi per impostazione predefinita; può solo
   chattare. Dobbiamo configurare manualmente i permessi.

   1.  Apri il file di configurazione di OpenClaw:

      .. code-block:: bash

         nano ~/.openclaw/openclaw.json

   2.  Trova l'opzione ``tools`` e modifica ``profile`` ed ``exec`` come
       mostrato.

      .. code-block:: json

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

   3.  Salva ed esci.

   4.  Inserisci il seguente comando nel terminale per riavviare l'OpenClaw
       Gateway:

      .. code-block:: bash

         openclaw gateway restart

   Ora, OpenClaw dovrebbe avere i permessi di lettura e scrittura ed essere
   in grado di operare sul tuo sistema Raspberry Pi.

Problemi di PiCrawler
^^^^^^^^^^^^^^^^^^^^^^


D: PiCrawler non risponde ai comandi. Cosa devo fare?

   Per prima cosa, verifica che PiCrawler sia correttamente collegato e
   acceso. Quindi testa le funzionalità di base:

   .. code-block:: bash

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

   Se questo fallisce, assicurati che le librerie Python richieste siano
   installate:

   .. code-block:: bash

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

D: Il test ``import picrawler`` fallisce.

   Ciò significa che la libreria Python di PiCrawler non è installata
   correttamente. Consulta la guida all'installazione ufficiale di PiCrawler
   per installare le librerie necessarie. Puoi anche eseguire lo script di
   installazione incluso:

   .. code-block:: bash

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

D: OpenClaw non riconosce la competenza PiCrawler.

   Ricorda a OpenClaw di sincronizzare le competenze dicendo nel TUI:
   *"Please rsync my skills"* o riavvia l'OpenClaw Gateway:

   .. code-block:: bash

      openclaw gateway restart

D: I movimenti di PiCrawler sembrano instabili o a scatti.

   Questo è solitamente causato dall'esecuzione di azioni a una velocità
   troppo elevata o senza consentire il completamento dell'azione precedente.
   La competenza applica regole di sicurezza (alzarsi prima di muoversi,
   sedersi dopo il movimento) e consiglia intervalli di velocità. Prova a
   ridurre il parametro di velocità (ad esempio, ``--speed 40``) o ad
   aggiungere brevi pause tra comandi consecutivi.

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

.. end_using_picrawler