Vibrator Development

When to Use

You can set different vibration effects as needed, for example, customizing the vibration intensity, frequency, and duration for button touches, alarm clocks, and incoming calls.

For details about the APIs, see Vibrator.

Available APIs

Custom Vibration Format

Custom vibration enables you to design desired vibration effects by customizing a vibration configuration file and orchestrating vibration forms based on the corresponding rules.

The custom vibration configuration file is in JSON format. An example file is as follows:

{
    "MetaData": {
        "Create": "2023-01-09",
        "Description": "a haptic case",
        "Version": 1.0,
        "ChannelNumber": 1
    },
    "Channels": [
        {
            "Parameters": {
                "Index": 1
            },
            "Pattern": [
                {
                    "Event": {
                        "Type": "transient",
                        "StartTime": 0,
                        "Parameters": {
                            "Intensity": 100,
                            "Frequency": 31
                        }
                    }
                },
                {
                    "Event": {
                        "Type": "continuous",
                        "StartTime": 100,
                        "Duration": 54,
                        "Parameters": {
                            "Intensity": 38,
                            "Frequency": 30
                        }
                    }
                }
            ]
        }
    ]
}

This JSON file contains two attributes: MetaData and Channels.

• MetaData contains information about the file header. You can add the following attributes under MetaData:
  • Version: version number of the file format, which is forward compatible. Currently, only version 1.0 is supported. This parameter is mandatory.
  • ChannelNumber: number of channels for vibration. Currently, only one channel is supported, and the value is fixed at 1. This parameter is mandatory.
  • Create: time when the file was created. This parameter is optional.
  • Description: additional information such as the vibration effect and creation information. This parameter is optional.
• Channels provides information about the vibration channel. It is a JSON array that holds information about each channel. It contains two attributes: Parameters and Pattern.
  • Parameters provides parameters related to the channel. Under it, Index indicates the channel ID. The value is fixed at 1 for a single channel. This parameter is mandatory.
  • Pattern indicates the vibration sequence. It is a JSON array. Under it, Event indicates a vibration event, which can be either of the following types:
    • transient: short vibration
    • continuous: long vibration

The table below describes the parameters under Event.

The following requirements must be met:

How to Develop

1. Before using the vibrator on a device, you must declare the ohos.permission.VIBRATE permission. For details about how to configure a permission, see Declaring Permissions.

2. Start vibration with the specified effect and attribute.

import vibrator from '@ohos.vibrator';
import { BusinessError } from '@ohos.base';

try {
  // To use startVibration, you must configure the ohos.permission.VIBRATE permission.
  vibrator.startVibration({
    type: 'time',
    duration: 1000,
  }, {
    id: 0,
    usage: 'alarm'
  }, (error: BusinessError) => {
    if (error) {
      console.error(`Failed to start vibration. Code: ${error.code}, message: ${error.message}`);
      return;
    }
    console.info('Succeed in starting vibration.');
  });
} catch (err) {
  let e: BusinessError = err as BusinessError;
  console.error(`An unexpected error occurred. Code: ${e.code}, message: ${e.message}`);
}

3. Stop vibration in the specified mode.

import vibrator from '@ohos.vibrator';
import { BusinessError } from '@ohos.base';

try {
  // Stop vibration in VIBRATOR_STOP_MODE_TIME mode. To use stopVibration, you must configure the ohos.permission.VIBRATE permission.
  vibrator.stopVibration(vibrator.VibratorStopMode.VIBRATOR_STOP_MODE_TIME, (error: BusinessError) => {
    if (error) {
      console.error(`Failed to stop vibration. Code: ${error.code}, message: ${error.message}`);
      return;
    }
    console.info('Succeeded in stopping vibration.');
  })
} catch (err) {
  let e: BusinessError = err as BusinessError;
  console.error(`An unexpected error occurred. Code: ${e.code}, message: ${e.message}`);
}

