Quick Start

This page shows the minimum flow for integrating sdk, sdk_bluetooth, sdk_lan, and sdk_mqtt together.

Requirements

Refer to each OHPM package page for supported HarmonyOS versions and API levels.
Phone, Tablet, and 2in1 devices are supported.
Bluetooth and location permissions are required before BLE scanning.
For LAN, the phone and device must be on the same Wi-Fi network with broadcast traffic allowed.
MQTT requires network access and an authenticated Gizwits user.

Install all dependencies

ohpm install @gizwits/smart-sdk
ohpm install @gizwits/smart-sdk-bluetooth
ohpm install @gizwits/smart-sdk-lan
ohpm install @gizwits/smart-sdk-mqtt

You can also declare them in the application module's oh-package.json5. Check OHPM and replace the placeholders with current compatible versions:

{
  'dependencies': {
    '@gizwits/smart-sdk': 'x.x.x',
    '@gizwits/smart-sdk-bluetooth': 'x.x.x-bluetooth',
    '@gizwits/smart-sdk-lan': 'x.x.x-lan',
    '@gizwits/smart-sdk-mqtt': 'x.x.x-mqtt',
  },
}

Permissions

Declare the permissions required by all four modules in src/main/module.json5:

{
  'module': {
    'requestPermissions': [
      { 'name': 'ohos.permission.INTERNET' },
      { 'name': 'ohos.permission.GET_NETWORK_INFO' },
      { 'name': 'ohos.permission.GET_WIFI_INFO' },
      {
        'name': 'ohos.permission.ACCESS_BLUETOOTH',
        'reason': '$string:permission_bluetooth_reason',
        'usedScene': { 'abilities': ['EntryAbility'], 'when': 'inuse' },
      },
      {
        'name': 'ohos.permission.APPROXIMATELY_LOCATION',
        'reason': '$string:permission_location_reason',
        'usedScene': { 'abilities': ['EntryAbility'], 'when': 'inuse' },
      },
    ],
  },
}

Request user-granted permissions with the native HarmonyOS API before BLE scanning:

import { abilityAccessCtrl, common, PermissionRequestResult, Permissions } from '@kit.AbilityKit';
 
async function requestBluetoothPermissions(context: common.UIAbilityContext): Promise<boolean> {
  const permissions: Array<Permissions> = [
    'ohos.permission.ACCESS_BLUETOOTH',
    'ohos.permission.APPROXIMATELY_LOCATION',
  ];
  const result: PermissionRequestResult = await abilityAccessCtrl
    .createAtManager()
    .requestPermissionsFromUser(context, permissions);
 
  return result.authResults.length === permissions.length &&
    result.authResults.every((status: number): boolean =>
      status === abilityAccessCtrl.GrantStatus.PERMISSION_GRANTED);
}

Initialize all modules

import { GizConfiguration, GizProductInfo, GizSDKManager, GizServerInfo } from '@gizwits/smart-sdk';
import { GizBluetoothManager } from '@gizwits/smart-sdk-bluetooth';
import { GizLanManager } from '@gizwits/smart-sdk-lan';
import { GizMqttManager } from '@gizwits/smart-sdk-mqtt';
 
const configuration = new GizConfiguration(
  'your-app-id',
  'your-app-secret',
  [new GizProductInfo('your-product-key', 'your-product-secret')],
  new GizServerInfo('api.gizwits.com')
);
 
GizSDKManager.initialize(configuration);
GizBluetoothManager.initialize();
GizLanManager.initialize();
GizMqttManager.initialize();

⚠️

AppSecret, ProductSecret, user tokens, and Wi-Fi passwords are sensitive. Never write them to logs or a public repository.

Log in and discover devices

import { GizDevice, GizSDKManager } from '@gizwits/smart-sdk';
 
const userManager = GizSDKManager.getUserManager();
await userManager.loginByAnonymous();
 
const unsubscribeBle = GizBluetoothManager.subscribeBluetoothDeviceList().subscribe(
  (devices: Array<GizDevice>): void => {
    // Copy the list into ArkUI state.
  }
);
GizBluetoothManager.startBleScan();
 
const unsubscribeLan = GizLanManager.subscribeLanDeviceList().subscribe(
  (devices: Array<GizDevice>): void => {
    // Copy the list into ArkUI state.
  }
);
await GizLanManager.startDiscovery();

MQTT observes login state and the bound-device list, then establishes cloud connections automatically. Stop discovery and unsubscribe when the page disappears:

GizBluetoothManager.stopBleScan();
await GizLanManager.stopDiscovery();
unsubscribeBle();
unsubscribeLan();

Continue

Expand the relevant SDK capability in the sidebar for API parameters, return values, and ArkTS examples.
Use the API List to find interfaces by module.

Basic Concepts Initialization