@ohos.usbManager.serial (Serial Port Management)

This module provides the serial port management functions, including enabling and disabling the serial port of the device, writing and reading data, setting and obtaining the configuration parameters of the serial port, and managing permissions.

NOTE

The initial APIs of this module are supported since API version 18. Newly added APIs will be marked with a superscript to indicate their earliest API version.

Modules to Import

import { serialManager } from '@kit.BasicServicesKit';

serialManager.getPortList

getPortList(): Readonly<serialport>[];

Obtains the serial port device list, including the device name and port number.

System capability: SystemCapability.USB.USBManager.Serial

Returns

Example

import { JSON } from '@kit.ArkTS';
import { serialManager } from '@kit.BasicServicesKit';

// Obtain the serial port device list.
let portList: serialManager.SerialPort[] = serialManager.getPortList();
console.info('usbSerial portList: ' + JSON.stringify(portList));
if (portList === undefined||portList.length === 0) {
  console.info('usbSerial portList is empty');
  return;
}
let portId: number = portList[0].portId;

serialManager.hasSerialRight

hasSerialRight(portId: number): boolean;

Checks whether the application has the permission to access the serial port device. When an application is restarted after exiting, you need to request the permission from the user again.

System capability: SystemCapability.USB.USBManager.Serial

Parameters

Returns

Error codes

For details about the error codes, see USB Service Error Codes.

Example

import { JSON } from '@kit.ArkTS';
import { serialManager } from '@kit.BasicServicesKit';

// Obtain the serial port list.
let portList: serialManager.SerialPort[] = serialManager.getPortList();
console.info('portList: ', JSON.stringify(portList));
if (portList === undefined||portList.length === 0) {
  console.info('portList is empty');
  return;
}
let portId: number = portList[0].portId;

// Check whether the device can be accessed by the application.
if (serialManager.hasSerialRight(portId)) {
  console.info('The serial port is accessible');
} else {
  console.info('No permission to access the serial port');
}

serialManager.requestSerialRight

requestSerialRight(portId: number): Promise<boolean>

Requests the permission for the application to access the serial port device. After the application exits, the access permission on the serial port device is automatically removed. After the application is restarted, you need to request the permission again.

System capability: SystemCapability.USB.USBManager.Serial

Parameters

Returns

Error codes

For details about the error codes, see USB Service Error Codes.

Example

import { JSON } from '@kit.ArkTS';
import { serialManager } from '@kit.BasicServicesKit';

// Obtain the serial port list.
let portList: serialManager.SerialPort[] = serialManager.getPortList();
console.info('usbSerial portList: ' + JSON.stringify(portList));
if (portList === undefined||portList.length === 0) {
  console.info('usbSerial portList is empty');
  return;
}
let portId: number = portList[0].portId;

// Check whether the device can be accessed by the application.
if (!serialManager.hasSerialRight(portId)) {
  await serialManager.requestSerialRight(portId).then(result => {
    if (!result) {
      // If the application does not have the access permission and is not granted by the user, the application exits.
      console.info('user is not granted the operation permission');
      return;
    } else {
      console.info('grant permission successfully');
    }
  });
}

serialManager.open

open(portId: number): void;

Opens a serial port device.

System capability: SystemCapability.USB.USBManager.Serial

Parameters

Error codes

For details about the error codes, see USB Service Error Codes.

Example

import { JSON } from '@kit.ArkTS';
import { serialManager } from '@kit.BasicServicesKit';

// Obtain the serial port list.
let portList: serialManager.SerialPort[] = serialManager.getPortList();
console.info('usbSerial portList: ' + JSON.stringify(portList));
if (portList === undefined||portList.length === 0) {
  console.info('usbSerial portList is empty');
  return;
}
let portId: number = portList[0].portId;

// Check whether the device can be accessed by the application.
if (!serialManager.hasSerialRight(portId)) {
  await serialManager.requestSerialRight(portId).then(result => {
    if (!result) {
      // If the application does not have the access permission and is not granted by the user, the application exits.
      console.info('user is not granted the operation  permission');
      return;
    } else {
      console.info('grant permission successfully');
    }
  });
}

// Open a serial port device.
try {
  serialManager.open(portId)
  console.info('open usbSerial success, portId: ' + portId);
} catch (error) {
  console.error('open usbSerial error, ' + JSON.stringify(error));
}

serialManager.getAttribute

getAttribute(portId: number): Readonly<SerialAttribute>;

Obtains the configuration parameters of a specified serial port.

System capability: SystemCapability.USB.USBManager.Serial

Parameters

Returns

Error codes

For details about the error codes, see USB Service Error Codes.

Example

import { JSON } from '@kit.ArkTS';
import { serialManager } from '@kit.BasicServicesKit';

