Skip to content

TESTING.md

Latest commit

 

History

History
477 lines (357 loc) · 12.4 KB

TESTING.md

File metadata and controls

477 lines (357 loc) · 12.4 KB

ESP-NOW Testing Guide

This guide explains how to test ESP-NOW functionality using the built-in test modes.

Overview

Two test modes are available:

  1. UI Test - Visual interface with peer list, message log, and statistics (default)
  2. Console Test - Serial terminal output for debugging

Both support serial input for peer MAC address entry, making them flexible for any device pairing.

Prerequisites

Hardware

  • 2x ESP32-S3 devices (ESP32-S3-Touch-LCD-1.46 or similar)
  • USB cables for both devices
  • Serial terminals for both devices (or use idf.py monitor)

Software

  • ESP-IDF 5.5.1
  • Project compiled with ESP-NOW support

Quick Start Testing

Step 1: Build Once

cd /home/kpatch/development/plaipin-device

# Configure
idf.py menuconfig
# Navigate to: plaipin-device Configuration
#   └─> Test Modes
#       └─> [*] Enable ESP-NOW Test Mode

# Build
idf.py build

Step 2: Flash Both Devices

# Device A (USB port 0)
idf.py -p /dev/ttyUSB0 flash

# Device B (USB port 1)  
idf.py -p /dev/ttyUSB1 flash

Step 3: Get MAC Addresses

# Terminal 1 - Device A
idf.py -p /dev/ttyUSB0 monitor

# You'll see:
# Local MAC: 24:0A:C4:12:34:56
# Enter peer MAC (XX:XX:XX:XX:XX:XX):
# > _
# Terminal 2 - Device B (separate terminal window)
idf.py -p /dev/ttyUSB1 monitor

# You'll see:
# Local MAC: 24:0A:C4:78:9A:BC  ← Copy this!
# Enter peer MAC (XX:XX:XX:XX:XX:XX):
# > _

Step 4: Cross-Enter MAC Addresses

In Terminal 1 (Device A):

> 24:0A:C4:78:9A:BC [Enter]  ← Enter Device B's MAC

In Terminal 2 (Device B):

> 24:0A:C4:12:34:56 [Enter]  ← Enter Device A's MAC

Step 5: Watch the Magic! ✨

Both devices will:

  • Auto-pair with each other
  • Exchange test messages every 15 seconds
  • Display status updates (UI version shows on screen)
  • Log all activity to serial

Test Modes

UI Test Mode (Default)

What you see on screen:

╔═══════════════════════════════════════════════════════════╗
║           ESP-NOW Test                                    ║
║  MAC: 24:0A:C4:12:34:56                                   ║
╠═══════════════════════════════════════════════════════════╣
║                                                           ║
║  📱 Paired Devices                                        ║
║  ┌───────────────────────────────────────────────────┐  ║
║  │ PlaiPin-def456                                     │  ║
║  │ 24:0A:C4:78:9A:BC | 3s ago                        │  ║
║  └───────────────────────────────────────────────────┘  ║
║                                                           ║
║  💬 Messages                                              ║
║  ├─ → Test #5 from PlaiPin-abc123                       ║
║  ├─ ← Test #4 from PlaiPin-def456                       ║
║  └─ → Test #3 from PlaiPin-abc123                       ║
║                                                           ║
║  📊 Sent:15 Rcv:12 Err:0                                 ║
╚═══════════════════════════════════════════════════════════╝

Features:

  • Live peer list with last-seen timestamps
  • Message history (last 3 messages)
  • Real-time statistics
  • Color-coded status indicators
  • Auto-refresh every 2 seconds

Console Test Mode (Alternative)

To use console mode:

Edit main/main.cc:

#ifdef CONFIG_ESPNOW_TEST_MODE
    // start_espnow_ui_test();      // UI version
    start_espnow_test();             // Console version ← Uncomment this
#endif

What you see in terminal:

ESP-NOW Test Mode
Local MAC: 24:0A:C4:12:34:56

Enter peer MAC: 24:0A:C4:78:9A:BC [Enter]

✓ Pairing request sent

📨 PAIRING RESPONSE received!
  From: 24:0A:C4:78:9A:BC
  Device: PlaiPin-def456
  Status: ACCEPTED ✅

