Zum Inhalt

Troubleshooting - TC100 Display

Lösungen für häufige Probleme mit der Display-Integration.

Schnelldiagnose

Schritt 1: Display erreichbar?

ping 192.168.178.48

✅ Erfolg: Display antwortet
❌ Fehler: Display nicht im Netzwerk

Schritt 2: WebUI aufrufbar?

open http://192.168.178.48

✅ Erfolg: WebUI lädt
❌ Fehler: Netzwerk-Probleme

Schritt 3: Backend konfiguriert?

cat backend/.env | grep DISPLAY

Erwartete Ausgabe: 

DISPLAY_ENABLED=true
DISPLAY_IP=192.168.178.48

❌ Fehler: Backend-Konfiguration

Schritt 4: Backend neu gestartet?

docker compose logs backend | grep -i display | tail -5

Erwartete Ausgabe: 

Display Service aktiviert: http://192.168.178.48
Display Bridge aktiviert

❌ Fehler: Backend-Integration

Häufige Probleme

Display nicht erreichbar

Symptome

  • ping schlägt fehl
  • WebUI nicht erreichbar
  • Backend-Logs: "Display timeout"

Ursachen & Lösungen

Ursache 1: IP-Adresse falsch

Prüfen: 

# Router aufrufen
# Nach "Ulanzi" oder MAC 94:FD:8C suchen

Lösung: 

# Korrekte IP in .env eintragen
nano backend/.env
# DISPLAY_IP=192.168.xxx.xxx (neue IP)

# Backend neu starten
docker compose restart backend

Ursache 2: Display ausgeschaltet

Prüfen: - Power-Button am Display gedrückt? - USB-C Kabel angeschlossen? - Batterie leer?

Lösung: 

# Display einschalten (Power-Button 3 Sekunden halten)
# Oder USB-C anschließen

Ursache 3: WiFi-Verbindung verloren

Prüfen: - Display zeigt "WiFi" Symbol? - Router erreichbar?

Lösung: 

# Display neu starten
# Power-Button 5 Sekunden halten (Neustart)

# WiFi neu konfigurieren:
# 1. Mittleren Button 3× drücken
# 2. WebUI öffnen (Fallback-IP)
# 3. Settings → Network → WiFi

Ursache 4: Firewall blockiert

Prüfen: 

# Firewall-Regeln prüfen (macOS)
sudo /usr/libexec/ApplicationFirewall/socketfilterfw --listapps

# Oder Firewall temporär deaktivieren
sudo /usr/libexec/ApplicationFirewall/socketfilterfw --setglobalstate off

Lösung: - Port 80 (HTTP) für Display freigeben - Oder Firewall-Ausnahme für Display-IP

Backend sendet keine Updates

Symptome

  • Display zeigt nichts
  • Backend-Logs zeigen keine Display-Requests
  • Manuelle curl-Tests funktionieren

Ursachen & Lösungen

Ursache 1: DISPLAY_ENABLED=false

Prüfen: 

cat backend/.env | grep DISPLAY_ENABLED

Lösung: 

echo "DISPLAY_ENABLED=true" >> backend/.env
docker compose restart backend

Ursache 2: Backend nicht neu gestartet

Prüfen: 

docker compose logs backend | grep "Display Service" | tail -1

Erwartung: Zeitstempel ist aktuell (nach .env-Änderung)

Lösung: 

docker compose restart backend

# Warten bis "Display Service aktiviert" erscheint
docker compose logs -f backend | grep -i display

Ursache 3: Keine WebSocket-Events

Prüfen: 

# WebSocket-Verbindungen prüfen
docker compose logs backend | grep -i websocket | tail -10

Lösung: - Frontend-Verbindung prüfen - Browser-Console öffnen (F12) - WebSocket-Fehler checken - Frontend neu laden

Ursache 4: Display-Bridge nicht importiert

Prüfen: 

docker compose logs backend | grep "Display Bridge"

Erwartung: "Display Bridge aktiviert"

Lösung: 

# Code prüfen
cat backend/app/websocket/manager.py | grep display_bridge

# Falls Import fehlt: Manuelle Integration nötig

Display zeigt falsche Daten

Symptome

  • Alte Daten werden angezeigt
  • Notifications verschwinden nicht
  • Indicators falsch gefärbt

Ursachen & Lösungen

Ursache 1: Cache nicht geleert

Lösung: 

# Display neu starten
curl -X POST http://192.168.178.48/api/power \
  -H "Content-Type: application/json" \
  -d '{"power":false}'

sleep 5

curl -X POST http://192.168.178.48/api/power \
  -H "Content-Type: application/json" \
  -d '{"power":true}'

