Risoluzione dei problemi relativi alle chiamate WebRTC sui dispositivi Webex RoomOS

Introduzione

In questo documento viene descritta la risoluzione dei problemi di WebRTC in RoomOS e vengono descritte l'architettura, la diagnostica, la raccolta dei log e le tecniche di correlazione SSRC.

Prerequisiti

Requisiti

Cisco raccomanda la conoscenza dei seguenti argomenti:

• Architettura Cisco RoomOS e framework del browser WebEngine.
• Cisco Webex Control Hub: amministrazione dei dispositivi, profili di configurazione e analisi della risoluzione dei problemi.
• Analisi dell'acquisizione di pacchetti di rete tramite Wireshark per ispezionare i flussi SSRC e i formati di payload.

Componenti usati

Le informazioni fornite in questo documento si basano sulle seguenti versioni software e hardware:

• Cisco serie Room (Room Bar, Room Kit, Room Kit Pro, Room Kit EQ) con RoomOS 26.x o versioni successive
• Cisco serie Board (Board Pro 55/75, Board Pro G2) con RoomOS 26.x
• Serie Cisco Desk (Desk Pro, Desk Mini)
• Cisco Webex Control Hub
• Servizi di collaborazione WebRTC: Microsoft Teams Direct Guest Join (DGJ), Google Meet, Zoom WebRTC e Webex Instant Connect

Le informazioni discusse in questo documento fanno riferimento a dispositivi usati in uno specifico ambiente di emulazione. Su tutti i dispositivi menzionati nel documento la configurazione è stata ripristinata ai valori predefiniti. Se la rete è operativa, valutare attentamente eventuali conseguenze derivanti dall'uso dei comandi.

Premesse

Informazioni su WebRTC

WebRTC (Web Real-Time Communication) è uno standard open-source incorporato nei moderni browser Web. Consente lo streaming in tempo reale di video, audio e dati tra gli endpoint senza la necessità di plug-in proprietari.

• API JavaScript: Fornisce API standardizzate (ad esempio getUserMedia, RTCPeerConnection e RTCDataChannel) che interagiscono direttamente con l'hardware audio/video.
• Supporto Codec Nativo: Incapsula i moderni codec audio e video ad alta definizione, tra cui Opus, G.711, VP8, VP9 e H.264.
• Dipendenza plug-in zero: Elimina la necessità di componenti aggiuntivi, file eseguibili scaricabili dal desktop o privilegi di installazione amministrativa.

Funzionamento di WebRTC su Cisco RoomOS (WebEngine)

Nei dispositivi di collaborazione video Cisco con RoomOS, le applicazioni WebRTC non vengono eseguite come applicazioni firmware C/C++ compilate native. Vengono invece eseguiti all'interno dell'ambiente browser WebEngine incorporato, basato su un core Chromium ad alte prestazioni ottimizzato per l'hardware di elaborazione video Cisco.

Configurazione 

Per abilitare le funzionalità diagnostiche complete per le sessioni WebRTC e WebEngine sui dispositivi Cisco RoomOS, gli amministratori devono abilitare il debug remoto in Cisco Webex Control Hub o tramite l'interfaccia xAPI del dispositivo.

Passaggio 1: Abilita debug remoto WebEngine in Cisco Collaboration Control Hub

1. Accedere a Cisco Webex Control Hub.
2. Passare a Gestione > Dispositivi e selezionare l'endpoint video di destinazione.
3. Fare clic su Tutte le configurazioni nel pannello a destra.
4. Cercare WebEngine e individuare il parametro RemoteDebugging.
5. Impostare WebEngine RemoteDebugging su On e fare clic su Salva.

In alternativa, abilitare il debug remoto direttamente tramite l'interfaccia CLI (Command Line Interface) del dispositivo:

xConfiguration WebEngine RemoteDebugging: On
xConfiguration WebEngine Features WebRTC: On

Passaggio 2: Verifica

Utilizzare questa sezione per verificare che WebEngine sia correttamente inizializzato e stia elaborando attivamente i canali multimediali WebRTC durante una chiamata.

Eseguire i comandi xStatus tramite il terminale mentre è in corso una riunione WebRTC:

xStatus WebEngine
xStatus WebRTC MediaChannels

Tabella 1: Descrive i campi operativi chiave restituiti dal comando di stato WebRTC:

Parametro xStatus	Stato previsto	Descrizione e impatto della diagnostica
Stato WebEngine	In esecuzione	Indica se il nucleo del browser Chromium è attivo e se è in corso il rendering.
Client MediaChannels WebRTC	Attivo/Connesso	Indica il trasporto multimediale attivo tra il codec e il bridge di supporti cloud.
Direzione	In uscita/In entrata	Identifica se il canale multimediale rappresenta la trasmissione della telecamera/microfono locale o la ricezione video remota.
BitrateDestinazione	1500000 bps (1,5 Mbps)	Larghezza di banda di destinazione allocata da WebEngine in base alla capacità di rete disponibile.

Risoluzione dei problemi

In questa sezione vengono fornite procedure complete e dettagliate per la risoluzione dei problemi, istruzioni per la raccolta dei log e tecniche di correlazione del flusso di supporti SSRC per problemi WebRTC.

1. Raccolta dei log da WebEngine e interfaccia touch

Quando si verifica un problema di qualità o di connessione durante una chiamata WebRTC attiva, eseguire la procedura direttamente dal pannello Cisco Room Navigator/Touch 10. Durante la riunione WebRTC attiva, toccare il menu di controllo del dispositivo e selezionare Impostazioni.

1. Passare a Problemi e diagnostica.
2. Attiva la registrazione estesa su ON. (La registrazione estesa registra i timestamp dei pacchetti ad alta risoluzione, i rapporti mittente/destinatario RTCP e le statistiche dei flussi multimediali).
3. Subito dopo la riproduzione del problema audio/video, selezionare Send WebRTC Logs.

Una volta caricati correttamente i log nel cloud Cisco, l'interfaccia genera due identificatori di rilevamento univoci:

• ID WebRTC: Questo identificatore è formattato specificamente per i provider di servizi di conferenza di terze parti (ad esempio, Microsoft Support for Teams Direct Guest Join o Google Cloud Support for Google Meet). Fornire questo ID quando si apre una richiesta di assistenza con il provider di hosting.

• ID registro/ID feedback: Questo identificatore è indicizzato in Cisco Webex Control Hub. I tecnici Cisco TAC utilizzano questo ID registro per individuare, decrittografare e analizzare l'intero bundle di diagnostica del sistema di endpoint.

ID registro: L'ID registro può essere utilizzato per cercare nei registri e scaricarli per risolvere i problemi o aprire una richiesta con TAC. I log possono essere scaricati direttamente in Collaboration Control Hub e raccolti utilizzando l'ID log/ID feedback o l'ID riunione nella sezione risoluzione dei problemi.

 

2. Mappatura dei flussi multimediali e identificazione SSRC (xStatus Correlation)

Nelle architetture Real-Time Transport Protocol (RTP) e WebRTC, un SSRC (Synchronization Source) è un identificatore numerico a 32 bit critico che etichetta l'origine di un flusso multimediale. I ricevitori utilizzano la SSRC per sequenziare i pacchetti, calcolare il tremolio e sincronizzare l'audio con il video.

Per mappare uno specifico flusso video o audio tra i registri xStatus del dispositivo e un'acquisizione di pacchetti Wireshark, convertire l'ID canale decimale da xstatus.txt nel relativo equivalente esadecimale:

(416917557)10  =  (0x18D9A835)16

Wireshark Display Filter: rtp.ssrc== 0x18D9A835

Il frammento di log illustra un canale video in uscita WebRTC in diretta estratto da un file di diagnostica xstatus.txt dell'endpoint:

*s WebRTC MediaChannels Client Channel 7 Direction: Incoming
*s WebRTC MediaChannels Client Channel 7 Id: "IT01V416917557"
*s WebRTC MediaChannels Client Channel 7 Netstat BytesSent: 89661904
*s WebRTC MediaChannels Client Channel 7 Netstat PacketsSent: 84431
*s WebRTC MediaChannels Client Channel 7 QualityLimitation NetworkBandwidthLimited: 50
*s WebRTC MediaChannels Client Channel 7 QualityLimitation NotLimited: 497
*s WebRTC MediaChannels Client Channel 7 TargetBitrate: 1500000
*s WebRTC MediaChannels Client Channel 7 Transport RTCP Local IpAddress: "<Local IP Address>"
*s WebRTC MediaChannels Client Channel 7 Transport RTCP Local Port: 1742
*s WebRTC MediaChannels Client Channel 7 Transport RTCP Local Protocol: UDP
*s WebRTC MediaChannels Client Channel 7 Transport RTCP Remote IpAddress: "<Server IP Address>"
*s WebRTC MediaChannels Client Channel 7 Transport RTCP Remote Port: 3478
*s WebRTC MediaChannels Client Channel 7 Transport RTCP Remote Protocol: UDP
*s WebRTC MediaChannels Client Channel 7 Type: Video
*s WebRTC MediaChannels Client Channel 7 Video EncoderImplementation: "ExternalEncoder"
*s WebRTC MediaChannels Client Channel 7 Video FrameHeight: 540
*s WebRTC MediaChannels Client Channel 7 Video FrameWidth: 960
*s WebRTC MediaChannels Client Channel 7 Video FramesPerSecond: 30
*s WebRTC MediaChannels Client Channel 7 Video Protocol: "video/VP8"

Principali strumenti di diagnostica da questa analisi del canale multimediale:

• Correlazione SSRC: Il suffisso ID canale "416917557" rappresenta SSRC 0x18D9A835. Il filtro di Wireshark per SSRC isola tutti i pacchetti video in uscita.
• Trasporto e relè: L'endpoint locale (<Indirizzo IP locale>) comunica direttamente con un server remoto Google STUN/TURN (Indirizzo server IP pubblico sulla porta UDP 3478).
• Risoluzione e codec: Lo streaming viene codificato attivamente utilizzando VP8 ad accelerazione hardware con risoluzione 960x540 a 30 frame al secondo.
• Contatore Limitazione Qualità: Il contatore QualityLimitation NetworkBandwidthLimited di 50 indica che l'algoritmo di controllo della congestione WebEngine ha ridotto la risoluzione a causa di vincoli transitori di larghezza di banda a monte.

3. Risoluzione avanzata dei problemi di Cisco Webex Control Hub

Gli amministratori possono analizzare le metriche delle riunioni WebRTC in tempo reale e cronologiche direttamente in Cisco Webex Control Hub:

1. Passare a Control Hub > Risoluzione dei problemi > Riunioni e chiamate.
2. Filtrare in base all'indirizzo MAC, al numero di serie, al nome del dispositivo o all'ID di registro dell'endpoint.

    

    
3. Selezionare la sessione di riunione di destinazione dai risultati della ricerca cronologica.
4. Esaminate i grafici di telemetria hop-by-hop in tempo reale: Perdita di pacchetti (audio/video), buffer di jitter, latenza (RTT) e scala dinamica della risoluzione.

 

 

Tabella 2: Modalità di errore e matrice di correzione comuni di WebRTC

Sintomo	Probabile causa principale	Verifica diagnostica	Passaggio di risoluzione
La chiamata non riesce ad unirsi/ruota continuamente	Porte UDP STUN/TURN in uscita bloccate dal firewall (3478, 5004-65535)	Wireshark visualizza le richieste di binding STUN ripetute senza risposte di binding	Apre le porte UDP in uscita negli intervalli IP multimediali del provider WebRTC.
Blocco audio/video unidirezionale	Timeout NAT o UDP simmetrico su firewall aziendale con stato	xStatus mostra QualityLimitation NetworkBandwidthLimited che aumenta rapidamente	Timeout stato UDP configurazione firewall >= 60 secondi; abilitare i pacchetti keepalive STUN.
Schermo nero o crash su USB-C BYOM	Negoziazione in modalità alternativa DisplayPort non riuscita su cavo non certificato	messages.log mostra il timeout della negoziazione dell'alimentazione USB del kernel	Utilizzare un cavo di tipo C a 10 Gb/s con certificazione USB-IF; impostare Video Output Connector MonitorRole su Auto.

Informazioni correlate

• Guida di riferimento ai comandi di Cisco RoomOS (configurazione xAPI e WebEngine)
• Gestione dispositivi in Cisco Collaboration Hub
• Informazioni di riferimento sull'API Webrtc
• Procedure ottimali per WebEngine

Cronologia delle revisioni

Revisione	Data di pubblicazione	Commenti
1.0	20-Oct-2026	Versione iniziale