Basic Concepts
The Gizwits HarmonyOS Native SDK is designed for ArkTS applications. It consists of one core module and three transport modules. This documentation covers the native SDK only, not application-specific UI or business logic.
Install all four modules together. Check OHPM for the latest compatible releases and do not mix incompatible module versions.
Modules
| Native module | OHPM package | Responsibility |
|---|---|---|
sdk | @gizwits/smart-sdk (opens in a new tab) | Initialization, configuration, users, devices, data points, logs, and OpenAPI |
sdk_bluetooth | @gizwits/smart-sdk-bluetooth (opens in a new tab) | BLE discovery, connection, authentication, provisioning, data points, and OTA |
sdk_lan | @gizwits/smart-sdk-lan (opens in a new tab) | LAN discovery, connection, provisioning, and data points |
sdk_mqtt | @gizwits/smart-sdk-mqtt (opens in a new tab) | Cloud connection, bound-device synchronization, and data points |
The three transport modules depend on sdk. Initialize GizSDKManager first, followed by GizBluetoothManager, GizLanManager, and GizMqttManager.
Unified device object
GizDevice represents a device across all transports. Every device exposes these capabilities:
| Capability | Module | Purpose |
|---|---|---|
device.bleCapability | sdk_bluetooth | BLE connection, provisioning, data points, and OTA |
device.lanCapability | sdk_lan | LAN connection, provisioning, and data points |
device.mqttCapability | sdk_mqtt | MQTT cloud connection and data points |
device.sendDataPoints() selects the first controllable transport in BLE, LAN, MQTT order. Call a specific capability when the business flow must use a fixed transport.
Capability status
GizCapacityStatus describes a transport capability:
| Status | Meaning |
|---|---|
OFFLINE | The transport is unavailable or the device is offline |
ONLINE | The device is discovered or connected but cannot yet accept commands |
ONLINE_CONTROLLABLE | Authentication or login is complete and data points can be read or written |
Observe status with capability.subscribeStatus().subscribe() and wait for ONLINE_CONTROLLABLE before controlling the device.
State and cleanup
The SDK exposes observable state through GizState<T>. subscribe() immediately emits the current value by default and returns an unsubscribe function:
const unsubscribe = device.bleCapability.subscribeStatus().subscribe((status): void => {
// Map status to ArkUI state.
});
// Call when the ArkUI component disappears or the Ability is destroyed.
unsubscribe();Release page-level scans, discovery, connections, and subscriptions with the page lifecycle. Shut down the transport modules and core module only when the application no longer needs the SDK.
Next steps
- Quick Start covers installation, permissions, initialization, and a minimal flow.
- Browse actual SDK capabilities such as accounts, discovery, provisioning, device management, communication, and OTA from the sidebar.
- Use the API List to find APIs by native module.