// Obtain the serial port list.
let portList: serialManager.SerialPort[] = serialManager.getPortList();
console.info('usbSerial portList: ' + JSON.stringify(portList));
if (portList === undefined||portList.length === 0) {
  console.info('usbSerial portList is empty');
  return;
}
let portId: number = portList[0].portId;

// Check whether the device can be accessed by the application.
if (!serialManager.hasSerialRight(portId)) {
  await serialManager.requestSerialRight(portId).then(result => {
    if (!result) {
      // If the application does not have the access permission and is not granted by the user, the application exits.
      console.info('user is not granted the operation  permission');
      return;
    } else {
      console.info('grant permission successfully');
    }
  });
}

// Open a serial port device.
try {
  serialManager.open(portId)
  console.info('open usbSerial success, portId: ' + portId);
} catch (error) {
  console.error('open usbSerial error, ' + JSON.stringify(error));
}

// Obtain the serial port configuration.
try {
  let attribute: serialManager.SerialAttribute = serialManager.getAttribute(portId);
  if (attribute === undefined) {
    console.error('getAttribute usbSerial error, attribute is undefined');
  } else {
    console.info('getAttribute usbSerial success, attribute: ' + JSON.stringify(attribute));
  }
} catch (error) {
  console.error('getAttribute usbSerial error, ' + JSON.stringify(error));
}

serialManager.setAttribute

setAttribute(portId: number, attribute: SerialAttribute): void;

Sets the parameters of the serial port. If this method is not called, the default configuration parameters are used (baud rate: 9600 bit/s; data bit: 8; parity bit: 0; stop bit: 1).

System capability: SystemCapability.USB.USBManager.Serial

Parameters

Error codes

For details about the error codes, see USB Service Error Codes.

Example

import { JSON } from '@kit.ArkTS';
import { serialManager } from '@kit.BasicServicesKit';

// Obtain the serial port list.
let portList: serialManager.SerialPort[] = serialManager.getPortList();
console.info('usbSerial portList: ' + JSON.stringify(portList));
if (portList === undefined||portList.length === 0) {
  console.info('usbSerial portList is empty');
  return;
}
let portId: number = portList[0].portId;

// Check whether the device can be accessed by the application.
if (!serialManager.hasSerialRight(portId)) {
  await serialManager.requestSerialRight(portId).then(result => {
    if (!result) {
      // If the application does not have the access permission and is not granted by the user, the application exits.
      console.info('user is not granted the operation  permission');
      return;
    } else {
      console.info('grant permission successfully');
    }
  });
}

// Open a serial port device.
try {
  serialManager.open(portId)
  console.info('open usbSerial success, portId: ' + portId);
} catch (error) {
  console.error('open usbSerial error, ' + JSON.stringify(error));
}

// Set the serial port configuration.
try {
  let attribute: serialManager.SerialAttribute = {
    baudRate: serialManager.BaudRates.BAUDRATE_9600,
    dataBits: serialManager.DataBits.DATABIT_8,
    parity: serialManager.Parity.PARITY_NONE,
    stopBits: serialManager.StopBits.STOPBIT_1
  }
  serialManager.setAttribute(portId, attribute);
  console.info('setAttribute usbSerial success, attribute: ' + JSON.stringify(attribute));
} catch (error) {
  console.error('setAttribute usbSerial error, ' + JSON.stringify(error));
}

serialManager.read

read(portId: number, buffer: Uint8Array, timeout?: number): Promise<number>;

Reads data from the serial port device asynchronously.

System capability: SystemCapability.USB.USBManager.Serial

Parameters

Returns

Error codes

For details about the error codes, see USB Service Error Codes.

Example

import { JSON } from '@kit.ArkTS';
import { serialManager } from '@kit.BasicServicesKit';

// Obtain the serial port list.
let portList: serialManager.SerialPort[] = serialManager.getPortList();
console.info('usbSerial portList: ' + JSON.stringify(portList));
if (portList === undefined||portList.length === 0) {
  console.info('usbSerial portList is empty');
  return;
}
let portId: number = portList[0].portId;

// Check whether the device can be accessed by the application.
if (!serialManager.hasSerialRight(portId)) {
  await serialManager.requestSerialRight(portId).then(result => {
    if (!result) {
      // If the application does not have the access permission and is not granted by the user, the application exits.
      console.info('user is not granted the operation  permission');
      return;
    } else {
      console.info('grant permission successfully');
    }
  });
}

// Open a serial port device.
try {
  serialManager.open(portId)
  console.info('open usbSerial success, portId: ' + portId);
} catch (error) {
  console.error('open usbSerial error, ' + JSON.stringify(error));
}