Ursache 2: Notification auf 'hold'

Symptom: Notification bleibt stehen

Lösung: 

# Mittleren Button am Display drücken
# Oder via API löschen:
curl -X POST http://192.168.178.48/api/notify \
  -H "Content-Type: application/json" \
  -d '{"text":""}'  # Leere Notification

Ursache 3: Custom App aktiv

Symptom: Solar-Status wird nicht aktualisiert

Lösung: 

# Custom App entfernen
curl -X DELETE http://192.168.178.48/api/custom/solar

# Backend nutzt jetzt /api/notify

Ursache 4: Zeitzone falsch

Symptom: Tagesproduktion (kWh) resettet zur falschen Zeit

Lösung: 

# WebUI öffnen
open http://192.168.178.48

# Settings → Time → Timezone
# Setzen auf: Europe/Berlin

Fehler in Backend-Logs

"Display timeout"

ERROR: Display request failed: TimeoutException

Lösung:

Timeout erhöhen 
# backend/app/services/display_service.py

self.timeout = httpx.Timeout(
    connect=5.0,   # Statt 2.0
    read=10.0,     # Statt 5.0
    write=10.0     # Statt 5.0
)

docker compose restart backend
Netzwerk prüfen 
# Ping-Zeit messen
ping -c 5 192.168.178.48

# Sollte < 100ms sein
# Falls > 500ms: WiFi-Probleme

"Connection refused"

ERROR: Display not reachable: Connection refused

Lösung:

Port prüfen 
# Port 80 erreichbar?
nc -zv 192.168.178.48 80

# Erwartung: "succeeded!"
AWTRIX3 läuft? 
# WebUI öffnen
open http://192.168.178.48

# Falls nicht: Display neu flashen
# https://blueforcer.github.io/awtrix3/#/flasher

"404 Not Found"

ERROR: Endpoint not found: /api/custom/solar

Lösung:

Endpoint gewechselt 
# backend/app/services/display_service.py

# ALT (funktioniert nicht):
# endpoint = "/api/custom/solar"

# NEU (korrekt):
endpoint = "/api/notify"

Fixed in aktueller Version!

WebUI-Probleme

WebUI lädt nicht

Lösung:

Browser-Cache leeren 
# Chrome/Safari
Cmd + Shift + R  # Hard Reload

# Oder Incognito-Modus
Cmd + Shift + N
Display neu starten 
# Power-Button 5 Sekunden halten
# Warten bis Logo erscheint

Settings werden nicht gespeichert

Lösung:

Firmware-Update 
# WebUI → Update → Check for Update
# Falls neue Version: Installieren

# Oder manuell:
# https://blueforcer.github.io/awtrix3/#/firmware
Factory Reset 
# WebUI → Settings → Factory Reset
# WARNUNG: Alle Einstellungen gelöscht!

# Danach neu konfigurieren

Debugging-Tools

Backend-Logs durchsuchen

# Alle Display-Logs
docker compose logs backend | grep -i display

# Nur Fehler
docker compose logs backend | grep -i "display.*error"

# Live-Modus
docker compose logs -f backend | grep -i display

# Letzte 50 Zeilen
docker compose logs --tail=50 backend | grep -i display

Display-Status abfragen

# Vollständiger Status
curl http://192.168.178.48/api/stats | python3 -m json.tool

# Nur wichtige Werte
curl -s http://192.168.178.48/api/stats | \
  python3 -c "import sys,json; s=json.load(sys.stdin); \
  print(f'🔋 {s[\"bat\"]}% | 📶 {s[\"wifi_signal\"]}dBm | 🌡️ {s[\"temp\"]}°C')"

Test-Script ausführen

# Vollständiger Test
cat > /tmp/test_display.py << 'EOF'
import asyncio
import sys
sys.path.insert(0, '/app')
from app.services.display_service import DisplayService

async def test():
    display = DisplayService('192.168.178.48', True)

    tests = [
        ("Notification", display.send_notification(text="Test 1")),
        ("Solar Status", display.update_solar_status(3200, 8.5, 2, 2)),
        ("Indicator", display.set_indicator(1, [0,255,0], fade=1000)),
        ("Stats", display.get_stats())
    ]

    for name, coro in tests:
        try:
            result = await coro
            print(f"✅ {name}: OK")
        except Exception as e:
            print(f"❌ {name}: {e}")

asyncio.run(test())
EOF

docker cp /tmp/test_display.py solarlog-backend:/tmp/
docker exec solarlog-backend python /tmp/test_display.py

Netzwerk-Analyse

# Traceroute zum Display
traceroute 192.168.178.48

# Packet-Loss Test
ping -c 100 192.168.178.48 | grep "packet loss"

