---
name: "SmartAlarmAbility.addCustomAlarm"
mode: "api"
versionRequirements:
  - { name: "@ray-js/panel-sdk", version: "1.8.0" }
title: "addCustomAlarm"
---

## SmartAlarmAbility.addCustomAlarm

> [VERSION] @ray-js/panel-sdk >= 1.8.0

> 💡 Supports single devices only; group environments are not supported. Note: The response example is for reference only and includes fields beyond the defined response parameters. Do not use any data other than the parameters defined here; otherwise, it may cause application errors.

### Description

Create or edit a custom alert rule

### Parameters

`Params`

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `options` | `AddCustomAlarmOptions` | Yes | Alert rule configuration |

### Return Value

Type: `Promise<AddCustomAlarmResult>`

Tuple [the created/updated rule, the updated full rule list]

### Referenced Types

##### `type` AddCustomAlarmOptions

| Property | Type | Description |
| --- | --- | --- |
| `devId` | `string` | Device ID; defaults to the one from the default device environment |
| `name` | `string` | Alarm name or note |
| `preCondition` | `Object` | Preconditions for triggering the alarm |
| `condition` | `[DpId, "==" \| "<" \| ">" \| "<=" \| ">=", boolean \| number \| string][]` | DP conditions that trigger the alarm, [DpId, Operator, DpValue][] |
| `duration` | `number` | How long the DP conditions must hold before executing the action, in seconds |

##### `type` AddCustomAlarmResult

```typescript
[AddCustomAlarmBindResult, CustomAlarmList]
```

##### `type` DpId

```typescript
type DpId = number;
```

##### `type` Operator

```typescript
type Operator = '==' | '<' | '>' | '<=' | '>=';
```

##### `type` DpValue

Datapoint value type, which can be boolean, number, or string.

```typescript
export type DpValue = boolean | number | string;
```

##### `type` AddCustomAlarmBindResult

| Property | Type | Description |
| --- | --- | --- |
| `associativeEntityValue` | `string` | Associated entity value, used to distinguish alarm types |
| `associativeEntityId` | `string` | Associated entity ID, typically the DP ID |
| `bindId` | `number` | Binding ID |
| `bizDomain` | `string` | Business domain, fixed as miniAppPanelSDKAlarm for alarms |
| `enable` | `boolean` | Whether enabled |
| `sourceEntityId` | `string` | Device ID |

##### `type` CustomAlarmList

```typescript
export type CustomAlarmList = CustomAlarmRule[];
```

##### `type` CustomAlarmRule

| Property | Type | Description |
| --- | --- | --- |
| `triggerRuleId` | `string` | ID of the rule executed by the alarm |
| `triggerRuleVO` | `AlarmTriggerRuleVO` | Details of the rule that triggers the alarm; see AlarmTriggerRuleVO |
| `bizDomain` | `string` | Business domain identifier, fixed as miniAppPanelSDKAlarm in the alarm SDK |
| `associativeEntityValue` | `string` | Used when associativeEntityId is not sufficient to distinguish cases—for example, when the same DP is used but alarm types must be differentiated. You can use DpValue; generally not required. |
| `sourceEntityId` | `string` | Device ID associated with the current alarm |
| `name` | `string` | Name or note |
| `icon` | `string` | Icon |
| `bindId` | `number` | Binding ID |
| `associativeEntityId` | `string` | DP ID associated with the current alarm |
| `enable` | `boolean` | Whether enabled |

##### `type` AlarmTriggerRuleVO

| Property | Type | Description |
| --- | --- | --- |
| `ownerId` | `string` | Home ID |
| `enabled` | `boolean` | Whether the alarm rule is enabled |
| `id` | `string` | Execution rule ID |
| `name` | `string` | Alarm name or note |
| `preConditions` | `AlarmPreCondition[] \| unknown[]` | Preconditions for executing actions; see AlarmPreCondition |
| `conditions` | `CustomAlarmCondition[] \| unknown[]` | Conditions for executing actions; see CustomAlarmCondition |
| `actions` | `CustomAlarmSceneAction[] \| unknown[]` | Actions to execute; see CustomAlarmSceneAction |

##### `type` AlarmPreCondition

| Property | Type | Description |
| --- | --- | --- |
| `expr` | `CustomAlarmPreConditionExpr` | Condition expression |
| `condType` | `"timeCheck"` | Condition type, fixed as timeCheck in the alarm SDK |
| `id` | `string` | Condition ID |

##### `type` CustomAlarmCondition

| Property | Type | Description |
| --- | --- | --- |
| `id` | `string` | Condition ID |
| `ruleId` | `string` | Rule ID |
| `entityId` | `string` | Data ID |
| `entitySubIds` | `string` | Abstract sub-data ID |
| `expr` | `string` | Condition expression |

##### `type` CustomAlarmSceneAction

| Property | Type | Description |
| --- | --- | --- |
| `id` | `string` | Condition ID |
| `ruleId` | `string` | Scene ID |
| `actionExecutor` | `string` | Action type, fixed as appPushTrigger in the alarm SDK |

##### `type` CustomAlarmPreConditionExpr

| Property | Type | Description |
| --- | --- | --- |
| `timeZoneId` | `string` | Time zone ID, e.g., Asia/Shanghai |
| `start` | `string` | Start time in HH:mm, e.g., 00:00 |
| `timeInterval` | `string` | Time interval, fixed as 'custom' |
| `loops` | `string` | Repeat days; '1111111' means all seven days are on, starting from Sunday |
| `end` | `string` | End time in HH:mm, e.g., 23:59 |

##### `type` AddCustomAlarmOptions.preCondition

| Property | Type | Description |
| --- | --- | --- |
| `startTime` | `string` | Start time when the alarm can be triggered; default is all day, i.e., 00:00 |
| `endTime` | `string` | End time when the alarm can be triggered; default is all day, i.e., 23:59 |
| `loops` | `string` | Days when the alarm can be triggered; default is the whole week, i.e., '1111111' |


### Examples

#### Example

```typescript
const [newRule, allRules] = await sdm.alarm.addCustomAlarm({
  name: 'High temperature alarm',
  condition: [['temp_current', '>', 40]],
  preCondition: {
    startTime: '08:00',
    endTime: '22:00',
    loops: '1111111',
  },
});
console.log('New rule:', newRule.bindId);
```