# Connectivity and Offline Logic

## 1. Overview
The connectivity and offline logic aims to provide users with real-time feedback on device connection status. In the Tuya panel system, "Offline" is a state where the device cannot be controlled, while "Bluetooth Connection/Reconnection" is an interaction process where the framework automatically attempts to restore the connection for Bluetooth and dual-mode devices after they are judged to be offline.

> **Tip**: This capability is highly integrated. It will automatically start the following logic during panel mini program initialization, requiring no code implementation by developers.

---

## 2. Logical Flow Chart

The basic library has a built-in complex offline decision tree, adapting to various connection methods such as Wi-Fi, Bluetooth, dual-mode, and gateway, as shown in the figure below:

<Image src="/images/panel/offline_logic_en.png" />

---

## 3. Automated Framework Behavior

### 3.1 Offline Mask Management
The framework will monitor the online status of the device in real-time. Once a device is judged to be offline, an "offline mask" will automatically cover the panel, intercepting all business operations.
*   **Troubleshooting Guidance**: Display corresponding troubleshooting suggestions based on the device type.
*   **Network Status Awareness**: Monitor the mobile phone's network environment in real-time. For devices requiring network connection, the framework will automatically display an offline mask when the mobile phone is disconnected.

<Image src="/images/panel/panel-offline-default.en-US.jpg" style={{ width: '375px', height: '664px' }} />

### 3.2 Automatic Bluetooth Reconnection
For Bluetooth (BLE) and dual-mode devices, the framework will automatically start the "local connection recovery" process after detecting device offline. This process aims to establish direct communication with the device through the phone's Bluetooth for near-end control in the offline state.

#### 1. Pre-check and Permission Guidance
Before attempting to connect, the framework will first check the necessary communication environment. If the environment is not met, a guidance prompt will be actively popped up:
*   **Bluetooth Authorization Check**: Detect if the App has permission to use the phone's Bluetooth. If not authorized, the user will be guided to the system settings to enable it.
*   **Bluetooth Switch Status**: Detect if the phone's system Bluetooth is turned on. If it is off, the user will be reminded to turn it on.

**Bluetooth Unauthorized Prompt**:
<Image src="/images/panel/panel-offline-ble-auth.en-US.jpg" style={{ width: '375px' }} />

**Bluetooth Not Turned On Prompt**:
<Image src="/images/panel/panel-offline-ble-system-off.en-US.jpg" style={{ width: '375px' }} />

#### 2. Automated Connection Process
Once the communication environment is ready, the framework will start silent background reconnection:
*   **Connection Status Feedback**: The interface will display a Bluetooth connection floating window to inform the user of the current connection progress.
*   **Automatic Interaction Loop**: If the reconnection is successful, the offline mask and connection floating window will automatically disappear, restoring panel control permissions.

**Bluetooth Connecting**:
<Image src="/images/panel/panel-offline-ble-connecting.en-US.jpg" style={{ width: '375px' }} />

**Connection Failed Status**:
<Image src="/images/panel/panel-offline-ble.en-US.jpg" style={{ width: '375px' }} />

#### 3. Failure Troubleshooting and Guidance
If the reconnection fails within the specified time, the framework will provide detailed failure reasons and troubleshooting suggestions, guiding the user to solve the problem in other ways (such as checking device power supply or restarting Bluetooth).

<Image src="/images/panel/panel-offline-ble-tip.en-US.jpg" style={{ width: '375px' }} />

---

## 4. Common Configuration Descriptions

Developers can fine-tune the above behavior through the parameters of `initPanelEnvironment`:

*   **`useDefaultOffline`**: Setting to `false` can completely disable the built-in offline mask, allowing developers to implement the UI themselves through status monitoring.
*   **`bleCover`**: Whether to add an overlay to block interface interaction when the Bluetooth connection floating window is displayed.
*   **`customTop`**: Adjust the top distance of the Bluetooth floating window to adapt to a custom navigation bar.

---

## 5. Precautions
1.  **Functional Standardization**: This offline mechanism is a unified standard capability built into the basic library, aiming to ensure that all panel applications remain highly consistent in handling device offline and abnormal interactions. **It is recommended that developers do not adjust the implementation themselves in non-essential scenarios**.
2.  **Customization Support**: If completely custom offline interaction is required in special business scenarios, developers can disable the built-in offline logic by configuring `useDefaultOffline: false`, and then monitor device status and implement interaction views themselves.
3.  **Interaction Loop**: In built-in mode, all jump paths of the offline page (such as pairing guidance, reconnection page) are handled in a closed loop within the framework. Developers do not need to concern themselves with jump protocols and page implementation.