English | [简体中文](./README-zh_CN.md)

# @ray/light-dp-bind-functional-utils Development Documentation

## Configuration

1. Configure the routing information for functional pages.

- Ray Framework

```typescript
export const thing = {
  window: {
    backgroundColor: '#f2f4f6',
    navigationBarTitleText: '',
    navigationBarBackgroundColor: '#f2f4f6',
    navigationBarTextStyle: 'black',
  },
  darkmode: false,
  functionalPages: {
    settings: {
      // Device details page
      appid: 'tycryc71qaug8at6yt',
      entryCode: 'entrye0n05idydmmfv',
    },
    details: {
      // DP sync device binding functional page
      appid: 'tyavb2zybiicrluxwk',
      entryCode: 'entryeo3eejedwj6sw',
    },
  },
};
```

- Native Mini Program

```json
{
  ...
  "functionalPages": {
    "settings": {
      "appid": "tycryc71qaug8at6yt",
      "entryCode": "entrye0n05idydmmfv"
    },
    "details": {
      "appid": "tyavb2zybiicrluxwk",
      "entryCode": "entryeo3eejedwj6sw"
    }
  },
  ...
}
```

## Constants

### `BIND_TYPE`

Binding type enumeration, commonly used in parameters such as `openDeviceOrDimmingSelect`.

| Key                  | Value | Description                        |
|----------------------|-------|------------------------------------|
| sceneControl         | 1     | Scene control (linkage interface)  |
| sceneDimming         | 2     | Scene dimming                      |
| lightControl         | 3     | Light control                      |
| curtainControl       | 4     | Curtain control                    |
| airConditionerControl| 5     | Air conditioner control            |
| tvControl            | 6     | TV control                         |
| virtualControl       | 7     | Non-smart light                    |
| musicControl         | 8     | Music control                      |
| voiceCentralControl  | 9     | Voice central control              |
| distributeBle        | 10    | Distributed BLE                    |
| bleDimming           | 11    | BLE dimming                        |
| bleLight             | 12    | BLE light                          |
| bleCurtain           | 13    | BLE curtain                        |
| distributeBleDouble  | 18    | Distributed BLE lighting scene - dual state      |
| bleLightNegation     | 19    | BLE SoC solution light control - negation        |
| bleVirtualControl    | 23    | BLE virtual device                               |

---

## API List

### Get Scene List

#### `getSceneList(params): Promise<{result: Array<any>}>`

Get the list of scenes that can be bound.

**Parameters:**

- `roomId: string` Room ID
- `masterDpId: number` Master device DPID
- `masterDevId: string` Master device ID
- `bindType?: number` Binding type

---

### Get Light/Linkage/Dimming List

#### `getLightAndLinkage(params: GETSceneListParams): Promise<GETSceneListResult>`

Filter out lights, linkage, and dimming from the scene list.

---

### Get Available Functions for Specific DP Points

#### `getAvailableFunction(params: { masterDevId: string; masterDpIds: string; }): Promise<{ result: Array<any> }>`

Get which functions are available.

**Parameters:**

- `masterDevId: string` Master device ID
- `masterDpIds?: string` Master device DPID, separated by commas

**Return Value:**

- `result` List of available functions, e.g. `[1,2,3,4,5]`

#### `getAvailableFunctionList(params: { masterDevId: string; masterDpIds: string; }): Promise<Array<SceneItem>>`

Get the list of available functions, merged with local configuration.

**Parameters:**

- `masterDevId: string` Master device ID
- `masterDpIds?: string` Master device DPID, separated by commas

**Return Value:**

- `result` List of available functions, e.g.:

```json
[
  {
    "title": "Bind regular scene",
    "desc": "After binding a 'regular scene', clicking the button can execute the corresponding scene.",
    "tip": "(Single state)",
    "bindType": 1,
    "icon": "/_assets/mode_scene-ADC62VSZ.png",
    "nextPage": "/pages/sceneSelection/index?type=1",
    "isBindDevice": false,
    "showNoRoom": {
        "isSupport": true,
        "notSupport": true
    }
  },
  {
    "title": "Bind distributed BLE scene",
    "desc": "After binding a 'regular scene (single state)', clicking the button can execute the corresponding scene.",
    "tip": "(Single state)",
    "icon": "/_assets/mode_scene-ADC62VSZ.png",
    "bindType": 10,
    "nextPage": "/pages/deviceSelection/index?type=10",
    "isBindDevice": false,
    "showNoRoom": {
        "isSupport": true,
        "notSupport": false
    }
  }
]
```

---

### Get Binding Information

#### `getBindInfo(params: { masterDevId: string; masterDpIds: string; }): Promise<{ result: Array<any> }>`

Get binding information.

**Parameters:**

- `masterDevId: string` Master device ID
- `masterDpIds?: string` Master device DPID, separated by commas

**Return Value:**

- `result` List of binding information, e.g.:

```json
[
  {
    "bindStatus": 2,
    "bindType": 1,
    "masterDevId": "vdevo174789587785064",
    "masterDpId": 1,
    "slaveBizIcon": "https://images.tuyacn.com/smart/rule/glyphicons/label.png",
    "slaveBizIconId": 25,
    "slaveBizId": "S5rKLicwZjLM9cEq",
    "slaveBizName": "\"Test\" Remaining available power cleared: Clear off",
    "slaveBizType": 8
  }
]
```

---

### Check if Master Device Can Create Group (Relay)

#### `checkGroupCreatable(ids: string, devId?: string): Promise<any>`

- `ids` Master device DPID, separated by commas
- `devId` Master device ID (optional)

---

### Open Device or Dimming Selection

#### `openDeviceOrDimmingSelect(params: DeviceSelectParams): Promise<void>`

**Parameter structure:**

```ts
{
  type: BIND_TYPE[keyof typeof BIND_TYPE]; // Binding type
  buttonId: string; // Button ID
  dpId: number; // DPID
  code: string; // Device code
  homeId?: number; // Home ID (optional, will be automatically obtained if not provided)
  preset?: Record<string, any>; // Preset content (optional)
}
```

---

### Open Scene Selection (One-click Execution)

#### `openSceneSelect(params: SceneSelectParams): Promise<void>`

**Parameter structure is the same as above, except for the type field.**

---

### Bind or View Virtual Device Details

#### `openVirtualDeviceBind(params: VirtualDeviceBindParams): Promise<void>`

**Parameter structure:**

```ts
{
  buttonId: string;
  dpId: number;
  code: string;
  homeId?: number;
  groupExecuteDpId?: number; // Group execution dpId
  bindRule?: any; // Binding rule
  preset?: Record<string, any>;
}
```

---

### Open Binding Details (Except Virtual Devices)

#### `openBindDetail(params: BindDetailParams): Promise<void>`

**Parameter structure:**

```ts
{
  buttonId: string;
  dpId: number;
  code: string;
  homeId?: number;
  bindRule?: any;
  preset?: Record<string, any>;
}
```

---

### 打开继电器配置页面（单独配置所有继电器的页面）

#### `openRelayConfig(params?: RelayConfigParams): Promise<void>`

**参数结构：**

```ts
{
  homeId?: number | string; // 家庭ID（可选，未传会自动获取）
}
```

---

### 打开睡眠模式配置页面

#### `openSleepModeConfig(params?: SleepModeConfigParams): Promise<void>`

**参数结构：**

```ts
{
  homeId?: number | string; // 家庭ID（可选，未传会自动获取）
}
```

---

## Preset Parameter Description

All `openXXX` methods support the `preset` parameter, which can be used for preset content. For example:

```ts
openDeviceOrDimmingSelect({
  ...,
  preset: {
    actions: {
      '1': { icon: require('@/res/button.png'), title: 'Light 1', desc: 'Description 1' },
    }
  }
})
```

---

## Related Files

- index.ts
- api.ts
- interface.d.ts

For detailed type definitions, please refer to interface.d.ts.