In the development of smart devices, Bluetooth configuration is a very common and critical step. This article will comprehensively outline the process and key points of Bluetooth configuration, starting from entering configuration mode to connecting the device to the network and entering business operations, explained step by step.

Table of Contents

1. 1. Preliminary Notes on Configuration
2. 2. Bluetooth Scanning
3. 3. Input Wi-Fi Information (or Select Wi-Fi)
4. 4. Send Data (Wi-Fi and Configuration Information)
5. 5. Device Networking (Wi-Fi, MQTT)
6. 6. Business Operations After Networking
7. 7. Summary and Development Considerations

1. Preliminary Notes on Configuration

This is the first step of configuration, aimed at prompting the user on the app how to set the device to a configurable state and what permissions to enable.

• • Methods to Enter Configuration Mode：
• • Common: Long press the power button or RESET button for 5 seconds.
• • It may also be triggered by pressing a specific button or through a combination of external buttons.
• • App Permissions/Settings：
• • Users should be reminded to enable Bluetooth and grant necessary permissions (location permission, Bluetooth permission, etc., depending on the system version) in the app.
• • Is It Mandatory：
• • If the device only starts Bluetooth broadcasting after a button is pressed, this step is mandatory;
• • If the device’s Bluetooth is always on and can be configured at any time, this interaction prompt can be omitted.

⚠️ Remind users to stay away from strong electromagnetic interference environments and to be close to the router to improve the success rate of the first configuration.

2. Bluetooth Scanning

The app scans for broadcasting devices and filters target devices using the operating system’s Bluetooth API.

• • Broadcasting and Filtering Strategy：
• • Commonly filter target devices based on the broadcast name (or SN in the broadcast data);
• • It is recommended that devices use a unified specification for broadcasting, for example:<span>XX-DID-SN</span>, where <span>XX</span> is the company prefix, <span>DID</span> is the device type number, and <span>SN</span> is the serial number.
• • QR Code Alternative：
• • If there is a QR code with SN on the packaging or device, users can scan it to obtain the SN and connect via Bluetooth, skipping the scanning list page to enhance user experience.
• • Scanning and Connection Optimization：
• • Round scanning: For example, scan for 3 seconds each round, looping several rounds to cover environmental changes.
• • Connection timeout: Set a reasonable timeout and callback to the business layer to prompt the user after timeout.
• • Anti-reconnection logic: Return directly when connecting; if the target device is already connected, return success directly.
• • Cross-Platform Considerations：
• • The Bluetooth API and permission model differ between Android/iOS, and the scanning strategy must accommodate the differences on both ends.

3. Input Wi-Fi Information (or Obtain Nearby Wi-Fi List and Select)

After a successful Bluetooth connection, the app needs to obtain and transmit the Wi-Fi SSID and password to the device.

• • Frequency Band Limitations：
• • Most modules only support 2.4GHz Wi-Fi, and the app must prominently inform users that only 2.4G is supported.
• • Auto-fill Current Wi-Fi：
• • Android can read the name of the currently connected Wi-Fi and auto-fill it (if it is 2.4G). This is important for user experience.
• • iOS does not support directly reading the current system Wi-Fi name (due to system restrictions).
• • Two Solutions for Obtaining Wi-Fi List：

1. 1. App Calls System API (Android): Directly obtain the nearby Wi-Fi list – iOS does not support this.
2. 2. Device Hardware Scans and Returns List via Bluetooth (recommended):

• • Advantages: Consistent for iOS/Android; the device can obtain more accurate signal strength information.
• • Disadvantages: When there are many Wi-Fi lists, consider Bluetooth MTU limitations and handle packet splitting/combining.

• • It is recommended to poll for Wi-Fi switching on the phone side (to avoid the interface not updating when the user switches Wi-Fi via the notification bar).
• • Clearly inform users of the minimum length/character rules for password input (as some routers have special character restrictions).

4. Send Data (Transmit Wi-Fi and Configuration Information to the Device)

The sending phase is the core and most complex part of the entire configuration process, involving protocol design and encrypted transmission.

• • Content to be Sent：
• • At a minimum:<span>SSID</span> and <span>Password</span>.
• • Optional/recommended: Other configuration information needed after the device starts (such as MQTT domain name, port, username/password, device-specific parameters, etc.).
• • The device can also pull configurations from the cloud via HTTPS after connecting to the network (implementation on the hardware side is more complex).
• • Protocol Forms (Two Common Types)：

1. 1. JSON Format (more friendly for front-end/back-end):

   {
     "cmd": "wifi_config",
     "cmdId": 0,
     "ssid": "MyHomeWiFi",
     "pwd": "12345678"
   }

