Advanced Troubleshooting

Packet Capture Analysis

Analyzing Matter network traffic provides deep visibility into communication issues. Matter uses encrypted communication, but metadata analysis can reveal problems.

Capture Setup

Capture Points:
  Wi-Fi Traffic:
    Tool: Wireshark with monitor mode
    Filter: "udp port 5540" (Matter default)
    Location: Near access point or device
    
  Thread Traffic:
    Tool: Thread Border Router packet capture
    Access: Via Thread diagnostic interface
    Format: PCAP for analysis

Wi-Fi Capture Configuration (Linux):
  # Enable monitor mode
  sudo airmon-ng start wlan0
  
  # Capture Matter traffic
  sudo wireshark -k -f "udp port 5540" -i wlan0mon

Analyzing Captures

Key Metrics to Analyze:
  
  Message Rates:
    - Commands per second
    - Response times
    - Retransmission count
    
  Addressing:
    - IPv6 addresses involved
    - mDNS queries/responses
    - Multicast group membership
    
  Session Security:
    - CASE session establishment
    - Session resumption
    - Encryption handshake success/failure

Common Patterns

# Normal command flow
Time    Source          Dest            Protocol    Info
0.000   Controller      Device          MATTER      InvokeCommand (OnOff.On)
0.015   Device          Controller      MATTER      InvokeCommandResponse (success)

# Retransmission issue
Time    Source          Dest            Protocol    Info
0.000   Controller      Device          MATTER      InvokeCommand (OnOff.On)
0.100   Controller      Device          MATTER      Retransmission
0.200   Controller      Device          MATTER      Retransmission
0.300   Controller      Device          MATTER      Retransmission
0.400   Controller      Device          MATTER      Timeout

# Session establishment failure
Time    Source          Dest            Protocol    Info
0.000   Controller      Device          MATTER      CASE Sigma1
0.050   Device          Controller      MATTER      CASE Sigma2
0.100   Controller      Device          MATTER      CASE Sigma3
0.150   Device          Controller      MATTER      CASE Sigma3 (responder) - FAILURE

Wireshark Filters

# Matter-specific Wireshark display filters
matter.traffic: "udp.port == 5540"
matter.mdns: "dns.resp.name contains \"_matter\" or dns.resp.name contains \"_matterc\""
# Note: _matter._tcp is the operational service; _matterc._tcp is used during commissioning
matter.ipv6: "ipv6 and udp.port == 5540"

# Troubleshooting filters
retransmissions: "ip.flags.df == 0 and udp.port == 5540"  # UDP retransmission heuristic
high_latency: "frame.time_delta > 0.1"
# Note: matter.status is not a built-in Wireshark field; filter by UDP payload content instead

Log Interpretation

Controller Logs

# Apple HomeKit controller logs (macOS)
Location: ~/Library/Logs/com.apple.Home/
Key Files:
  - Home.log: General operations
  - HomeSharing.log: Multi-user access
  - com.apple.homed.log: Core daemon

# Google Home controller logs
Access: Google Home app → Settings → Device Information
Key Events:
  - Commissioning attempts
  - Command responses
  - Network changes

# Home Assistant logs
Location: /config/home-assistant.log
Filter: "matter" or device name

Device Logs

For Prolicht Matter devices, diagnostic logs can be accessed:

# Via Matter diagnostic cluster
Cluster: 0x0032 (General Diagnostics)
Attributes:
  - NetworkInterfaces: Network state
  - RebootCount: Number of reboots
  - UpTime: Seconds since boot
  - TotalOperationalHours: Lifetime hours
  
Events:
  - BootReason: Why device restarted
  - HardwareFaultChange: Hardware issues
  - RadioFaultChange: RF problems
  - NetworkFaultChange: Connectivity issues

# Retrieving diagnostic data
Command: ReadAttribute
Endpoint: 0
Cluster: General Diagnostics (0x0032)

Log Analysis Examples

# Successful commissioning
[INFO] Commissioning started for device AA:BB:CC:DD:EE:FF
[DEBUG] PASE session established
[INFO] Device attestation verified
[INFO] Operational credentials provisioned
[INFO] Commissioning complete

# Commissioning failure - wrong network
[INFO] Commissioning started for device AA:BB:CC:DD:EE:FF
[DEBUG] PASE session established
[ERROR] Network commissioning failed: 0x02 (NetworkNotFound)
[INFO] Device not on target network

# Intermittent connectivity
[WARN] Device light-office-001 unresponsive
[DEBUG] Ping timeout after 3000ms
[INFO] Device recovered after 15 seconds
[WARN] This is the 3rd occurrence in 24 hours

Performance Monitoring Tools

Built-in Diagnostics

Matter Controller Diagnostics:
  
  Device Status:
    Command: ReadAttribute
    Cluster: Basic Information (0x0028)
    Attributes:
      - Reachable: Boolean connectivity
      - LastChanged: Timestamp of state change
      
  Network Diagnostics:
    Cluster: Network Diagnostics (0x0036)
    Attributes:
      - WiFiRSSI: Signal strength
      - WiFiChannel: Current channel
      - ThreadRole: Router/End Device/Child
      
  Thread Diagnostics:
    Cluster: Thread Network Diagnostics (0x0035)
    Attributes:
      - NeighborTable: Connected devices
      - RouteTable: Mesh routing paths
      - PartitionId: Network partition status

