EspTouch for Android

ESP-TOUCH uses Smart Config technology to provision Wi-Fi credentials (SSID and password) to ESP8266 and ESP32 devices via a smartphone.

Because the device is not yet connected to a network, the smartphone cannot communicate with it directly via IP. Instead, the smartphone sends a series of UDP packets to the Wi-Fi Access Point (AP). The SSID and password are encoded into the Length field of these UDP packets. The device, operating in a specific mode, listens to these packets to extract and parse the credentials.

UDP Packet Structure:

The operational mode of the ESP chip affects how it handles the Wi-Fi connection during configuration:

• ESP8266: Requires Sniffer mode to be enabled; Station/soft-AP mode must be disabled.
• ESP32: Can have both Sniffer and Station modes enabled simultaneously.

IP Interaction

Once configuration is successful, the smartphone obtains the device's IP address, and the device returns the smartphone's IP address. This enables custom local area network (LAN) communication between the two.

ESP-TOUCH uses Smart Config technology to connect ESP8266 and ESP32 devices to a Wi-Fi network. Since the device is not yet connected to the internet, a Wi-Fi-enabled device (like a smartphone) sends a series of UDP data packets to the Wi-Fi Access Point (AP).

The SSID and password are encoded within the Length field of the UDP packet. The device listens for these packets and parses them to obtain the network credentials.

UDP Packet Structure

For the EspTouch Android application or libraries to successfully configure your ESP device to connect to a target Access Point (AP), the device must be running a Smart Config implementation.

Supported implementations include:

• esp-idf smart_config
• ESP8266_RTOS_SDK smart_config

To start a provisioning task, instantiate EsptouchTask with the Access Point (AP) credentials and the application context. You can optionally configure the communication method using setPackageBroadcast.

• setPackageBroadcast(true): Sends broadcast packets.
• setPackageBroadcast(false): Sends multicast packets.

Context context; // Set Application context
byte[] apSsid = {}; // Set AP's SSID
byte[] apBssid = {}; // Set AP's BSSID
byte[] apPassword = {}; // Set AP's password

EsptouchTask task = new EsptouchTask(apSsid, apBssid, apPassword, context);
task.setPackageBroadcast(true); // if true send broadcast packets, else send multicast packets

To use the EspTouch libraries in your Android project, you must first add the JitPack repository to your root build.gradle file, and then add the specific library dependency to your app module's build.gradle file.

Important Compatibility Note: EspTouchV2 is not compatible with the original EspTouch. Choose the version that matches the Smart Config implementation running on your ESP device.

// 1. In your root build.gradle
allprojects {
    repositories {
        ...
        maven { url 'https://jitpack.io' }
    }
}

// 2. In your app module's build.gradle
// For original EspTouch:
implementation 'com.github.EspressifApp:lib-esptouch-android:1.1.1'

// OR for EspTouchV2:
implementation 'com.github.EspressifApp:lib-esptouch-v2-android:2.2.1'

To initiate the provisioning process, you must provide an EspProvisioningRequest object to the EspProvisioningParams constructor. The EspProvisioningParams class internally parses this request to generate the necessary data packets for the EspTouch protocol.

Key fields in the request that influence the provisioning payload include:

• ssid: The target Wi-Fi SSID.
• password: The Wi-Fi password.
• reservedData: Additional custom data to be sent during provisioning.
• aesKey: If provided, the provisioning process will use AES encryption for the password and reserved data.
• securityVer: Specifies the security version (e.g., 2 for AES IV generation).
• address: The target device address (determines if IPv4 or IPv6 flags are set in the header).
• bssid: Used to calculate the BSSID CRC in the packet header.

If provisioning fails, check the following common causes:

• Distance: If the device is too far from the router, connection may time out or take longer.
• Router Power: Ensure the router is powered on before starting the configuration process.
• AP Isolation: Check if the router has 'AP Isolation' enabled; this prevents the App from receiving the success notification.
• Network Band: Ensure you are not attempting to use a 5 GHz band or 802.11ac, as they are unsupported.
• Timeout: If the App returns a failure message, the timeout period may have expired before the device could parse the credentials.