mcbluetooth-esp32/tests/prompts/test-prompt-v5.md

ESP32 + BlueZ Full E2E Bluetooth Test Suite (v5 - Complete Coverage)

You have two MCP servers available:

• esp32 (prefix: mcp__esp32__) — controls an ESP32 dev board via serial/UART
• bluez (prefix: mcp__bluez__) — controls the Linux BlueZ Bluetooth stack

Run ALL tests IN ORDER. For each test, report PASS or FAIL with actual response data. If a test fails, note the error and continue with remaining tests.

Important: The Linux adapter is hci1 (not hci0). Use hci1 for all BlueZ calls.

---

Phase 1: ESP32 Connection & System (Tests 1-4)

1. Connect: Call esp32_connect — should return connected=true AND ready=true
2. Ping: Call esp32_ping — expect {"pong": true}
3. Get Info: Call esp32_get_info — note the chip model, FW version, and BT MAC address (you'll need the MAC later)
4. Get Status: Call esp32_status — confirm bt_enabled=false, ble_enabled=false

Phase 2: BlueZ Adapter Deep Dive (Tests 5-8)

5. List Adapters: Call bt_list_adapters — find the powered adapter, note its name (probably hci1)
6. Adapter Info: Call bt_adapter_info with the adapter name — report full details including the adapter's MAC address
7. Set Pairable: Call bt_adapter_pairable with adapter, on=true — enable pairing acceptance
8. Set Discoverable: Call bt_adapter_discoverable with adapter, on=true, timeout=300 — make Linux visible

Phase 3: Classic BT + SSP Pairing (Tests 9-24)

IMPORTANT: Enable Classic BT FIRST, then configure IO capabilities.

9. Enable Classic: Call esp32_classic_enable
10. Configure ESP32: Call esp32_configure with name="SSP-Test-Device", io_cap="display_yesno"
11. Set SSP Mode: Call esp32_set_ssp_mode with mode="numeric_comparison", auto_accept=true
12. Check Status: Call esp32_status — confirm bt_enabled=true
13. Set ESP32 Discoverable: Call esp32_classic_set_discoverable with discoverable=true, timeout=120
14. Scan from Linux: Call bt_scan with adapter="hci1", mode="classic", timeout=10 — find the ESP32 by its MAC

Now initiate pairing:

15. Check Pairing Status Before: Call bt_pairing_status — should show no pending requests
16. Start Pairing: Call bt_pair with adapter="hci1", address=, pairing_mode="auto"
17. Check ESP32 Pair Events: Call esp32_get_events — look for pair_request and pair_complete events
18. Verify Paired on Linux: Call bt_device_info with adapter="hci1", address= — check paired=true

Post-pairing device management:

19. List Known Devices: Call bt_list_devices with adapter="hci1", filter="paired" — ESP32 should be in the list
20. Trust Device: Call bt_trust with adapter="hci1", address=, trusted=true
21. Set Alias: Call bt_device_set_alias with adapter="hci1", address=, alias="My ESP32 Test Device"
22. Block Device: Call bt_block with adapter="hci1", address=, blocked=true — block the device
23. Unblock Device: Call bt_block with adapter="hci1", address=, blocked=false — unblock it
24. Unpair: Call bt_unpair with adapter="hci1", address= — clean up pairing

Phase 4: Classic Cleanup + Event System (Tests 25-29)

25. Disable Classic: Call esp32_classic_disable
26. Get All Events: Call esp32_get_events — report ALL events captured so far
27. Clear Events: Call esp32_clear_events
28. Verify Cleared: Call esp32_get_events — should return empty list
29. Check Status: Call esp32_status — confirm bt_enabled=false

Phase 5: BLE GATT Setup with Battery Service (Tests 30-42)

Set up ESP32 as a BLE peripheral with Environmental Sensing AND Battery Service:

30. Enable BLE: Call esp32_ble_enable

First, add Battery Service (0x180F) for bt_ble_battery test:

31. Add Battery Service: Call esp32_gatt_add_service with uuid="0000180f-0000-1000-8000-00805f9b34fb" (Battery Service), primary=true — save as battery_svc_handle
32. Add Battery Level Char: Call esp32_gatt_add_characteristic with service_handle=battery_svc_handle, uuid="00002a19-0000-1000-8000-00805f9b34fb" (Battery Level), properties=["read"] — save as battery_char_handle
33. Set Battery Level: Call esp32_gatt_set_value with char_handle=battery_char_handle, value="4b" (75%)

Now add Environmental Sensing Service:

34. Add Env Service: Call esp32_gatt_add_service with uuid="0000181a-0000-1000-8000-00805f9b34fb" (Environmental Sensing), primary=true — save as env_svc_handle
35. Add Temperature Char: Call esp32_gatt_add_characteristic with service_handle=env_svc_handle, uuid="00002a6e-0000-1000-8000-00805f9b34fb" (Temperature), properties=["read","notify"] — save as temp_handle
36. Add Humidity Char: Call esp32_gatt_add_characteristic with service_handle=env_svc_handle, uuid="00002a6f-0000-1000-8000-00805f9b34fb" (Humidity), properties=["read","write"] — save as humidity_handle
37. Set Temperature: Call esp32_gatt_set_value with char_handle=temp_handle, value="e803" (25.0°C)
38. Set Humidity: Call esp32_gatt_set_value with char_handle=humidity_handle, value="3200" (50%)

Configure advertising:

39. Set Adv Data: Call esp32_ble_set_adv_data with name="BLE-Sensor-Test", service_uuids=["0000180f-0000-1000-8000-00805f9b34fb", "0000181a-0000-1000-8000-00805f9b34fb"]
40. Start Advertising: Call esp32_ble_advertise with enable=true
41. Clear Events: Call esp32_clear_events — clear event history before BLE tests
42. Check BLE Status: Call esp32_status — confirm ble_enabled=true

Phase 6: HCI Capture + BLE Discovery (Tests 43-51)

Start HCI packet capture BEFORE connecting:

43. Start HCI Capture: Call bt_capture_start with adapter="hci1", output_file="/tmp/ble-gatt-capture.btsnoop"
44. List Active Captures: Call bt_capture_list_active — verify capture is running
45. BLE Scan: Call bt_ble_scan with adapter="hci1", timeout=10 — find the ESP32, verify name="BLE-Sensor-Test"
46. Connect BLE: Call bt_connect with adapter="hci1", address=

Wait 3 seconds for service discovery to complete, then:

47. List Services: Call bt_ble_services with adapter="hci1", address= — should see Battery (180f) and Environmental Sensing (181a)
48. List Characteristics: Call bt_ble_characteristics with adapter="hci1", address= — should see Battery Level (2a19), Temperature (2a6e), Humidity (2a6f)
49. Read Battery Level: Call bt_ble_battery with adapter="hci1", address= — should return 75 (the value we set as "4b")
50. Read Temperature: Call bt_ble_read with adapter="hci1", address=, char_uuid="00002a6e-0000-1000-8000-00805f9b34fb" — should return hex "e803"
51. Check Read Events: Call esp32_get_events — look for gatt_read events

Stop capture for analysis:

Phase 7: Analyze HCI Capture (Tests 52-55)

52. Stop HCI Capture: Call bt_capture_stop with capture_id from test 43
53. Parse Capture: Call bt_capture_parse with filepath="/tmp/ble-gatt-capture.btsnoop", max_packets=50 — report packet count and types
54. Analyze Capture: Call bt_capture_analyze with filepath="/tmp/ble-gatt-capture.btsnoop" — report statistics
55. Read Raw Packets: Call bt_capture_read_raw with filepath="/tmp/ble-gatt-capture.btsnoop", count=20 — show decoded packets

Phase 8: BLE GATT Write + Notifications (Tests 56-63)

56. Write Humidity: Call bt_ble_write with adapter="hci1", address=, char_uuid="00002a6f-0000-1000-8000-00805f9b34fb", value="4b00", value_type="hex"
57. Check Write Event: Call esp32_get_events — look for a gatt_write event with the written value
58. Subscribe Notifications: Call bt_ble_notify with adapter="hci1", address=, char_uuid="00002a6e-0000-1000-8000-00805f9b34fb", enable=true
59. Check Subscribe Event: Call esp32_get_events — look for a gatt_subscribe event
60. Push Notification: First call esp32_gatt_set_value with char_handle=temp_handle, value="f401" (50.0°C), then call esp32_gatt_notify with char_handle=temp_handle
61. Read Updated Value: Call bt_ble_read with adapter="hci1", address=, char_uuid="00002a6e-0000-1000-8000-00805f9b34fb" — should now return "f401"
62. Unsubscribe: Call bt_ble_notify with adapter="hci1", address=, char_uuid="00002a6e-0000-1000-8000-00805f9b34fb", enable=false
63. Disconnect BLE: Call bt_disconnect with adapter="hci1", address=

Phase 9: BLE Cleanup (Tests 64-68)

64. Stop Advertising: Call esp32_ble_advertise with enable=false
65. Clear GATT: Call esp32_gatt_clear
66. Disable BLE: Call esp32_ble_disable
67. Final Status: Call esp32_status — bt_enabled=false, ble_enabled=false
68. Clear ESP32 Events: Call esp32_clear_events

Phase 10: Adapter Self-Management (Tests 69-73)

These tests verify adapter configuration tools. Done at the end to not interfere with earlier tests.

69. Get Original Alias: Call bt_adapter_info with adapter="hci1" — note the current alias
70. Set New Alias: Call bt_adapter_set_alias with adapter="hci1", alias="E2E-Test-Adapter" — change the name
71. Verify Alias Changed: Call bt_adapter_info with adapter="hci1" — confirm alias is "E2E-Test-Adapter"
72. Restore Original Alias: Call bt_adapter_set_alias with adapter="hci1", alias=<original alias from test 69>
73. Disable Discoverable: Call bt_adapter_discoverable with adapter="hci1", on=false — clean up

Phase 11: Final Cleanup (Tests 74-76)

74. Reset ESP32: Call esp32_reset
75. Disconnect Serial: Call esp32_disconnect
76. Final Adapter Check: Call bt_adapter_info with adapter="hci1" — verify adapter is still powered and healthy

---

Summary

After all tests, print a DETAILED summary table:

#	Test	Result	Notes
1	Connect	PASS/FAIL	...
...	...	...	...

Report:

• Total PASS/FAIL counts
• Whether pairing succeeded (phase 3)
• What ESP32 events were captured (phases 4, 6, 8)
• Whether bt_ble_battery returned the expected value 75 (test 49)
• Whether GATT read returned expected value (test 50)
• Whether GATT write succeeded (test 56)
• Whether the updated value was readable after notification (test 61)
• HCI capture statistics (tests 53-55): packet count, types captured, any errors