// Read data asynchronously.
let readBuffer: Uint8Array = new Uint8Array(64);
serialManager.read(portId, readBuffer, 2000).then((size: number) => {
  console.info('read usbSerial success, readBuffer: ' + readBuffer.toString());
}).catch((error: Error) => {
  console.error('read usbSerial error, ' + JSON.stringify(error));
})

serialManager.readSync

readSync(portId: number, buffer: Uint8Array, timeout?: number): number;

Reads data from the serial port device synchronously.

System capability: SystemCapability.USB.USBManager.Serial

Parameters

Returns

Error codes

For details about the error codes, see USB Service Error Codes.

Example

import { JSON } from '@kit.ArkTS';
import { serialManager } from '@kit.BasicServicesKit';

// Obtain the serial port list.
let portList: serialManager.SerialPort[] = serialManager.getPortList();
console.info('usbSerial portList: ' + JSON.stringify(portList));
if (portList === undefined||portList.length === 0) {
  console.info('usbSerial portList is empty');
  return;
}
let portId: number = portList[0].portId;

// Check whether the device can be accessed by the application.
if (!serialManager.hasSerialRight(portId)) {
  await serialManager.requestSerialRight(portId).then(result => {
    if (!result) {
      // If the application does not have the access permission and is not granted by the user, the application exits.
      console.info('user is not granted the operation  permission');
      return;
    } else {
      console.info('grant permission successfully');
    }
  });
}

// Open a serial port device.
try {
  serialManager.open(portId)
  console.info('open usbSerial success, portId: ' + portId);
} catch (error) {
  console.error('open usbSerial error, ' + JSON.stringify(error));
}

// Read data synchronously.
let readSyncBuffer: Uint8Array = new Uint8Array(64);
try {
  serialManager.readSync(portId, readSyncBuffer, 2000);
  console.info('readSync usbSerial success, readSyncBuffer: ' + readSyncBuffer.toString());
} catch (error) {
  console.error('readSync usbSerial error, ' + JSON.stringify(error));
}

serialManager.write

write(portId: number, buffer: Uint8Array, timeout?: number): Promise<number>;

Writes data to the serial port device asynchronously.

System capability: SystemCapability.USB.USBManager.Serial

Parameters

Returns

Error codes

For details about the error codes, see USB Service Error Codes.

Example

import { JSON } from '@kit.ArkTS';
import { serialManager } from '@kit.BasicServicesKit';

// Obtain the serial port list.
let portList: serialManager.SerialPort[] = serialManager.getPortList();
console.info('usbSerial portList: ' + JSON.stringify(portList));
if (portList === undefined||portList.length === 0) {
  console.info('usbSerial portList is empty');
  return;
}
let portId: number = portList[0].portId;

// Check whether the device can be accessed by the application.
if (!serialManager.hasSerialRight(portId)) {
  await serialManager.requestSerialRight(portId).then(result => {
    if (!result) {
      // If the application does not have the access permission and is not granted by the user, the application exits.
      console.info('user is not granted the operation  permission');
      return;
    } else {
      console.info('grant permission successfully');
    }
  });
}

// Open a serial port device.
try {
  serialManager.open(portId)
  console.info('open usbSerial success, portId: ' + portId);
} catch (error) {
  console.error('open usbSerial error, ' + JSON.stringify(error));
}

// Write data asynchronously.
let writeBuffer: Uint8Array = new Uint8Array(buffer.from('Hello World', 'utf-8').buffer)
serialManager.write(portId, writeBuffer, 2000).then((size: number) => {
  console.info('write usbSerial success, writeBuffer: ' + writeBuffer.toString());
}).catch((error: Error) => {
  console.error('write usbSerial error, ' + JSON.stringify(error));
})

serialManager.writeSync

writeSync(portId: number, buffer: Uint8Array, timeout?: number): number;

Writes data to the serial port device synchronously.

System capability: SystemCapability.USB.USBManager.Serial

Parameters

Returns

Error codes

For details about the error codes, see USB Service Error Codes.

Example

import { JSON } from '@kit.ArkTS';
import { serialManager } from '@kit.BasicServicesKit';

// Obtain the serial port list.
let portList: serialManager.SerialPort[] = serialManager.getPortList();
console.info('usbSerial portList: ' + JSON.stringify(portList));
if (portList === undefined||portList.length === 0) {
  console.info('usbSerial portList is empty');
  return;
}
let portId: number = portList[0].portId;

// Check whether the device can be accessed by the application.
if (!serialManager.hasSerialRight(portId)) {
  await serialManager.requestSerialRight(portId).then(result => {
    if (!result) {
      // If the application does not have the access permission and is not granted by the user, the application exits.
      console.info('user is not granted the operation  permission');
      return;
    } else {
      console.info('grant permission successfully');
    }
  });
}

