Android SDK Guide (v3.6.0)
1. Introduction
1.1. Network Configuration Process
Before beginning network configuration, determine the current device status to decide on next steps. The device status falls into one of the following categories:
- Idle
status = 0: Device is ready for configuration. - Configuring
status in 1..8: Device is mid-configuration. Wait for completion. - Configured
status = 9: Network setup is complete. Installation details such as signal strength and orientation can now be retrieved. - Upgrading
status = 11: Wait for the upgrade to finish before proceeding or choose to skip it.
After configuration, send the "Configuration Finish" command to finalize setup.
1.2. Network Configuration Flowchart
2. SDK Configuration
2.1. Download SDK
Download the SDK package or source code and import it into the app project.
2.2. Configure Permissions
| Category | Permission | Description |
|---|---|---|
| Bluetooth | BLUETOOTH_SCAN | Scan for Bluetooth devices (API 31+) |
| BLUETOOTH_CONNECT | Connect to Bluetooth devices (API 31+) | |
| BLUETOOTH / BLUETOOTH_ADMIN | Legacy permissions for API < 31 | |
| Location | ACCESS_FINE_LOCATION / ACCESS_COARSE_LOCATION | Location access required for scanning |
<uses-permission android:name="android.permission.BLUETOOTH_SCAN" tools:targetApi="s" android:usesPermissionFlags="neverForLocation" />
<uses-permission android:name="android.permission.BLUETOOTH_CONNECT" />
<uses-permission android:name="android.permission.BLUETOOTH_ADMIN" android:maxSdkVersion="30" />
<uses-permission android:name="android.permission.BLUETOOTH" android:maxSdkVersion="30" />
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
3. Network Configuration Steps
3.1. Initialization
fun init(application: Application, enableLog: Boolean = false, bluetoothStateChangeListener: BluetoothStateChangeListener? = null)
3.2. Scan Device List
fun scanPSDevices(context: AppCompatActivity, prefix: String? = "", duration: Long = 5000L, exactMatch: Boolean? = true, scanCallback: BleScanCallback)
abstract class BleScanCallback {
abstract fun onScanStart()
abstract fun onDeviceFound(device: BleDevice)
abstract fun onScanFinished(results: MutableList<BleDevice>)
abstract fun onFailure(exception: Exception)
}
3.3. Connect to Device
fun connectDevice(lifecycleOwner: LifecycleOwner, device: BleDevice?, duration: Long = 5000, connectCallback: ConnectStateCallback)
enum class ConnectState {
ON_CONNECT_START,
ON_CONNECT_SUCCESS,
ON_CONNECT_FAIL,
ON_DISCONNECTED,
}
3.4. Get Device Status Code
3.4.1. Device Status Code
| Status Code | Description |
|---|---|
| 0 | Idle state, waiting for network configuration |
| 1 | Connecting to Wi-Fi |
| 2 | Wi-Fi connection failed |
| 3 | Connecting to the internet |
| 4 | Internet connection failed |
| 5 | Connecting to the server |
| 6 | Server connection failed |
| 7 | Getting configuration information |
| 8 | Failed to get configuration information |
| 9 | Device network configuration successful |
| 10 | Device working status (retained by the device) |
| 11 | Device is upgrading |
| Upgrade State (phase) | Description |
|---|---|
| 0 | Downloading |
| 1 | Installing Radar |
| 2 | Installing Wi-Fi |
3.4.2. Get Device Status Code
fun getSensorStateFromDevice(owner: LifecycleOwner, device: BleDevice?, stateCallback: SensorStateCallback)
State
{
"status": 0, // Status Code
"error": null, // Error
"upgrade_status":{
"phase":0,
"totalBytes":0,
"currentBytes":0
}
}
3.5. Scan Wi-Fi List
fun getWifiListFromDevice(owner: LifecycleOwner, device: BleDevice?, wifiListCallback: WiFiListCallback)
WiFiParams
{
"softapList": [
[
"ssid", // Wi-Fi Name
"bssid", // Identifier
"rssi", // Signal Strength
"auth" // Authentication Method
]
]
}
3.6. Send Configuration Info
After sending the configuration information, return the device's real-time network configuration status code (see Status Codes in Table 3.4.1).
fun sendWiFiConfigToDevice(owner: LifecycleOwner, device: BleDevice?, orgId: String, certPem: String, publicKey: String, privateKey: String, host: String, wifiName: String, password: String, target: Int?, stateCallback: SensorStateCallback)
State
{
"status": 0, // Status Code
"error": {
"code": 0, // Common Error Codes
"error_code": "", // Other Error Codes
"message": "error msg"
}
}
3.7. Get Device Installation Info
Get the device's network signal strength, network availability status, tilt angle and effective range, roll angle and effective range.
fun getSensorInfoFromDevice(owner: LifecycleOwner, device: BleDevice?, infoCallback: SensorInfoCallback)
SensorParams
{
"rssi": -55, // Network Signal Strength
"rssi_status": 0, // Signal Strength Availability
"pitch": 10.5, // Tilt Angle
"pitch_max": 2.0, // Maximum Effective Tilt Angle
"pitch_min": -2.0, // Minimum Effective Tilt Angle
"roll": 20.5, // Roll Angle
"roll_max": 2.0, // Maximum Effective Roll Angle
"roll_min": -2.0 // Minimum Effective Roll Angle
}
3.8. Device Upgrade
After the device network configuration is successfully completed, you can choose to upgrade the device to the latest version. During the upgrade process, the device status will change to 11. Once the upgrade is complete, the device will automatically restart and re-enter the network configuration process. At this point, you will need to reconnect Bluetooth in order to continue with the subsequent configuration steps.
fun sendUpgradeInfoToDevice(owner: LifecycleOwner, device: BleDevice?, model: String?, version: String?, url: String?, stateCallback: SensorStateCallback)
State
{
"status": 0, // Status Code
"error": {
"code": 0, // Common Error Codes
"error_code": "", // Other Error Codes
"message": "error msg"
}
}
3.9. Get Device Upgrade Status
During the device configuration phase or after the upgrade is completed and Bluetooth is reconnected, you can retrieve the most recent upgrade status information of the device, such as whether the upgrade was successful, the current device version, the target version in case of an upgrade failure, and any related error codes.
fun getUpgradeStateFromDevice(lifecycleOwner: LifecycleOwner,device: BleDevice?, updateInfoCallback: UpdateInfoCallback)
SensorUpdateInfoParams
{
"isUpgradeFailed": false,
"currentFirmware": "v1.0.0",
"failedUpgradeVersion": "v1.0.1",
"errorCode": 101
}
3.10. Stop OTA
Call this method to interrupt or stop the upgrade process when the device is currently undergoing a firmware or software update.
3.11. Configuration Complete
After the network configuration is complete, the device will actively disconnect the Bluetooth connection. When the network is available and both the tilt angle and roll angle are within the effective range, the device will automatically enter normal working mode.
fun sendCompleteInfoToDevice(owner: LifecycleOwner, device: BleDevice?, configFinishCallback: ConfigFinishCallback)