---
title: Usage
---

# Usage

<div style={{ display: 'flex', gap: '8px', marginBottom: '16px' }}>
  <span style={{ backgroundColor: '#52c41a', color: 'white', padding: '2px 8px', borderRadius: '4px', fontSize: '12px' }}>Device Support</span>
  <span style={{ backgroundColor: '#ff4d4f', color: 'white', padding: '2px 8px', borderRadius: '4px', fontSize: '12px' }}>Group Not Support</span>
</div>

<Callout type="info" emoji="ℹ️">
The current Alarm Ability SDK provides standard abstractions for the following two types of scenarios, allowing developers to use them according to their business needs:
- Built-in alarms (alarm switch)
- Custom alarms
</Callout>

## Getting Started

> Required to import `HomeKit`, and can only be used in version `>=3.0.1`.

`SmartAlarmAbility` was introduced in `@ray-js/panel-sdk@1.8.0` and has been included as a basic example in the [Generic Abilities - Usage](/en/miniapp/solution-panel/ability/common/sdm/abilities/usage) page.

### Basic use

Here's an example of accessing generic abilities using basic JavaScript:

```ts
import { SmartAlarmAbility } from '@ray-js/panel-sdk';

// Create an instance of SmartAlarmAbility
const alarm = new SmartAlarmAbility();
// Must call init() before using the functionalities of SmartAlarmAbility
alarm.init();

// Use the functionalities of SmartAlarmAbility
alarm.getBuiltInAlarmList(params)
  .then(result => {
    // Handle the returned result
  })
  .catch(error => {
    // Handle error cases
  });
```

### Ray & SDM

Here's an example of accessing generic abilities using Ray and SDM. By integrating with SDM, you can enjoy better TypeScript type hints and the development experience provided by React Hooks:

**src/devices/index.ts**

> Create a smart device model for the sensor with built-in alarm capability

```ts
import { SmartDeviceModel, SmartAlarmAbility } from '@ray-js/panel-sdk';

const options = {
  abilities: [new SmartAlarmAbility()],
};

const devices = {
  sensor: new SmartDeviceModel<SmartDeviceSchema, { alarm: SmartAlarmAbility }>(options)
};
```

**src/app.tsx**

> Access the React ecosystem through SdmProvider

```tsx
import React from 'react';
import 'ray';
// Import other dependencies
import { kit, SdmProvider } from '@ray-js/panel-sdk';
import { devices } from '@/devices';

const { initPanelEnvironment } = kit;

interface Props {
  children: React.ReactNode;
}

initPanelEnvironment({ useDefaultOffline: true });

export default class App extends React.Component<Props> {
  onLaunch() {
    console.info('=== App onLaunch');
  }

  render() {
    return (
      <SdmProvider value={devices.sensor}>{this.props.children}</SdmProvider>
    );
  }
}
```

**src/pages/home.tsx**

> Fetch the alarm list and display it using TyList

```tsx
import React from 'react';
import { View } from '@ray-js/ray';
import { useBuiltInAlarm } from '@ray-js/panel-sdk';
import { AlarmList } from '@ray-js/api/lib/cloud/interface';
import TyList from '@ray-js/components-ty-cell';
import TySwitch from '@ray-js/components-ty-switch';

function PageSdmAlarm() {
  const { loading, data, getBuiltInAlarmList, setBuiltInAlarmStatus } = useBuiltInAlarm();

  React.useEffect(() => {
    getBuiltInAlarmList();
  }, []);

  const handleValueChange = React.useCallback(
    (item: AlarmList) => (value: boolean) => {
      setBuiltInAlarmStatus({ disabled: !value, ruleIds: item.id });
    },
    []
  );

  const rowKey = React.useCallback((item: AlarmList) => item.id, []);

  console.log('=== rerender builtInAlarm', data, loading);
  return (
    <View>
      <TyList<AlarmList>
        dataSource={data}
        renderItem={item => (
          <TyList.Item
            key={item.id}
            title={item.name}
            content={<TySwitch checked={item.enabled} onChange={handleValueChange(item)} />}
          />
        )}
        rowKey={rowKey}
      />
    </View>
  );
}
```

