# Panel Environment Initialization

`initPanelEnvironment` is a **standard environment initialization tool** for Tuya Panel MiniApps. It is not just an API, but an integrated implementation of Tuya panel standard interaction specifications. Through a one-click call, developers can quickly access a series of standardized capabilities such as offline, Bluetooth, OTA, and fault reminders for the panel.

<Callout type="info">
  `DeviceKit` must be introduced, and the `@ray-js/ray` version must be higher than `0.10.3`.
</Callout>

## Quick Start

Calling it as early as possible at the application entry or the main page of the panel will enable the standard environment (current Panel MiniApp templates already have this API call built-in):

```typescript
import { initPanelEnvironment } from '@ray-js/ray';

// Enable standard environment initialization
initPanelEnvironment({ 
  useDefaultOffline: true, // Enable default offline reminder
});
```

---

## Core Capabilities

The `initPanelEnvironment` API deeply integrates the following standard interaction capabilities:

### 1. Connectivity and Offline Guarantee
Real-time monitoring of device online status. Provides offline mask guidance for Wi-Fi devices; provides automatic reconnection, permission detection, and status floating window display for Bluetooth devices.

> **Details**: [Connectivity and Offline Logic Description](./connectivity)

### 2. OTA Upgrade Check
Real-time detection of device firmware updates and guiding users to upgrade based on priority (mandatory/reminder).

> **Details**: [OTA Upgrade Mechanism Description](./ota)

### 3. Cloud Activation and Device Monitoring
- **Cloud Activation**: For devices requiring activation, a prompt automatically pops up after entering the panel.
- **Basic Monitoring**: Automatically register basic monitoring such as device removal and status changes, simplifying business complexity.

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

### 4. Fault List Component
When the device supports and reports function points of type `fault`, the standard fault list description automatically pops up. Currently only supports function points with `dpCode` as `fault`.

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

---

## Technical Reference

### Type Definition

```typescript
/**
 * Panel environment initialization parameters
 */
export interface InitPanelEnvironmentOptions {
  /**
   * @description Whether to use the default offline pop-up
   * @default true
   */
  useDefaultOffline?: boolean;
  /**
   * @description Whether Bluetooth prompts need to block interaction
   * @default false
   */
  bleCover?: boolean;
  /**
   * @description Bluetooth and toast prompt custom top height (used for custom navigation)
   * @default 0
   */
  customTop?: string;
  /**
   * @description Bluetooth connection type, default 0
   * 0: Both gateway and app are required, the default value, either local or gateway can take effect
   * 1: App only, only determines if local is online and if local connection is successful
   * 2: Gateway only, only determines if the gateway is online and if the gateway connection is successful
   * @default 0
   */
  bleConnectType?: number;
  /**
   * @description Whether to display the Bluetooth connection status prompt
   * @default true
   * @version 2.10.4
   */
  showBLEToast?: boolean;
  /**
   * @description Current device id, default is undefined, means automatically retrieved from the query parameters of the mini program
   * @default undefined
   */
  deviceId?: string;
  /**
   * @description Current group id, default is undefined, means automatically retrieved from the query parameters of the mini program
   * @default undefined
   */
  groupId?: string;
  /**
   * @description WeChat detailed page route
   * @default undefined
   */
  deviceDetailPage?: string;
  /**
   * @description Whether to show fault prompt
   * @default false
   */
  showFault?: boolean;
  /**
   * @description Configure whether to automatically connect Bluetooth, supported from basic library 2.27.0
   * @default true
   */
  shouldConnectBleAuto?: boolean;
  /**
   * @description Automatically check for activation, supported from basic library 2.27.0
   * @default true
   */
  autoCheckActivation?: boolean;
  /**
   * @description Disable automatic check for firmware upgrade, supported from basic library 2.27.0
   * @default false
   * @see [OTA Upgrade Logic](./ota)
   */
  disableOtaDialog?: boolean;
}

/**
 * Initialize panel environment
 * @param options configuration items
 */
export declare function initPanelEnvironment(
  options?: InitPanelEnvironmentOptions,
): void;
```

---

### Parameter Details

#### bleCover
Whether to add an overlay to block interface interaction when the Bluetooth status floating window is displayed. Usually, if some functions can be used when the device is offline (such as: data chart viewing), the interface does not need to be covered.

```typescript | pure
initPanelEnvironment({ useDefaultOffline: true, bleCover: true });
```

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

#### customTop
When using a custom status bar, the distance between the Bluetooth status floating window and the top can be customized through this property. This parameter accepts standard CSS length values (such as: '100px', '10%', etc.).

```typescript | pure
initPanelEnvironment({ useDefaultOffline: true, customTop: '120px' });
```

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

#### bleConnectType

In the standard logic, selection of network connection methods for Bluetooth devices:
- **0**: Try both phone direct connection and gateway connection (default).
- **1**: Only use phone direct connection.
- **2**: Only use gateway connection.

#### showBLEToast
Whether to display a Toast prompt when the Bluetooth device connection is successful or fails.

```typescript | pure
initPanelEnvironment({ useDefaultOffline: true, showBLEToast: true });
```

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

#### showFault
If set to `true`, the built-in capability is used to display device faults. Currently only supports fault display for `dpCode` as `fault`.

```typescript | pure
initPanelEnvironment({ useDefaultOffline: true, showFault: true });
```

---

### Underlying Atomic Implementation
`initPanelEnvironment` is deeply encapsulated based on the following underlying APIs:

- [ty.panel.initPanelKit](/en/miniapp/develop/ray/api/other/initPanelKit)
- [registerDeviceListListener](/en/miniapp/develop/ray/api/device-info/info/registerDeviceListListener)
- [getDeviceInfo](/en/miniapp/develop/ray/api/device-info/info/getDeviceInfo)
- [getSystemInfoSync](/en/miniapp/develop/ray/api/base/system/getSystemInfoSync)
- [authorizeStatus](/en/miniapp/develop/ray/api/authorize/authorizeStatus)
- [openMiniWidget](/en/miniapp/develop/ray/api/base/container/MiniWidgetDialog)
- [onWidgetDismiss](/en/miniapp/develop/ray/api/base/container/MiniWidgetDialog#miniwidgetdialogonwidgetdismiss)
- [offWidgetDismiss](/en/miniapp/develop/ray/api/base/container/MiniWidgetDialog#miniwidgetdialogoffwidgetdismiss)
- [dismissMiniWidget](/en/miniapp/develop/ray/api/base/container/MiniWidgetDialog#miniwidgetdialogdismissminiwidget)
- [authorize](/en/miniapp/develop/ray/api/authorize/authorize)
- [getDeviceOnlineType](/en/miniapp/develop/ray/api/device-info/info/getDeviceOnlineType)
- [connectBluetoothDevice](/en/miniapp/develop/ray/api/bluetooth/single/connectBluetoothDevice)
- [subscribeBLEConnectStatus](/en/miniapp/develop/ray/api/bluetooth/single/subscribeBLEConnectStatus)
- [onBLEConnectStatusChange](/en/miniapp/develop/ray/api/bluetooth/single/onBLEConnectStatusChange)
- [onBluetoothAdapterStateChange](/en/miniapp/develop/ray/api/device/bluetooth/onBluetoothAdapterStateChange)

---

## Precautions

1. **Standardized Logic Recommendation**: The logic provided by `initPanelEnvironment` is the standard specification of Tuya panels. We recommend that developers prioritize using this interface and only refer to atomic interfaces for customization in special scenarios.
2. **OTA Logic Enclosure**: The OTA upgrade mechanism (detection, pop-ups, and jumps) currently does not support developer customization. Please be sure to complete it through the built-in capabilities.