4. Stop vibration in all modes.

import vibrator from '@ohos.vibrator';
import { BusinessError } from '@ohos.base';

try {
  vibrator.startVibration({
    type: 'time',
    duration: 1000,
  }, {
    id: 0,
    usage: 'alarm'
  }, (error: BusinessError) => {
    if (error) {
      console.error(`Failed to start vibration. Code: ${error.code}, message: ${error.message}`);
      return;
    }
    console.info('Succeed in starting vibration');
  });
  // Stop vibration in all modes.
  vibrator.stopVibration((error: BusinessError) => {
    if (error) {
      console.error(`Failed to stop vibration. Code: ${error.code}, message: ${error.message}`);
      return;
    }
    console.info('Succeed in stopping vibration');
  })
} catch (error) {
  let e: BusinessError = error as BusinessError;
  console.error(`An unexpected error occurred. Code: ${e.code}, message: ${e.message}`);
}

5. Check whether the passed effect ID is supported.

import vibrator from '@ohos.vibrator';
import { BusinessError } from '@ohos.base';

try {
  // Check whether 'haptic.clock.timer' is supported.
  vibrator.isSupportEffect('haptic.clock.timer', (err: BusinessError, state: boolean) => {
    if (err) {
      console.error(`Failed to query effect. Code: ${err.code}, message: ${err.message}`);
      return;
    }
    console.info('Succeed in querying effect');
    if (state) {
      try {
        // To use startVibration, you must configure the ohos.permission.VIBRATE permission.
        vibrator.startVibration({
          type: 'preset',
          effectId: 'haptic.clock.timer',
          count: 1,
        }, {
          usage: 'unknown'
        }, (error: BusinessError) => {
          if (error) {
            console.error(`Failed to start vibration. Code: ${error.code}, message: ${error.message}`);
          } else {
            console.info('Succeed in starting vibration');
          }
        });
      } catch (error) {
        let e: BusinessError = error as BusinessError;
        console.error(`An unexpected error occurred. Code: ${e.code}, message: ${e.message}`);
      }
    }
  })
} catch (error) {
  let e: BusinessError = error as BusinessError;
  console.error(`An unexpected error occurred. Code: ${e.code}, message: ${e.message}`);
}

6. Start and stop custom vibration.

import vibrator from '@ohos.vibrator';
import { BusinessError } from '@ohos.base';
import resourceManager from '@ohos.resourceManager';

// Obtain the file descriptor of the vibration configuration file.
async function getRawfileFd(fileName: string): Promise<resourceManager.RawFileDescriptor> {
  let rawFd = await getContext().resourceManager.getRawFd(fileName);
  return rawFd;
}

// Close the file descriptor of the vibration configuration file.
async function closeRawfileFd(fileName: string): Promise<void> {
  await getContext().resourceManager.closeRawFd(fileName)
}

// Play the custom vibration. To use startVibration and stopVibration, you must configure the ohos.permission.VIBRATE permission.
async function playCustomHaptic(fileName: string): Promise<void> {
  try {
    let rawFd = await getRawfileFd(fileName);
    vibrator.startVibration({
      type: "file",
      hapticFd: { fd: rawFd.fd, offset: rawFd.offset, length: rawFd.length }
    }, {
      usage: "alarm"
    }).then(() => {
      console.info('Succeed in starting vibration');
    }, (error: BusinessError) => {
      console.error(`Failed to start vibration. Code: ${error.code}, message: ${error.message}`);
    });
    vibrator.stopVibration((error: BusinessError) => {
      if (error) {
        console.error(`Failed to stop vibration. Code: ${error.code}, message: ${error.message}`);
        return;
      }
      console.info('Succeed in stopping vibration');
    })
    await closeRawfileFd(fileName);
  } catch (error) {
    let e: BusinessError = error as BusinessError;
    console.error(`An unexpected error occurred. Code: ${e.code}, message: ${e.message}`);
  }
}