#Usage

#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 page.

#Basic use

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

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

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

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

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
• Enable/disable alarms: setBuiltInAlarmStatus
• 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.
MiniApp Developer	1. Call getBuiltInAlarmList to query the message push list and get the supported message push list for the current device. 2. Call setBuiltInAlarmStatus to enable or disable the current message push.
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.

#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
• Add/modify custom alarm rule: addCustomAlarm
• Enable/disable custom alarm rule: setCustomAlarmStatus
• Delete custom alarm rule: deleteCustomAlarm
• Hooks: useCustomAlarm

#Workflow

Role	Operation	Example Image
MiniApp Developer	Call getCustomAlarmList to fetch the current device's automation rule list.
MiniApp Developer	Call addCustomAlarm to add or edit an alarm rule.
MiniApp Developer	Call setCustomAlarmStatus to enable or disable the alarm rule.
MiniApp Developer	Call deleteCustomAlarm to delete an alarm rule.
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.