💬 TEXT MESSAGE received!
  From: PlaiPin-def456
  Message: "Test #1 from PlaiPin-def456"

========== Paired Devices (1) ==========
  MAC: 24:0A:C4:78:9A:BC
  Name: PlaiPin-def456
  RSSI: 0 dBm
  Last seen: 2s ago
=======================================

Testing Scenarios

Scenario 1: Basic Pairing Test

Goal: Verify ESP-NOW initialization and pairing

Steps:

  1. Flash both devices with test mode
  2. Enter MAC addresses via serial
  3. Verify pairing success messages
  4. Check that devices appear in peer list

Success Criteria:

  • ✅ Both devices initialize ESP-NOW
  • ✅ Pairing requests sent and received
  • ✅ Auto-acceptance works
  • ✅ Peers visible in list

Scenario 2: Message Exchange Test

Goal: Verify bidirectional messaging

Steps:

  1. Complete pairing (Scenario 1)
  2. Wait for automatic test messages (every 15 seconds)
  3. Observe message counters incrementing
  4. Check serial logs for message content

Success Criteria:

  • ✅ Messages sent successfully
  • ✅ Messages received on peer device
  • ✅ No send errors
  • ✅ Message content correct

Scenario 3: Passive Mode Test

Goal: Test discovery without active pairing

Steps:

  1. Device A: Enter peer MAC
  2. Device B: Press Enter (skip MAC entry - passive mode)
  3. Device A initiates pairing
  4. Device B auto-accepts

Success Criteria:

  • ✅ Device B receives pairing request
  • ✅ Auto-acceptance works
  • ✅ Bidirectional communication established

Scenario 4: Range Test

Goal: Test maximum communication distance

Steps:

  1. Pair devices normally
  2. Move devices apart gradually
  3. Monitor message success/failure
  4. Note distance where failures occur

Expected Range:

  • Indoor: 30-50 meters
  • Outdoor (line of sight): 100-200 meters
  • Through walls: 10-30 meters (depending on materials)

Scenario 5: Multi-Device Test

Goal: Test with more than 2 devices

Steps:

  1. Flash 3+ devices
  2. Device A pairs with Device B and C
  3. Observe message broadcast behavior
  4. Check that all paired devices receive messages

Success Criteria:

  • ✅ Multiple peers visible
  • ✅ Broadcast messages reach all peers
  • ✅ No crosstalk or interference

Expected Output

Serial Log (Successful Test)

I (1234) EspNowTest: 
I (1234) EspNowTest: ╔═══════════════════════════════════════════════════════╗
I (1234) EspNowTest: ║          ESP-NOW COMMUNICATION TEST MODE              ║
I (1234) EspNowTest: ╚═══════════════════════════════════════════════════════╝
I (1234) EspNowTest: 
I (1256) EspNowTest: ✓ NVS initialized
I (1278) EspNowTest: Initializing WiFi...
I (1345) EspNowTest: ✓ WiFi initialized (STA mode, Channel 1)
I (1345) EspNowTest: 
I (1345) EspNowTest: Device Information:
I (1345) EspNowTest:   UUID: 05f6c0c3-1594-44bc-b3b5-15b6e3f6c7a8
I (1345) EspNowTest:   Name: PlaiPin-05f6c0
I (1345) EspNowTest:   MAC:  24:0A:C4:12:34:56
I (1345) EspNowTest: 
I (1456) EspNowTest: Initializing ESP-NOW...
I (1467) EspNowTest: ✓ ESP-NOW initialized
I (1467) EspNowTest:   Local MAC: 24:0A:C4:12:34:56
I (1467) EspNowTest: 
I (1567) EspNowTest: ✓ Callbacks configured
I (1567) EspNowTest: 
I (1567) EspNowTest: ╔═══════════════════════════════════════════════════════╗
I (1567) EspNowTest: ║              PEER DEVICE CONFIGURATION                ║
I (1567) EspNowTest: ╚═══════════════════════════════════════════════════════╝
I (1567) EspNowTest: 
I (1567) EspNowTest: Enter peer MAC address (XX:XX:XX:XX:XX:XX):
I (1567) EspNowTest: Or press Enter to skip (passive mode - wait for pairing)
I (1567) EspNowTest: 
> 24:0A:C4:78:9A:BC
I (5678) EspNowTest: 
I (5678) EspNowTest: ✓ Initiating pairing with: 24:0A:C4:78:9A:BC
I (5678) EspNowTest: 
I (5689) EspNowTest: ✓ Pairing request sent
I (5689) EspNowTest: 
I (5745) EspNowTest: 
I (5745) EspNowTest: 📨 PAIRING RESPONSE received!
I (5745) EspNowTest:   From: 24:0A:C4:78:9A:BC
I (5745) EspNowTest:   Device: PlaiPin-789abc
I (5745) EspNowTest:   UUID: 789abc12-3456-78de-f123-456789abcdef
I (5745) EspNowTest:   Status: ACCEPTED ✅
I (5745) EspNowTest:

