raspOVOS

RaspOVOS: A Beginner’s Guide to Setting Up Your Raspberry Pi with OVOS

This tutorial is designed for users new to Raspberry Pi and RaspOVOS. Follow these steps to set up and optimize your device for the best experience.

Step 1: Prepare Your Hardware

Raspberry Pi Model Recommendations

Storage Options

Power Supply Considerations

Raspberry Pi boards are notoriously picky about power supplies. Insufficient power can lead to performance issues, random reboots, or the appearance of the undervoltage detected warning (a lightning bolt symbol in the top-right corner of the screen).

Step 2: Install RaspOVOS Image

  1. Download and Install Raspberry Pi Imager
    • Visit Raspberry Pi Imager and download the appropriate version for your OS.
    • Install and launch the imager.
  2. Flash the Image to Storage
    • Insert your SD card or USB drive into your computer.
    • In the Raspberry Pi Imager:
      • Choose OS: Select “Use custom” and locate the RaspOVOS image file.
      • Choose Storage: Select your SD card or USB drive.

image

image

image

  1. Advanced Configuration Options
    • Click Next and select Edit Settings to customize settings, including:
      • Password: Change the default password.
      • Hostname: Set a custom hostname for your device.
      • Wi-Fi Credentials: Enter your Wi-Fi network name and password.
      • Keyboard Layout: Configure the correct layout for your region.

    Important: Do NOT change the default username (ovos), as it is required for the system to function properly.

image

image

  1. Write the Image
    • Click Save and then Yes to flash the image onto your storage device.
    • Once complete, safely remove the SD card or USB drive from your computer.

Step 3: Initial Setup and First Boot

Connect and Power On

First Boot Process

  1. Initialization:
    • The system will expand the filesystem, generate SSH keys, and perform other setups.
  2. Reboots:
    • The device will reboot up to three times during this process.
  3. Autologin:
    • The ovos user will automatically log in to the terminal after boot.
  4. Check System Status:
    • Use the ologs command to monitor logs and confirm that the system has fully initialized.

Step 4: Setting Up Wi-Fi

Option 1: Configure Wi-Fi Using Raspberry Pi Imager

The most straightforward method is to set up Wi-Fi during the imaging process.

  1. Open Raspberry Pi Imager and select Edit Settings Option.
  2. Enter your SSID (Wi-Fi network name) and password in the Wi-Fi configuration fields.
  3. Write the image to your SD card or USB drive, and your Wi-Fi will be pre-configured.

Option 2: Use Audio-Based Wi-Fi Setup (ggwave)

  1. Open ggwave Wi-Fi setup on a device with speakers.
  2. Enter your SSID and password and transmit the data as sound.
  3. Place the transmitting device near the Raspberry Pi microphone.
  4. If successful, you’ll hear an acknowledgment tone.
    • If decoding fails or credentials are incorrect, you’ll hear an error tone.

🚧 Note: ggwave is a work-in-progress feature and does not have any dialogs or provide on-screen feedback. 🚧

image

Step 5: Running OVOS

OVOS First Launch

Step 6: Using OVOS Commands

Helpful Commands

Once the terminal appears, you’ll see a guide with OVOS commands. Some key commands include:

You use the command ovos-help to print the message with all commands again at any point

Check Logs in Real-Time

Troubleshooting

Undervoltage Detected Warning

If you see an undervoltage detected warning:

Audio Issues

  1. Check Input Devices:
    • Run arecord -l to list all detected audio capture devices (microphones).
    • Example output: 
      **** List of CAPTURE Hardware Devices ****
card 1: Device [USB Audio Device], device 0: USB Audio [USB Audio]
  2. Check Output Devices:
    • Run aplay -l to list all detected audio playback devices (speakers).
    • Example output: 
      **** List of PLAYBACK Hardware Devices ****
card 1: Device [USB Audio Device], device 0: USB Audio [USB Audio]
  3. Verify Audio:
    • Record a short test file with arecord -D plughw:1,0 -f cd test.wav.
    • Play it back with aplay test.wav.

System Boot Issues

OVOS Fails to Speak “I am Ready”

STT tips and tricks

Saving Transcriptions

You can enable saving of recordings to file, this should be your first step to diagnose problems, is the audio inteligible? is it being cropped? too noisy? low volume?

set "save_utterances": true in your listener config, recordings will be saved to ~/.local/share/mycroft/listener/utterances

If the recorded audio looks good to you, maybe you need to use a different STT plugin, maybe the one you are using does not like your microphone, or just isn’t very good for your language

Wrong Transcriptions

If you consistently get specific words or utterances transcribed wrong, you can remedy around this to some extent by using the ovos-utterance-corrections-plugin

You can define replacements at word level ~/.local/share/mycroft/word_corrections.json

for example whisper STT often gets artist names wrong, this allows you to correct them

{
    "Jimmy Hendricks": "Jimi Hendrix",
    "Eric Klapptern": "Eric Clapton",
    "Eric Klappton": "Eric Clapton"
}

Silence Removal

By default OVOS applies VAD (Voice Activity Detection) to crop silence from the audio sent to STT, this helps in performance and in accuracy (reduces hallucinations in plugins like FasterWhisper)

Depending on your microphone/VAD plugin, this might be removing too much audio

set "remove_silence": false in your listener config, this will send the full audio recording to STT

Listen Sound

does your listen sound contain speech? some users replace the “ding” sound with words such as “yes?”

In this case the listen sound will be sent to STT and might negatively affect the transcription

set "instant_listen": false in your listener config, this will drop the listen sound audio from the STT audio buffer. You will need to wait for the listen sound to finish before speaking your command in this case

Enjoy your journey with RaspOVOS! With your Raspberry Pi set up, you can start exploring all the features of OpenVoiceOS.