Troubleshooting & Debug

Common errors, hardware permission configurations, and debug solutions for the WaveGo Whisper-bot platform.

📝 Major Development Issues & Solutions

Historical log of critical errors solved during Whisper-bot development:

Issue #1: Vosk InitializationSpeech-to-Text

Vosk Segmentation Fault on Startup

Root Cause

OpenBLAS thread allocation crashed when imported inside startup contexts (cron/systemd) due to CPU affinity limitations.

Working Solution

Prepend the environment variable constraint to the absolute top of the Python script before importing any bionic dog dependencies.

import os
os.environ['OPENBLAS_NUM_THREADS'] = '1'
import vosk

Issue #2: OS PersistenceRaspberry Pi OS

Vosk Files Reverting/Corrupting on Reboot

Root Cause

The Raspberry Pi was running an active Overlay File System (OverlayFS) which reset all system files in /home/rpi/.local to their read-only state on reboot.

Working Solution

Disable the overlay file system protection, remount partitions as read-write, edit config, and restart the system.

# Remount read-write, remove dtoverlay=overlayfs from /boot/config.txt, then:
sudo reboot

Issue #3: Library PathsPython Packages

Global Python Library Files Failing to Persist

Root Cause

The system root partition / remained protected, but the custom codebase folder /home/rpi/WaveGo was mounted on a separate, writable persistent partition.

Working Solution

Install vosk directly in the writable project directory using target parameters, and prepend it to the sys.path in webServer.py.

pip3 install --target=/home/rpi/WaveGo/vosk_package vosk

# In Python:
sys.path.insert(0, '/home/rpi/WaveGo/vosk_package')

Issue #4: Git MergeVersion Control

SyntaxError inside AudioToText.py

Root Cause

A git merge checkout left unresolved merge conflict markers (<<<<<<< Updated upstream) inside AudioToText.py on the Pi.

Working Solution

Discard the conflicted file local changes on the Pi and check out the clean source code from upstream, then re-apply directory patches.

git checkout -- whisper/AudioToText.py

Issue #5: Threading & ConcurrencyFlask Backend / Flutter App

First Voice Command Kicks Mobile App Offline

Root Cause

Flask runs single-threaded. The first AI command initializes Vosk, Embeddings, and Gemma3 (takes ~42s), which blocks the server's status polling loop, causing the mobile client to assume a disconnected state.

Working Solution

Modified _startStatusPolling in dashboard_screen.dart to ignore status poll failures when _chatLoading is true (waiting for models), and increased text request timeouts to 45 seconds.

Issue #6: SDK Version ConflictFlutter / Dart Build

Flutter Build Dependency Solving Failure

Root Cause

The project requested Dart SDK ^3.12.1 but the system is running Dart SDK 3.2.6, blocking asset generation.

Working Solution

Relaxed the environment SDK constraint in pubspec.yaml and downgraded conflicting linter rules packages.

environment:
  sdk: '>=3.2.0 <4.0.0'

dev_dependencies:
  flutter_lints: ^3.0.0

⚠️ Serial Port Access Denied (/dev/ttyS0)

Symptom / Logs:

serial open failed: [Errno 13] could not open port /dev/ttyS0: Permission denied: '/dev/ttyS0'
serial write failed: write failed: [Errno 5] Input/output error

Root Cause:

Access Restrictions: Linux reserves device serial lines for root or accounts belonging to the dialout group.
Port Locking: Raspberry Pi OS starts a background console login shell on the hardware serial lines by default, locking out user applications.

System Resolution Steps

Step 1: Grant User Serial Group Access

Run the following command in the Raspberry Pi shell to add your active user to the serial communication group:

sudo usermod -a -G dialout $USER

Note: You must reboot the Pi afterwards (sudo reboot) for the groups to reload.

Step 2: Disable Serial Terminal Console via raspi-config

Free up the serial port from the OS kernel console terminal:

Launch the raspi configuration utility: sudo raspi-config
Navigate to Interface Options (or Interfacing Options) > Serial Port.
Select No when asked: "Would you like a login shell to be accessible over serial?"
Select Yes when asked: "Would you like the serial port hardware to be enabled?"
Finish and reboot the Raspberry Pi.

Step 3: Permanent udev Device Rule (Fallback Option)

If permissions persist after reboot, configure a persistent udev rule to force global read-write permissions:

echo 'KERNEL=="ttyS0", MODE="0666"' | sudo tee /etc/udev/rules.d/99-serial.rules
sudo udevadm control --reload-rules && sudo udevadm trigger