## Use Case

### Built-in Alarms

Some sensor devices have built-in functionality to push alarm messages. For example, a door sensor may need to push a message to the user when the door is opened or closed. To handle such fixed push notifications, some product categories have predefined templates for easy use by IoT developers. Users can customize the enablement or disablement of such message notifications in the device panel on the consumer (C) app.

#### Related APIs

- Get device alarm configuration list: [getBuiltInAlarmList](./getBuiltInAlarmList)
- Enable/disable alarms: [setBuiltInAlarmStatus](./setBuiltInAlarmStatus)
- Hooks: [useBuiltInAlarm](/en/miniapp/solution-panel/ability/common/sdm/hooks/useBuiltInAlarm)

#### Workflow

| Role                 | Operation                                                                                                                                                                                                                                                                                                                                                                                                                   | Example Image                                                            |
| :------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :----------------------------------------------------------------------- |
| IoT Developer        | In the IoT device message push configuration page, select the default message push template or customize the message push content. After the configuration is completed, the product interface will display the current supported message push list. At this point, the panel development can call the interface based on the virtual device generated through product network setup or scanning to fetch the message list. | <Image width="200px"  src="/images/panel/sdm-ability-iot.png" />         |
| MiniApp Developer    | 1. Call `getBuiltInAlarmList` to query the message push list and get the supported message push list for the current device.<br/> 2. Call `setBuiltInAlarmStatus` to enable or disable the current message push.                                                                                                                                                                                                            | <Image width="200px"  src="/images/panel/sdm-ability-builtin-get.png" /> |
| User on Consumer App | Enable or disable message push as needed. When the rule is met, the user will receive the message push on the app.                                                                                                                                                                                                                                                                                                          | <Image width="200px"  src="/images/panel/sdm-ability-demo.png" />        |

### Custom Alarms

For more complex alarm triggering rules that cannot be satisfied by the alarm switch, custom alarm scenarios are used. For example, in the temperature and humidity sensor category, users may want to adjust the upper and lower temperature limits and trigger alarms within the custom range. Users may also want to define other rules, such as triggering alarms based on specific functionalities, delayed push notifications, notification methods, and events.

#### Related APIs

- Query custom alarm rule list: [getCustomAlarmList](./getCustomAlarmList)
- Add/modify custom alarm rule: [addCustomAlarm](./addCustomAlarm)
- Enable/disable custom alarm rule: [setCustomAlarmStatus](./setCustomAlarmStatus)
- Delete custom alarm rule: [deleteCustomAlarm](./deleteCustomAlarm)
- Hooks: [useCustomAlarm](/en/miniapp/solution-panel/ability/common/sdm/hooks/useCustomAlarm)

#### Workflow

| Role                 | Operation                                                                                                                                                                       | Example Image                                                                            |
| :------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :--------------------------------------------------------------------------------------- |
| MiniApp Developer    | Call `getCustomAlarmList` to fetch the current device's automation rule list.                                                                                                   | <Image width="200px" src="/images/panel/sdm-ability-custom-get.png" preview={true} />    |
| MiniApp Developer    | Call `addCustomAlarm` to add or edit an alarm rule.                                                                                                                             | <Image width="200px" src="/images/panel/sdm-ability-custom-add.png" preview={true} />    |
| MiniApp Developer    | Call `setCustomAlarmStatus` to enable or disable the alarm rule.                                                                                                                | <Image width="200px" src="/images/panel/sdm-ability-custom-get.png" preview={true} />    |
| MiniApp Developer    | Call `deleteCustomAlarm` to delete an alarm rule.                                                                                                                               | <Image width="200px" src="/images/panel/sdm-ability-custom-delete.png" preview={true} /> |
| User on Consumer App | Configure the alarm push rules according to their needs (similar to the interaction shown in the above images). If the rules are met, the app will receive a push notification. | <Image width="200px"  src="/images/panel/sdm-ability-demo.png" preview={true} />         |