UI Display

The screen will show:

  • Header: Device name and MAC
  • Status: Green when paired, yellow when waiting
  • Peer List: Up to 5 paired devices with timestamps
  • Message Log: Last 3 messages (sent/received)
  • Footer: Statistics (sent, received, errors)

Troubleshooting

Problem: "Failed to initialize ESP-NOW"

Possible Causes:

  • WiFi not initialized
  • Insufficient memory
  • ESP-NOW already initialized

Solution:

# Clean build
rm -rf build
idf.py build flash

Problem: "Failed to send pairing request"

Possible Causes:

  • Invalid MAC address format
  • Peer not added to ESP-NOW peer list
  • WiFi channel mismatch

Solution:

  • Check MAC format: XX:XX:XX:XX:XX:XX
  • Ensure both devices on channel 1
  • Try adding peer manually first

Problem: "No messages received"

Possible Causes:

  • Devices too far apart
  • WiFi channel different
  • Pairing not established

Solution:

  • Move devices closer (<5m for testing)
  • Check serial logs for pairing confirmation
  • Verify both devices show each other in peer list

Problem: "Invalid MAC address format"

Possible Causes:

  • Typo in MAC address
  • Wrong format (lowercase, missing colons)

Solution:

  • Use UPPERCASE: 24:0A:C4:12:34:56
  • Include colons every 2 digits
  • Copy-paste from serial output

Problem: "Timeout waiting for input"

Possible Causes:

  • 30-second timeout expired
  • No serial input received

Solution:

  • Reboot device to get prompt again
  • Type faster :)
  • Or press Enter for passive mode

Advanced Testing

Custom Message Interval

Edit espnow_test.cc or espnow_ui_test.cc:

// Change from 15 seconds to 5 seconds
vTaskDelay(pdMS_TO_TICKS(5000));  // Line ~60

Custom Message Content

Edit message_sender_task():

snprintf(msg_text, sizeof(msg_text), "Your custom message here");

Enable Encryption

In main/Kconfig.projbuild:

CONFIG_ESPNOW_ENABLE_ENCRYPTION=y

Then set encryption key in code.

Performance Metrics

Expected Performance

Metric Value
Initialization Time < 2 seconds
Pairing Latency < 100 ms
Message Latency 10-50 ms
Range (Indoor) 30-50 meters
Range (Outdoor) 100-200 meters
Max Message Size 250 bytes
Message Success Rate > 99% (< 5m)

Actual Performance

Record your test results:

Date: ___________
Device A MAC: __________________
Device B MAC: __________________

Test Results:
- Initialization: _____ seconds
- First pairing: _____ ms
- Message latency (avg): _____ ms
- Max range tested: _____ meters
- Messages sent: _____
- Messages received: _____
- Send errors: _____
- Success rate: _____ %

Tips

  1. Keep devices close (<5m) for initial testing
  2. Use copy-paste for MAC addresses to avoid typos
  3. Check serial logs on both devices simultaneously
  4. Wait 30 seconds for message exchange to start
  5. Power cycle if something seems stuck
  6. Use UI version for easier monitoring
  7. Use console version for detailed debugging

Next Steps

After successful testing:

  1. Phase 2: Integrate with BLE proximity detection
  2. Phase 3: Add LLM message injection
  3. Production: Integrate into main application

See ../proximity/INTEGRATION_GUIDE.md for integration examples.

Getting Help

If you encounter issues:

  1. Check serial logs on both devices
  2. Verify MAC addresses are correct
  3. Ensure both devices completed WiFi init
  4. Try moving devices closer together
  5. Check ESP-IDF version (5.5.1 required)

For detailed API documentation, see README.md in this directory.