Network Monitoring

Wi-Fi Monitoring:
  Tools:
    - Ubiquiti Network Controller
    - Cisco Prime Infrastructure
    - Aruba Central
    
  Metrics:
    - Client RSSI per device
    - Channel utilization
    - Retry rates
    - Roaming events
    
Thread Monitoring:
  Tools:
    - Thread Border Router CLI
    - OpenThread diagnostic commands
    - Mesh topology visualization
    
  Commands:
    # Thread network diagnostics
    ot-ctl networkname
    ot-ctl leaderdata
    ot-ctl childtable
    ot-ctl neighbor

Performance Baselines

Expected Performance:
  
  Command Latency:
    On/Off: < 100ms
    Brightness: < 150ms
    Color: < 200ms
    
  Network Metrics:
    WiFi RSSI: > -70 dBm
    WiFi Retry Rate: < 5%
    Thread LQI: > 100
    
  Availability:
    Uptime: > 99.9%
    Response Rate: > 99%
    
Alert Thresholds:
  - Latency > 500ms
  - RSSI < -75 dBm
  - Retry rate > 10%
  - Packet loss > 1%

Debugging Methodology

Systematic Approach

┌─────────────────────────────────────────────────────────────┐
│                    1. DEFINE THE PROBLEM                     │
│         What exactly is not working? When? Pattern?          │
└─────────────────────────────┬───────────────────────────────┘
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                    2. GATHER INFORMATION                     │
│         Logs, device status, network state, recent changes   │
└─────────────────────────────┬───────────────────────────────┘
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                    3. IDENTIFY SCOPE                         │
│         Single device? Multiple? All? Specific location?     │
└─────────────────────────────┬───────────────────────────────┘
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                    4. HYPOTHESIZE                             │
│         What is the most likely cause based on evidence?     │
└─────────────────────────────┬───────────────────────────────┘
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                    5. TEST & ISOLATE                          │
│         Change one variable at a time, verify results        │
└─────────────────────────────┬───────────────────────────────┘
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                    6. RESOLVE & DOCUMENT                      │
│         Apply fix, verify resolution, document for future    │
└─────────────────────────────────────────────────────────────┘

Diagnostic Commands

# Device connectivity check
1. Read Basic Information cluster
   - Confirm device responds
   - Check reachable attribute
   
2. Read Network Diagnostics cluster
   - Verify RSSI is acceptable
   - Check for network errors
   
3. Test command execution
   - Send OnOff toggle
   - Verify response time

# Network health check
1. Ping test to device IP
2. mDNS resolution test
3. Matter unicast test
4. Matter multicast test

Isolation Techniques

Isolate Device:
  1. Move device closer to hub/AP
  2. Test with different power source
  3. Factory reset and re-commission
  4. Test in isolation (different network)
  
Isolate Network:
  1. Test with mobile hotspot
  2. Disable other 2.4 GHz devices
  3. Change Wi-Fi channel
  4. Test with wired hub connection
  
Isolate Controller:
  1. Test with different controller app
  2. Test with different phone/tablet
  3. Test with different hub (if available)
  4. Remove and re-add device

Common Error Codes

Commissioning Errors

Network Errors

Operational Errors

Thread-Specific Errors

Escalation Procedures

Internal Escalation Levels

Level 1 - Self-Service:
  Resources:
    - Documentation and guides
    - FAQ and known issues
    - Community forums
  Response: Immediate
  Scope: Common issues, configuration errors

Level 2 - Technical Support:
  Contact: [email protected]
  Response: 4-24 hours
  Scope: Device failures, persistent issues
  Required Info:
    - Device model and firmware version
    - Controller type and version
    - Network configuration
    - Steps already attempted

Level 3 - Engineering:
  Contact: Via Level 2 escalation
  Response: 24-72 hours
  Scope: Bugs, firmware issues, security concerns
  Required Info:
    - Full diagnostic logs
    - Packet captures (if applicable)
    - Reproduction steps

Information to Collect

Before Contacting Support:

Device Information:
  □ Model number
  □ Serial number
  □ Firmware version
  □ Hardware revision
  
Network Information:
  □ Router make/model
  □ Wi-Fi configuration (channel, security)
  □ Thread network status (if applicable)
  □ Network diagram
  
Controller Information:
  □ Hub type and model
  □ Controller app version
  □ Phone/tablet OS version
  
Issue Details:
  □ Exact error messages
  □ When issue started
  □ Frequency of occurrence
  □ Steps to reproduce
  □ Recent changes to network
  
Diagnostic Data:
  □ Controller logs
  □ Device diagnostic cluster data
  □ Packet capture (if available)
  □ Screenshots of errors

When to Contact Support

Immediate Escalation Required

• Security vulnerability discovered
• Device physical damage or safety concern
• Complete network failure affecting operations
• Data loss or corruption

Standard Support Request

• Persistent connectivity issues after troubleshooting
• Device not functioning as documented
• Unexpected behavior after firmware update
• Feature requests or enhancement suggestions

Warranty and RMA

• Device hardware failure
• Manufacturing defects
• DOA (Dead on Arrival) devices

RMA Process:
  1. Contact support with device details
  2. Provide proof of purchase
  3. Receive RMA number
  4. Ship device to service center
  5. Replacement or repair within 14 days

For security-related issues, see our Security Hardening guide.