iOS SDK Guide (v3.6.0)

1. Introduction

1.1. Network Configuration Process

Before starting the network configuration, it is necessary to obtain the current status of the device and determine the next steps accordingly. The device status can be broadly classified into four categories:

Idle state status = 0: The device is in its initial idle state, and network configuration can begin directly.
Undergoing configuration status in 1..8: The device has entered the configuration process. Wait for completion. The interface can display progress based on real-time status updates.
Configuration complete status = 9: Network setup is complete. Users can now retrieve signal strength, tilt angle, and roll angle to finalize installation.
Upgrade in progress status = 11: The device is upgrading. Wait for completion before proceeding.

Once configuration is complete, send the "Configuration Finish" command to enter operational mode.

1.2. Network Configuration Flowchart

Flowchart

2. SDK Configuration

2.1. Download SDK

Download the SDK package and import:

PontosenseProvision.xcframework

2.2. Configure Permissions

Category	Permission	Description
Bluetooth	Privacy - Bluetooth Always Usage	Allows Bluetooth scanning and data transfer
Camera	Privacy - Camera Usage	Access to camera for QR code scanning
Photo Library	Privacy - Photo Library Usage	Selection and saving of images

<key>NSBluetoothAlwaysUsageDescription</key>
<string></string>
<key>NSPhotoLibraryUsageDescription</key>
<string></string>
<key>NSCameraUsageDescription</key>
<string></string>

3. Network Configuration Steps

3.1. Initialization

/// Init PSProvisionManager class
/// 
/// - Parameters:
///   - enableLog: Enable Logging
///   - bleStateDelegate: Bluetooth status monitoring
public init(enableLog: Bool = false, bleStateDelegate: (PontosenseProvision.PSBleStateDelegate)? = nil)

3.2. Scan Device List

3.2.1. Scan the QR code to get the device name

/// Scan QR code
///
/// - Parameters:
///   - scanView: The view where the scan will be displayed.
///   - completionHandler: A closure that gets called after the scan is completed. It returns the scanned string (if any) and an error (if any).
public func scanQRCode(scanView: UIView, completionHandler: @escaping (String?, PSDeviceCSSError?) -> Void)

3.2.2. Search devices by prefix

/// Searches for PS devices with the specified prefix
///
/// This method scans for devices matching the given prefix for a specified duration, and calls the completion handler with the results or an error if the operation fails.
///
/// - Parameters:
///   - devicePrefix: The prefix to filter devices during the scan.
///   - scanTimeOut: The maximum duration (in seconds) to scan for devices. Default is 5.0 seconds.
///   - completionHandler: A closure that is called when the scan is complete.
///     It returns an optional array of `PSDevice` representing the found devices, and an optional `PSDeviceCSSError` indicating any issues that may have occurred.
public func searchPSDevices(devicePrefix: String, scanTimeOut: CGFloat = 5.0, completionHandler: @escaping (PSDevice]?, PSDeviceCSSError?) -> Void)

3.3. Connect to Device

/// Connects to the specified device
///
/// This method initiates a connection to the given device and calls the completion handler with the connection status once the operation is complete.
///
/// - Parameter device: The `PSDevice` instance representing the device to connect to.
/// - Parameter completionHandler: A closure that is called when the connection attempt is complete.
///   It returns a `PSSessionStatus` indicating the result of the connection attempt.
public func connectDevice(device: PSDevice, completionHandler: @escaping (PSSessionStatus) -> Void)

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

/// Retrieves the sensor state from the connected device
///
/// This method requests the current sensor status from the device and calls the completion handler, with the retrieved status or an error if the operation fails.
///
/// - Parameter completionHandler: A closure that is called when the sensor state retrieval is complete.
///   It returns an optional `PSSensorStatusModel` containing the network status information.  If the device status = `deviceUpgrading` , the `PSSensorStatusModel` information will contain information about the upgrade progress. And an optional `PSSessionError` indicating any issues that may have occurred.
public func getSensorStateFromDevice(completionHandler: @escaping (PSSensorStatusModel?, PSSessionError?) -> Void)

3.5. Scan Wi-Fi List