# Port-Scan
nmap -p 80,443 192.168.178.48

Erweiterte Probleme

Performance-Probleme

Symptome

  • Display reagiert verzögert
  • Backend-Logs zeigen lange Response-Zeiten
  • Indicators laggen

Lösungen

Request-Rate reduzieren 
# backend/app/services/display_bridge.py

# Rate-Limiting hinzufügen
import time

class DisplayBridge:
    _last_update = 0
    MIN_INTERVAL = 1.0  # Max 1 Update/Sekunde

    async def handle_production_data(data: dict):
        now = time.time()
        if now - self._last_update < self.MIN_INTERVAL:
            return  # Skip Update

        self._last_update = now
        # ... rest of code
Batch Updates 
# Indicators parallel statt sequentiell
await asyncio.gather(
    display.set_indicator(1, [0,255,0]),
    display.set_indicator(2, [0,255,0]),
    display.set_indicator(3, [0,255,0])
)

Batterie-Probleme

Symptome

  • Display schaltet sich aus
  • Batterie lädt nicht
  • Batterie-% sinkt schnell

Lösungen

Helligkeit reduzieren 
# WebUI → Settings → Matrix → Brightness
# Day: 100 (statt 150)
# Night: 20 (statt 30)
USB-C Power 
# Display dauerhaft an USB-C anschließen
# Batterie wird geschont
Auto-Brightness 
# WebUI → Settings → Matrix
# Auto-Brightness: ON
# Nutzt Lichtsensor

WiFi-Instabilität

Symptome

  • Display verliert Verbindung
  • WiFi-Signal schwach (<-70 dBm)
  • Häufige Reconnects

Lösungen

Statische IP 
# WebUI → Settings → Network
# DHCP: OFF
# Static IP: 192.168.178.48
# Gateway: 192.168.178.1
# DNS: 192.168.178.1
WiFi-Kanal wechseln 
# Router-Einstellungen
# 2.4 GHz: Kanal 1, 6, oder 11
# 5 GHz nicht unterstützt von TC100!
Repeater verwenden 
# Falls Display zu weit von Router
# WiFi-Repeater in der Nähe platzieren

Logs & Diagnostics

Backend Debug-Modus

# .env erweitern
echo "LOG_LEVEL=DEBUG" >> backend/.env
docker compose restart backend

# Debug-Logs anzeigen
docker compose logs -f backend | grep -E "(DEBUG|display)"

Display Console-Logs

# WebUI öffnen
open http://192.168.178.48

# Rechts oben: Console
# Zeigt:
# - API Requests
# - Fehler
# - WiFi Events

Wireshark Network Capture

# Traffic zum Display mitschneiden
sudo tcpdump -i en0 host 192.168.178.48 -w display.pcap

# In Wireshark öffnen
wireshark display.pcap

Factory Reset

Display zurücksetzen

Achtung

Alle Einstellungen werden gelöscht!

Via WebUI

# WebUI öffnen
open http://192.168.178.48

# Settings → Advanced → Factory Reset
# Button klicken → Bestätigen

Via Hardware

# 1. Display ausschalten (Power-Button)
# 2. Alle 3 Buttons gleichzeitig gedrückt halten
# 3. Power-Button drücken (weiter halten)
# 4. Warten bis "Reset" erscheint
# 5. Alle Buttons loslassen

Backend zurücksetzen

# Display-Konfiguration entfernen
sed -i '' '/DISPLAY_/d' backend/.env

# Backend neu starten
docker compose restart backend

# Prüfen
docker compose logs backend | grep -i display
# Sollte leer sein

Kontakt & Support

AWTRIX3 Community

SolarLog Support

  • GitHub Issues: [repository]/issues
  • Dokumentation: Diese Seite
  • Logs: docker compose logs backend

Checkliste vor Support-Anfrage

Bitte prüfen Sie:

  • Display ist eingeschaltet und im Netzwerk
  • WebUI ist erreichbar (http://192.168.178.48)
  • Backend .env enthält DISPLAY_ENABLED=true
  • Backend wurde nach Änderungen neu gestartet
  • Test-Script wurde ausgeführt (siehe Debugging-Tools)
  • Backend-Logs wurden geprüft (keine Fehler)
  • Display-Firmware ist aktuell (≥ 0.96)
  • Factory Reset wurde versucht (falls hartnäckige Probleme)

Logs sammeln:

# Backend-Logs
docker compose logs backend > backend_logs.txt

# Display-Status
curl http://192.168.178.48/api/stats > display_stats.json

# System-Info
uname -a > system_info.txt
docker --version >> system_info.txt

Zurück zur Übersicht: