MCP/mcbluetooth-esp32
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
mcbluetooth-esp32/tests/prompts/test-prompt-v5.md
Ryan Malloy 88d006e9c4 Add automated E2E testing documentation and test prompts 
- docs/automated-e2e-testing.md: Guide for running headless Claude CLI
  tests with both mcbluetooth and mcbluetooth-esp32 MCP servers
- tests/prompts/test-prompt-v4.md: 71-test suite covering Classic BT,
  BLE GATT, HCI capture, device management
- tests/prompts/test-prompt-v5.md: 76-test suite adding Battery Service
  (0x180F) and bt_ble_battery verification

Test results from v4: 71/71 PASS with 143 HCI packets captured
2026-02-03 11:18:37 -07:00

171 lines
10 KiB
Markdown
Raw Blame History

# 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=<ESP32 MAC>, 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=<ESP32 MAC> — 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=<ESP32 MAC>, trusted=true
21. **Set Alias**: Call `bt_device_set_alias` with adapter="hci1", address=<ESP32 MAC>, alias="My ESP32 Test Device"
22. **Block Device**: Call `bt_block` with adapter="hci1", address=<ESP32 MAC>, blocked=true — block the device
23. **Unblock Device**: Call `bt_block` with adapter="hci1", address=<ESP32 MAC>, blocked=false — unblock it
24. **Unpair**: Call `bt_unpair` with adapter="hci1", address=<ESP32 MAC> — 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=<ESP32 MAC>
Wait 3 seconds for service discovery to complete, then:
47. **List Services**: Call `bt_ble_services` with adapter="hci1", address=<ESP32 MAC> — should see Battery (180f) and Environmental Sensing (181a)
48. **List Characteristics**: Call `bt_ble_characteristics` with adapter="hci1", address=<ESP32 MAC> — should see Battery Level (2a19), Temperature (2a6e), Humidity (2a6f)
49. **Read Battery Level**: Call `bt_ble_battery` with adapter="hci1", address=<ESP32 MAC> — should return 75 (the value we set as "4b")
50. **Read Temperature**: Call `bt_ble_read` with adapter="hci1", address=<ESP32 MAC>, 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=<ESP32 MAC>, 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=<ESP32 MAC>, 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=<ESP32 MAC>, char_uuid="00002a6e-0000-1000-8000-00805f9b34fb" — should now return "f401"
62. **Unsubscribe**: Call `bt_ble_notify` with adapter="hci1", address=<ESP32 MAC>, char_uuid="00002a6e-0000-1000-8000-00805f9b34fb", enable=false
63. **Disconnect BLE**: Call `bt_disconnect` with adapter="hci1", address=<ESP32 MAC>
## 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
Reference in New Issue View Git Blame Copy Permalink