/// Retrieves the list of available Wi-Fi networks from the connected device
///
/// This method requests the current list of available Wi-Fi networks from the device and calls the completion handler with either the retrieved list or an error if the operation fails.
///
/// - Parameter completionHandler: A closure that is called when the Wi-Fi list retrieval is complete.
///   It returns an optional array of `PSWifiNetwork` containing the available networks, and an optional `PSSessionError` indicating any issues that may have occurred.
public func getWifiListFromDevice(completionHandler: @escaping ([PSWifiNetwork]?, PSSessionError?) -> Void)

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).

/// Sends Wi-Fi configuration settings to the connected device
///
/// This method transmits the specified Wi-Fi credentials and AWS configuration to the device.
/// It calls the completion handler when the operation is complete, indicating success or failure.
///
/// - Parameters:
///   - ssid: The SSID of the Wi-Fi network.
///   - password: The password for the Wi-Fi network.
///   - orgId: The organization ID associated with the device.
///   - awsPrivateKey: The AWS private key for secure communication.
///   - awsPublicKey: The AWS public key for secure communication.
///   - awsCertificate: The AWS certificate for secure communication.
///   - awsUrl: The URL for the AWS endpoint.
///   - target: The target parameter currently only accepts a value of "0" or can be omitted.
///   - completionHandler: A closure that is called when the configuration transmission is complete.
///     It returns an optional boolean indicating success (`true` if successful), and an optional `PSSessionError` indicating any issues that may have occurred.
public func sendWifiConfigToDevice(ssid: String, password: String, orgId: String, awsPrivateKey: String, awsPublicKey: String, awsCertificate: String, awsUrl: String, target: Int? = nil, completionHandler: @escaping (Bool?, PSSessionError?) -> Void)

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.

/// Retrieves sensor information from the connected device
///
/// This method requests the sensor data from the device and calls the completion handler, with the retrieved information or an error if the operation fails.
///
/// - Parameter completionHandler: A closure that is called when the data retrieval is complete.
///   It returns an optional `PSDeviceInfo` containing the sensor information, and an optional `PSSessionError`, indicating any issues that may have occurred.
public func getSensorInfoFromDevice(completionHandler: @escaping (PSDeviceInfo?, PSSessionError?) -> Void)

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.

/// Send the firmware upgrade configuration to the device for upgrade
///
/// - Parameters:
///   - version: The firmware version of sensor.
///   - model: The model type of sensor.
///   - url: Download address for firmware upgrade.
///   - completionHandler: A closure that is called when the configuration transmission is complete.
///     It returns an optional boolean indicating success (`true` if successful), and an optional `PSSessionError` indicating any issues that may have occurred.
public func sendFirmwareInfoToDevice(completionHandler: @escaping (Bool?, PSSessionError?) -> Swift.Void)

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.

/// Retrieves device upgrade results from the connected device
///
/// - Parameter completionHandler: A closure that is called when the device upgrade results retrieval is complete.
///   It returns an optional object of `PSSensorUpgradeModel` containing the upgrade results, and an optional `PSSessionError` indicating any issues that may have occurred.
public func getSensorUpgradeStatusFromDevice(completionHandler: @escaping (PSSensorUpgradeModel?, PSSessionError?) -> Swift.Void)

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.

/// Sends a stop upgrade message to the connected device
///
/// After the device receives the message, if it is downloading the upgraded firmware, it will stop upgrading.
/// Once the operation is complete, the completion handler is called.
/// If an error occurs during transmission, it is passed to the handler.
///
/// - Parameter completionHandler: A closure that is called when the transmission is complete.
///   It returns an optional `PSSessionError` indicating any issues that may have occurred.
public func sendStopSensorOtaToDevice(completionHandler: @escaping (PSSessionError?) -> Void)

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.

/// Sends complete information to the connected device
///
/// This method transmits all necessary data to the device and calls the completion handler.
/// Once the operation is complete, the completion handler is called.
/// If an error occurs during transmission, it is passed to the handler.
///
/// - Parameter completionHandler: A closure that is called when the transmission is complete.
///   It returns an optional `PSSessionError` indicating any issues that may have occurred.
public func sendCompleteInfoToDevice(completionHandler: @escaping (PSSessionError?) -> Void)