ESP8266 Diagnostic Utility
This is a small set of diagnostics and debugging tools for the ESP8266. It's meant to help solve problems around Wifi and I2C.
The utility includes Wifi and I2C scanners and can report basic information about the board you're using.
The utility runs the serial port at 115,200 bps. You'll want to use some kind of terminal program to interact with it.
The utility will display a menu when it starts:
Hello World 1. Show ESP information 2. Enter wifi credentials 3. Connect to wifi network 4. Current wifi info 5. Scan wifi networks 6. Scan I2C devices 0. Restart
1 Show ESP Infiormation
This shows information about the ESP SDK and Arduino core that the utility was built with as well as information about the CPU it's running on.
SDK version 2.2.1(cfd48f3) Arduino Core version 2_4_1 VCC 3013 Chip ID 283132 Flash Chip ID 1458208 Flash Chip Speed 40000000 Sketch Size 276032 Free heap 43496 Free sketch space 2867200 Reset reason External System
2 Enter Wifi credentials
You'll enter an SSID and password, each up to 64 characters, ending with the RETURN key. You can use backspace or delete to go back a character.
The SSID and password are not stored in flash and should not persist across reboots.
3 Connect to wifi network
This item will attempt to connect the ESP to a wifi network or will disconnect from the current network. You must enter wifi credentials before you can connect.
As it attempts to connect you should see wifi-related events.
A connection attempt using a non-existent SSID should look like:
Connecting...............[wifi] 1, Disconnected - Status 6, Disconnected ............................................................................................................
at this time you'll need to reset the CPU to get out of it.
A connection attempt with an invalid passwords hould look like:
Connecting........[wifi] 2, AuthMode Change ............................[wifi] 1, Disconnected - Status 6, Disconnected ............................................................................
at this time you'll need to reset the CPU to get out of it.
A successful connection attempt should look like:
Connecting....[wifi] 2, AuthMode Change ............[wifi] 0, Connected .........[wifi] 3, Got IP WiFi connected
4 Current wifi info
When connect to a wifi network, this will show how the ESP was configured by DHCP and the RSSI for the wifi network. It will always show you the ESP's MAC address.
Connected Hostname ESP_0223FC MAC address 38:2B:78:02:23:FC IP address 10.0.1.206 Subnet mask 255.255.255.0 router IP 10.0.1.1 first DNS server 10.0.1.1 SSID YOUR WIFI NETWORK RSSi -51
5 Scan wifi networks
This will show you a list of wifi networks that the ESP can currently see. The list may seem very random. Only nearby access points will show up reliably.
Remember that current ESPs are 2.4GHz devices. They support 802.11b/g/n but only the 2.4GHz band for n. They will never be able to see 5GHz 802.11a, 802.11n or 802.11ac networks.
Scan network output will look like this:
About to scan wifi networks Wifi scan done 10 networks found SSID CHN RSS MAC address Encryption HOME-2001 1 -84 E8:3E:FC:23:23:23 WPA/WPA2/PSK you better know your dumplng 1 -58 44:D9:E7:23:23:23 CCMP CenturyLink2061 1 -92 58:8B:F3:23:23:23 WPA/WPA2/PSK NETGEAR69 3 -35 9C:3D:CF:23:23:23 CCMP HP-Print-28-Officejet Pro 8600 4 -87 A0:D3:C1:23:23:23 none extra cashew sauce 4 -66 8C:3B:AD:23:23:23 CCMP tell me about the dumpling 5 -53 80:2A:A8:23:23:23 CCMP xfinitywifi 6 -93 F6:AA:A0:23:23:23 none BAKINGINDAKITC 6 -92 EC:AA:A0:23:23:23 CCMP Internet of Dumplings 11 -52 88:1F:A1:23:23:23 WPA/WPA2/PSK
The MAC address is the MAC address of the access point.
6 I2C Scanner
The I2C scanner probes each I2C address and reports which addresses respond.
It also contains a list of known I2C devices by address and will report the known uses of each responding address.
The list needs a lot of work and should eventually be stored in flash and not in the heap.
An I2C scan with no I2C device should look like this:
Scanning... No I2C devices found
A successful I2C scan might look like this:
Scanning... I2C device found at address 0x18 at 0x18 might be LIS3DH (3-axis accelerometer) at 0x18 might be LSM303 (Triple-axis Accelerometer+Magnetometer (Compass)) at 0x18 might be MCP9808 (temp sensor) I2C device found at address 0x39 at 0x39 might be APDS-9960 (IR/Color/Proximity Sensor) at 0x39 might be TSL2561 (light sensor) at 0x39 might be VEML6070 (UV Index) I2C device found at address 0x53 at 0x53 might be ADXL345 (3-axis accelerometer) at 0x53 might be MB85RC (Ferroelectric RAM) at 0x53 might be PCA9685 (16-channel PWM driver default address) I2C device found at address 0x5b at 0x5b might be CCS811 (VOC sensor) at 0x5b might be MPR121 (12-point capacitive touch sensor) at 0x5b might be PCA9685 (16-channel PWM driver default address) I2C device found at address 0x76 at 0x76 might be BME280 (Temp/Barometric/Humidity) at 0x76 might be BMP280 (Temp/Barometric) at 0x76 might be HT16K33 (LED Matrix Driver) at 0x76 might be MS5607/MS5611 (Barometric Pressure) at 0x76 might be PCA9685 (16-channel PWM driver default address) at 0x76 might be TCA9548 (1-to-8 I2C Multiplexer) done
An I2C scan with malfunctioning hardware might look like this:
Scanning... Unknown error at address 0x01 Unknown error at address 0x02 Unknown error at address 0x03 Unknown error at address 0x04 ...
This means something is interfering with signalling on the I2C SDA and SDC lines. It's most likely an electrical or wiring problem but could possibly be a defective I2C device.
The device list is generated by the web site https://i2cdevices.org/devices
There is no SPI scanner. SPI devices are individually selected - SPI doesn't have addresses. Which leaves us no way to scan for SPI devices. So, no SPI scanner; sorry.
Resets the ESP. It should very quickly restart and present the menu again.
H, ? and Newline
These will all re-display the menu.
Building and Installation
- Clone the repository
git clone firstname.lastname@example.org:romkey/ESP-Diagnostic-Tool.git
If the board you want to run on isn't currently in
platformio.ini, add it.
Build it and upload it:
platformio run -e YOUR_BOARD_ID -t upload
YOUR_BOARD_ID with the id for your board - for instance, Wemos D1 mini is listed in the shipping
- Run the serial monitor to interact with the utility.
platformio device monitor
If you missed the menu try typing
h to see it.
The utility has very limited ESP32 support. It can't currently report Wifi events and can't give much information about the board.
Bluetooth support looks problematic. The Bluetooth library is so large that it makes the firmware too big to load using the default flash partitioning scheme. You can work around this by changing partitioning but this is non-trivial.
Add more I2C devices
Build under Arduino IDE
Add timeout to Wifi connect attempt
Support AP and STA_AP wifi modes
mDNS publish and resolve
Move I2C device names list to Flash storage.
Improve ESP32 support
ESP32 Bluetooth scanning? (not likely due to Bluetooth library size issues)
This code is published under the MIT License.