Debug Thread Network

Comprehensive toolkit for debugging Thread mesh networks and OpenThread Border Routers.

Quick Start

Run the main diagnostic script to test connectivity and gather network information:

scripts/test_thread_connectivity.sh <border-router-ip>

Example:

scripts/test_thread_connectivity.sh 192.168.50.104

Core Scripts

1. Thread Connectivity Test (

scripts/test_thread_connectivity.sh

)

Purpose: Comprehensive connectivity test for Thread Border Router

Usage:

scripts/test_thread_connectivity.sh <border-router-ip>

What it tests:

• ICMP reachability (ping)
• HTTP REST API accessibility
• IPv6 Router Advertisement reception
• Thread network status
• Border Router configuration

Output: Summary report with pass/fail status for each test

2. IPv6 Diagnostics (

scripts/ipv6_diagnostics.sh

)

Purpose: Gather complete IPv6 configuration and routing information

Usage:

scripts/ipv6_diagnostics.sh [interface]

Collects:

• IPv6 addresses on all interfaces
• IPv6 routing table
• Neighbor Discovery cache
• Router Advertisement prefixes
• Default routers

Output: Formatted diagnostic report

3. Border Router API Query (

scripts/query_otbr_api.sh

)

Purpose: Query OpenThread Border Router REST API endpoints

Usage:

scripts/query_otbr_api.sh <border-router-ip> [port]

Endpoints queried:

• /get_properties

  - Network properties

• /node_information

  - Node details

• /topology

  - Network topology

• /diagnostics

  - Full diagnostic info

• /node/dataset/active

  - Thread credentials

Output: JSON responses from each endpoint

4. Thread Network Data Decoder (

scripts/decode_thread_netdata.py

)

Purpose: Decode Thread Network Data hex string into human-readable format

Usage:

scripts/decode_thread_netdata.py <netdata-hex>

Or pipe from API:

curl -s http://192.168.50.104/diagnostics | \
  jq -r '.[0].NetworkData' | \
  scripts/decode_thread_netdata.py

Decodes:

• Prefix TLVs with IPv6 prefixes
• Border Router sub-TLVs with flags
• Has Route sub-TLVs
• Service TLVs

Output: Structured TLV analysis with prefix flags

5. RA Packet Analyzer (

scripts/analyze_ra_packet.sh

)

Purpose: Capture and analyze Router Advertisement packets

Usage:

sudo scripts/analyze_ra_packet.sh <interface>

Captures:

• Router Advertisement packets
• Prefix Information Options (PIO)
• Route Information Options (RIO)
• Router lifetime and flags

Output: Parsed RA packet details

Common Workflows

Workflow 1: Initial Border Router Discovery

When you know the network but not the border router IP:

# Scan for Thread Border Routers on network
scripts/scan_for_otbr.sh 192.168.1

Workflow 2: Full Network Diagnostic

When troubleshooting connectivity issues:

# Step 1: Test connectivity
scripts/test_thread_connectivity.sh 192.168.50.104

# Step 2: Check IPv6 configuration
scripts/ipv6_diagnostics.sh en0

# Step 3: Query Border Router
scripts/query_otbr_api.sh 192.168.50.104

# Step 4: Analyze Router Advertisements
sudo scripts/analyze_ra_packet.sh en0

Workflow 3: Decode Thread Network Configuration

When analyzing Thread network prefixes and routes:

# Get Network Data and decode
curl -s http://192.168.50.104/diagnostics | \
  jq -r '.[0].NetworkData' | \
  scripts/decode_thread_netdata.py

Workflow 4: Test OMR Address Reachability

When verifying external connectivity to Thread devices:

# Get OMR addresses from border router
OMR_ADDR=$(curl -s http://192.168.50.104/diagnostics | \
  jq -r '.[0].IP6AddressList[] | select(startswith("fd03"))')

# Test connectivity
ping6 -c 3 $OMR_ADDR

# Test HTTP over IPv6
curl -s "http://[$OMR_ADDR]/get_properties" | jq

Reference Documentation

Thread Address Types

For detailed explanation of Thread IPv6 addressing, see references/thread-addressing.md

Router Advertisement Analysis

For RA packet structure and interpretation, see references/router-advertisements.md

OpenThread Border Router API

For complete API documentation, see references/otbr-api.md

Troubleshooting Guide

Border Router Not Responding

1. Check network connectivity:

   ping <border-router-ip>

2. Verify correct IP address
3. Check if REST API is enabled (ESP32 uses port 80, ot-br-posix uses 8081)
4. Verify firewall settings

No IPv6 Connectivity to Thread Devices

1. Check if Router Advertisements are being received:

   ndp -p

2. Verify OMR prefix in routing table:

   netstat -rn -f inet6 | grep fd

3. Check if IPv6 forwarding is blocking RAs:

   sysctl net.inet6.ip6.forwarding

4. Verify border router is advertising routes

Cannot Reach Mesh-Local Addresses

This is expected behavior. Mesh-local addresses (fd65::/64) are only reachable from within the Thread mesh. External devices must use OMR addresses instead.

Router Advertisement Not Captured

1. Verify interface name:

   ifconfig

2. Check for sudo permissions
3. Wait longer (RAs sent every 30-300 seconds)
4. Use Wireshark filter:

   icmpv6.type == 134

Platform-Specific Notes

macOS

• Use

  ndp

  commands for neighbor discovery
• IPv6 forwarding check:

  sysctl net.inet6.ip6.forwarding

• Interface typically

  en0

  for Wi-Fi,

  en1

  for Ethernet

Linux

• Use

  ip -6

  commands instead of

  ndp

• IPv6 forwarding check:

  sysctl net.ipv6.conf.all.forwarding

• Accept RA setting:

  sysctl net.ipv6.conf.eth0.accept_ra

Best Practices

1. Always start with connectivity test - Run

   test_thread_connectivity.sh

   first
2. Save diagnostic output - Redirect script output to files for analysis
3. Compare before/after - Run diagnostics before and after configuration changes
4. Check both sides - Verify configuration on both infrastructure and Thread mesh
5. Use IPv6 bracket notation - When using IPv6 in URLs:

   http://[fd03::1]/