2. 2. Byte Array/Binary Protocol (commonly used in embedded systems):

   [0xAA][0x55][CMD][LEN][DATA...][CRC]

• • Sensitive fields (such as Wi-Fi passwords, MQTT passwords) should be encrypted, common algorithms include: AES, TEA, etc. Currently, products going overseas require overseas certification, and encryption is a necessary step.
• • The key negotiation method needs to be agreed upon or the key should be embedded in the device at the factory.

• • When the length of a single data exceeds Bluetooth MTU (or for reliability), it is necessary to split packets for sending and perform combining and verification (e.g., CRC or sequence number) on the device side.

• • There should be a retransmission strategy for sending failures or verification failures, and timely notification to the user (or display a retry button on the interface).

5. Device Networking (Wi-Fi Connection and Backend Connection)

After the device receives and parses the configuration information sent by the app, it begins the networking process and returns the result to the app.

• • Common Networking Steps：

1. 1. Module connects to Wi-Fi (base station authentication, obtaining IP, etc.).
2. 2. Connect to cloud protocol (commonly MQTT, may also be WebSocket or HTTP).
3. 3. Save Wi-Fi and cloud connection information to persistent storage (for automatic reconnection after power loss).

• • Some designs: as long as Wi-Fi is connected, it returns success.
• • More recommended:Wi-Fi success + MQTT (or business layer) connection success before returning configuration success.
• • Advantages: Users can immediately see normal business data, reducing the misjudgment of “connection successful but unable to access the cloud”.
• • Disadvantages: MQTT connection may increase configuration time (usually from hundreds of milliseconds to several seconds).

{
  "cmdId": 0,
  "errCode": "0"
}

Fine-Grained Progress Feedback

• • Some solutions will return the status of each step in stages, for example:<span>Connected to Wi-Fi</span> / <span>Connected to MQTT</span> / <span>Saved Successfully</span>.
• • The app can display a progress bar or step prompts on the interface based on this, significantly enhancing user experience.

Weak Network and Module Differences

• • In weak network environments, the module may not be able to accurately distinguish the error reasons (e.g., only returning “connection failed”).
• • The app needs to design general interaction prompts and retry strategies (e.g., retry, switch Wi-Fi, manual input, or contact customer service), and log enough information for troubleshooting.

6. Business Operations After Networking

After the device successfully connects to the network, subsequent business processes are usually determined by product/business requirements, with common processing logic as follows:

• • App Receives Failure (<span>errCode ≠ 0</span>)
• • Pop up corresponding prompts based on the error code (e.g., “Wi-Fi password error” or “Device failed to connect to the cloud, please check the network”).
• • Provide options for retry, manual input, or return to the previous step, and guide users to move closer to the router or check router settings if necessary.
• • App Receives Success (<span>errCode = 0</span>)
• • Common subsequent actions:
• • Call the backend Add Device / Bind Device interface to bind the device with the user account/room/scene.
• • Send device initialization parameters (if required by the business).
• • Decide whether to disconnect the Bluetooth connection (usually disconnect to save power).
• • Redirect to the device home page or device detail page, displaying the real-time status of the device and guiding users to complete the initial configuration.
• • Device Initialization
• • Some business scenarios will continue to execute after configuration: sending initial scenes, checking firmware versions, configuring permissions, etc., to ensure the device is in an available and secure state.

7. Summary and Development Considerations

Overview of Configuration Process

<span>Enter Configuration Mode → Bluetooth Scanning → Input/Select Wi-Fi → Send Configuration Information → Device Networking (Wi-Fi + MQTT, etc.) → Business Binding and Initialization</span>

Core Challenges

• • Protocol design (readability, extensibility, choice of serialization format).
• • Data security (encryption of passwords and sensitive information, key management).
• • Cross-platform compatibility (iOS and Android have differences in Wi-Fi and Bluetooth permissions, APIs).
• • Reliable Bluetooth transmission (MTU, packet splitting/combining, retransmission strategy, connection timeout).
• • User experience (auto-fill, clear error prompts, progress feedback).

Engineering Practice Recommendations

• • Use a unified and easily parseable broadcasting format to facilitate filtering on the app side.
• • It is recommended that the hardware side provide a Wi-Fi scanning interface and return it via Bluetooth (to reduce differences caused by iOS restrictions).
• • Design clear <span>cmdId</span>/<span>seq</span> and <span>errCode</span> in the protocol to facilitate problem localization and log tracking.
• • Encrypt sensitive data and establish a version compatibility strategy (backward compatibility during protocol upgrades).
• • On the app side, consider various failure scenarios (weak network, password errors, router restrictions, dual-band router settings, etc.), and provide friendly guidance and executable actions (retry, manual input, contact customer service).