// Open a serial port device.
try {
  serialManager.open(portId)
  console.info('open usbSerial success, portId: ' + portId);
} catch (error) {
  console.error('open usbSerial error, ' + JSON.stringify(error));
}

// Write data synchronously.
let writeSyncBuffer: Uint8Array = new Uint8Array(buffer.from('Hello World', 'utf-8').buffer)
try {
  serialManager.writeSync(portId, writeSyncBuffer, 2000);
  console.info('writeSync usbSerial success, writeSyncBuffer: ' + writeSyncBuffer.toString());
} catch (error) {
  console.error('writeSync usbSerial error, ' + JSON.stringify(error));
}

serialManager.close

close(portId: number): void;

Closes the serial port device.

System capability: SystemCapability.USB.USBManager.Serial

Parameters

Error codes

For details about the error codes, see USB Service Error Codes.

Example

import { JSON } from '@kit.ArkTS';
import { serialManager } from '@kit.BasicServicesKit';

// Obtain the serial port list.
let portList: serialManager.SerialPort[] = serialManager.getPortList();
console.info('usbSerial portList: ' + JSON.stringify(portList));
if (portList === undefined||portList.length === 0) {
  console.info('usbSerial portList is empty');
  return;
}
let portId: number = portList[0].portId;

// Check whether the device can be accessed by the application.
if (!serialManager.hasSerialRight(portId)) {
  await serialManager.requestSerialRight(portId).then(result => {
    if (!result) {
      // If the application does not have the access permission and is not granted by the user, the application exits.
      console.info('user is not granted the operation  permission');
      return;
    } else {
      console.info('grant permission successfully');
    }
  });
}

// Open a serial port device.
try {
  serialManager.open(portId)
  console.info('open usbSerial success, portId: ' + portId);
} catch (error) {
  console.error('open usbSerial error, ' + JSON.stringify(error));
}

// Close the serial port device.
try {
  serialManager.close(portId);
  console.info('close usbSerial success, portId: ' + portId);
} catch (error) {
  console.error('close usbSerial error, ' + JSON.stringify(error));
}

serialManager.cancelSerialRight

cancelSerialRight(portId: number): void;

Cancels the permission to access the serial port device when the application is running. This API is used to close the enabled serial port device.

System capability: SystemCapability.USB.USBManager.Serial

Parameters

Error codes

For details about the error codes, see USB Service Error Codes.

Example

import { JSON } from '@kit.ArkTS';
import { serialManager } from '@kit.BasicServicesKit';

// Obtain the serial port list.
let portList: serialManager.SerialPort[] = serialManager.getPortList();
console.info('usbSerial portList: ' + JSON.stringify(portList));
if (portList === undefined||portList.length === 0) {
  console.info('usbSerial portList is empty');
  return;
}
let portId: number = portList[0].portId;

// Check whether the device can be accessed by the application.
if (!serialManager.hasSerialRight(portId)) {
  await serialManager.requestSerialRight(portId).then(result => {
    if (!result) {
      // If the application does not have the access permission and is not granted by the user, the application exits.
      console.info('user is not granted the operation  permission');
      return;
    } else {
      console.info('grant permission successfully');
    }
  });
}

// Cancel the granted permission.
try {
  serialManager.cancelSerialRight(portId);
  console.info('cancelSerialRight success, portId: ', portId);
} catch (error) {
  console.error('cancelSerialRight error, ', JSON.stringify(error));
}

SerialAttribute

Represents the configuration parameters of a serial port.

System capability: SystemCapability.USB.USBManager.Serial

SerialPort

Represents the parameters of a serial port.

System capability: SystemCapability.USB.USBManager.Serial

BaudRates

Enumerates the baud rates.

System capability: SystemCapability.USB.USBManager.Serial

DataBits

Enumerates the number of data bits.

System capability: SystemCapability.USB.USBManager.Serial

Parity

Enumerates the parity check modes.

System capability: SystemCapability.USB.USBManager.Serial

StopBits

Enumerates of the number of stop bits.

System capability: SystemCapability.USB.USBManager.Serial

你可能感兴趣的鸿蒙文章

harmony 鸿蒙Basic Services Kit

harmony 鸿蒙DeviceInfo

harmony 鸿蒙InitSync

harmony 鸿蒙OH_Print

harmony 鸿蒙OsAccount

harmony 鸿蒙Pasteboard

harmony 鸿蒙Print_Margin

harmony 鸿蒙Print_PageSize

harmony 鸿蒙Print_PrintAttributes

harmony 鸿蒙Print_PrintDocCallback