NB-IoT Device Pairing

Narrowband Internet of Things (NB-IoT) is a low-power wide-area network radio technology for cellular network devices. NB-IoT focuses on long battery life and high connection density. An NB-IoT device comes with a SIM card slot or eSIM embedded on board. In the pairing process, an NB-IoT device gets registered and activated with the cloud through a cellular network.

Pairing process

Parse QR code

Extract the URL from the QR code and get the device information through the common API. Based on the return value, determine whether the device is an NB-IoT device.

@protocol ThingSmartActivatorRequestProtocol <NSObject>

/// Provide QR code parsing capability
/// @param param Request Parameters
/// @param success Network success callback
/// @param failure Network Failure Callbacks
- (void)requestParseQRCodeWithParam:(ThingActivatorParseQRCodeRequestData *)param success:(void(^)(ThingSmartAScanCodeModel *result))success failure:(ThingActivatorCallbackError)failure;
@end

Parameter description

Description of the return value:

@interface ThingSmartAScanCodeModel : NSObject
@property (nonatomic, strong) NSString * _Nullable actionName;
@property (nonatomic, assign) id _Nullable actionData;
@end

The actionName for an NB-IoT device is "device_net_conn_bind_nb". See the example for usage.

Register the pairing type

When the device pairing service is initialized, register the pairing type, which is ThingSmartActivatorTypeNBModel.

/// Initialize network configuration types
/// @param typeList Network configuration types
- (void)registerWithActivatorList:(NSArray<ThingSmartActivatorTypeModel *>*)typeList;

Parameter description

Activate a device

API description

/// Activate devices with a single network configuration type
/// @param type Network configuration type
/// @param deviceList Devices to be activated
- (void)startActive:(ThingSmartActivatorTypeModel *)type deviceList:(NSArray<ThingSmartActivatorDeviceModel *>*)deviceList;

Parameter description

Stop activation

API description

/// Stop activating devices
/// @param typeList Array of network configuration types
/// @param clearCache Whether to clear the cache
- (void)stopActive:(NSArray <ThingSmartActivatorTypeModel *>*)typeList clearCache:(BOOL)clearCache;

Parameter description

Activation callback

API description

// Device network configuration result callback
/// @param service Device network configuration implementation object
/// @param type Network configuration type
/// @param devices Devices being configured
/// @param errorModel Error encountered during network configuration
- (void)activatorService:(id<ThingSmartActivatorActiveProtocol>)service
           activatorType:(ThingSmartActivatorTypeModel *)type
       didReceiveDevices:(nullable NSArray<ThingSmartActivatorDeviceModel *> *)devices
                   error:(nullable ThingSmartActivatorErrorModel *)errorModel;

Parameter description

Error codes

ThingSmartActivatorErrorModel is returned if pairing fails or times out.

@interface ThingSmartActivatorErrorModel : NSObject
@property (nonatomic, strong) ThingSmartActivatorDeviceModel *deviceModel;
@property (nonatomic) NSError *error;
@end

ThingSmartActivatorDiscoveryError includes the definition of error codes.

Example

Swift:

class NBmodeConfigurationVC: UITableViewController {

    private var token: String = ""
    private var typeModel:ThingSmartActivatorTypeNBModel = {
        let type = ThingSmartActivatorTypeNBModel()
        type.type = ThingSmartActivatorType.NB
        type.typeName = NSStringFromThingSmartActivatorType(ThingSmartActivatorType.NB)
        type.timeout = 120
        type.spaceId = Home.current!.homeId
        return type
    }()


    lazy var discovery: ThingSmartActivatorDiscovery = {
        let discovery = ThingSmartActivatorDiscovery()
        discovery.register(withActivatorList: [self.typeModel])
        discovery.setupDelegate(self)
        discovery.loadConfig()
        return discovery
    }()

    var request: ThingSmartActivatorDiscoveryRequest = {
        let request = ThingSmartActivatorDiscoveryRequest()
        return request
    }()

    private func startConfiguration(qrcode codeStr: String?) -> Void{
        SVProgressHUD.show()
        let requestDate = ThingActivatorParseQRCodeRequestData()
        requestDate.code = codeStr ?? ""
        request.requestParseQRCode(withParam: requestDate) {codeModel in
            if codeModel.actionName == "device_net_conn_bind_nb" {
                self.typeModel.nbId = codeModel.actionData?.object(forKey: "id") as! String
                self.discovery.startActive(self.typeModel, deviceList: [])
            }
        } failure: { error in

        }
    }
}

extension NBmodeConfigurationVC: ThingSmartActivatorActiveDelegate {
    func activatorService(_ service: ThingSmartActivatorActiveProtocol, activatorType type: ThingSmartActivatorTypeModel, didReceiveDevices devices: [ThingSmartActivatorDeviceModel]?, error errorModel: ThingSmartActivatorErrorModel?) {
        if errorModel != nil {
            SVProgressHUD.showError(withStatus: "Bind Failure. (\(errorModel?.error.localizedDescription ?? ""))")
            return
        }

        let device = devices?.first
        SVProgressHUD.show(withStatus: "Bind Success. \n devId: \(device?.uniqueID ?? "") \n name: \(device?.name ?? "")")
    }
}

Objective-C:

- (void)qrParse:(NSString *)url {
    ThingActivatorParseQRCodeRequestData *param = [[ThingActivatorParseQRCodeRequestData alloc] init];
    param.code = url;

   [self.requestService requestParseQRCodeWithParam:param success:^(ThingSmartAScanCodeModel * _Nonnull model) {
        if ([model.actionName isEqualToString:@"device_net_conn_bind_nb"]) {
            ThingSmartActivatorTypeNBModel *type = [[ThingSmartActivatorTypeNBModel alloc] init];
            type.type = ThingSmartActivatorTypeNB;
            type.typeName = NSStringFromThingSmartActivatorType(ThingSmartActivatorTypeNB);
            type.timeout = 120;
            type.spaceId = [ThingSmartActivatorLinkTool getSpaceId];
            type.nbId = [codeModel.actionData objectForKey:@"id"];;
            [self startConfigQRCode:type];
        }
    } failure:^(NSError * _Nonnull error) {

    }];
}

- (void)startConfigQRCode:(ThingSmartActivatorTypeNBModel *)type {

  [self.discovery registerWithActivatorList:@[type]];
  [self.discovery setupDelegate:self];
  [self.discovery startActive:type deviceList:@[]];

}

- (void)activatorService:(id<ThingSmartActivatorActiveProtocol>)service 
           activatorType:(ThingSmartActivatorTypeModel *)type 
       didReceiveDevices:(NSArray<ThingSmartActivatorDeviceModel *> *)devices 
                   error:(ThingSmartActivatorErrorModel *)errorModel {    
    if (errorModel) {
        [self _connectWifiError:errorModel];
        return;
    }

    if (device) {
        [self _handleDevice:device];
    }
}

- (void)_handleDevice:(ThingSmartActivatorDeviceModel *)deviceModel {
    /// handle success device
}

- (ThingSmartActivatorDiscovery *)discovery {
    if (!_discovery) {
        _discovery = [[ThingSmartActivatorDiscovery alloc] init];
    }
    return _discovery;
}

- (ThingSmartActivatorDiscoveryRequest *)requestService {
    if (!_requestService) {
        _requestService = [[ThingSmartActivatorDiscoveryRequest alloc] init];
    }
    return _requestService;
}