Automatic Unlocking

Bluetooth is widely used for IoT-enabled vehicles, such as electric bicycles and automotive cars. For example, smart vehicles can be automatically unlocked over Bluetooth as users approach them. Travel SDK supports this efficient unlocking feature.

In the traditional unlocking process, users need to keep the vehicle connected to the app, open the panel, and then manually tap to unlock the device.

Bluetooth automatic unlocking simplifies the whole process. Users only need to enable this feature when they access it for the first time on the app. Then, whenever they take the mobile phone that runs the app and approach the target vehicle, the app automatically unlocks or disarms the vehicle.

Types of automatic unlocking methods

• Travel SDK supports two types of automatic unlocking methods: Bluetooth LE_HID and Bluetooth.
• They are intended for different types of vehicles. You can make an API request to query the type of automatic unlocking method supported by the target device to get the automatic unlocking control class.

Bluetooth LE_HID

Bluetooth LE_HID automatic unlocking is implemented based on the Bluetooth Low Energy (LE) human interface device (HID) protocol.

Bluetooth

Bluetooth automatic unlocking is implemented based on pairing over Bluetooth Classic.

Automatic unlocking management class

Get automatic unlocking management class

Example

ThingSmartODInductiveUnlock *manager = [ThingSmartODInductiveUnlock sharedInstance];

Get type of automatic unlocking method

API description

/**
 * @brief Get the {@link InductiveUnlockType} of device
 *
 * @param devId device ID
 * @param completionBlock inductiveUnlockType
 * @param errorBlock error message
 */
- (void)getInductiveUnlockType:(NSString *)devId
                    completion:(void(^)(InductiveUnlockType type))completionBlock
                         error:(void(^)(NSError* error))errorBlock;

Data model of InductiveUnlockType

Enum value	Description
InductiveUnlockTypeNone	Automatic unlocking not supported
InductiveUnlockTypeBLEHID	Bluetooth LE_HID automatic unlocking
InductiveUnlockTypeBT	Bluetooth automatic unlocking

Example

[[ThingSmartODInductiveUnlock sharedInstance] getInductiveUnlockType:devId completion:^(InductiveUnlockType type) {
    NSLog(@"result: %ld", type);
} error:^(NSError * _Nonnull error) {
    NSLog(@"error: %@", error.localizedDescription);
}];

Listen for changes in automatic unlocking switch status

API description

typedef NS_ENUM(NSInteger, UnlockStatus) {
    UnlockStatusTurnOn = 0,
    UnlockStatusTurnOff = 1,
};

@protocol ThingSmartODInductiveUnlockDelegate <NSObject>

- (void)listenUnlockStatusCallback:(UnlockStatus)status;

@end

Example

// set up proxy
[ThingSmartODInductiveUnlock sharedInstance].delegate = self;

// implementing the protocol
#pragma mark - ThingSmartODInductiveUnlockDelegate

- (void)listenUnlockStatusCallback:(UnlockStatus)status {
      NSLog(@"status: %ld", status);
}

Control class of Bluetooth LE_HID automatic unlocking

Get control class of Bluetooth LE_HID automatic unlocking

Example

ThingODHidInductiveUnlock *hidManager = [ThingODHidInductiveUnlock sharedInstance];

Determine support for HID capabilities

Checks whether the target device supports Bluetooth LE HID capabilities. During the process of removing and resetting the HID device that is paired over Bluetooth, the device must stay online on a local area network (LAN).

API description

/**
 * @brief Get the {@link hid bind ability} of device
 *
 * @param devId device ID
 */
- (BOOL)supportHIDAbility:(NSString *)devId;

Example

BOOL hidDevice = [[ThingODHidInductiveUnlock sharedInstance] supportHIDAbility:devId];

Get automatic unlocking switch status

API description

/**
 * @brief Get the {@link unlock status} of device
 *
 * @param devId device ID
 */
- (BOOL)getUnlockStatus:(NSString *)devId;

Example

BOOL unlockStatus = [[ThingODHidInductiveUnlock sharedInstance] getUnlockStatus:devId];

Get HID binding status

API description

/**
 * @brief Get the {@link hid bind status} of device
 *
 * @param devId device ID
 */
- (BOOL)getHidBindStatus:(NSString *)devId;

Example

BOOL bindStatus = [[ThingODHidInductiveUnlock sharedInstance] getHidBindStatus:devId];

Enable automatic unlocking

The automatic unlocking feature is enabled prior to the process of Bluetooth pairing with a mobile phone. Travel SDK provides the listener delegate method that handles the process of enabling this feature and Bluetooth pairing. After the success callback for enabled automatic unlocking is invoked, Bluetooth pairing is started. The delegate method will then invoke the callback for the HID binding status.

If users cancel pairing, the automatic unlocking status is disabled.

API description

/**
 * @brief Turn on the inductive unlock
 *
 * @param devId device ID
 * @param finishedBlock unlock result
 * @param errorBlock error message
 */
- (void)turnOnHidInductiveUnlock:(NSString *)devId
                        finished:(void(^_Nullable)(void))finishedBlock
                           error:(void(^)(NSError* error))errorBlock;

Delegate

typedef NS_ENUM(NSInteger, HidBindStatus) {
    HidBindStatusBind = 0,
    HidBindStatusUnbind = 1
};

@protocol ThingODHidInductiveUnlockDelegate <NSObject>

- (void)listenHidBindStatusCallback:(HidBindStatus)status;

@end

Example

// set up proxy
[ThingODHidInductiveUnlock sharedInstance].delegate = self;

// The method of turning on the HID inductive unlock
[[ThingODHidInductiveUnlock sharedInstance] turnOnHidInductiveUnlock:devId finished:^{
    NSLog(@"Enter the hid unlocking process");
} error:^(NSError * _Nonnull error) {
    NSLog(@"error: %@", error.localizedDescription);
}];

// implementing the protocol
#pragma mark - ThingODHidInductiveUnlockDelegate

- (void)listenHidBindStatusCallback:(HidBindStatus)status {
    NSLog(@"status: %ld", status);
}

Disable automatic unlocking

API description

/**
 * @brief Turn off the inductive unlock
 *
 * @param devId device ID
 * @param finishedBlock unlock result
 * @param errorBlock error message
 */
- (void)turnOffHidInductiveUnlock:(NSString *)devId
                         finished:(void(^_Nullable)(void))finishedBlock
                            error:(void(^)(NSError* error))errorBlock;

Example

[[ThingODHidInductiveUnlock sharedInstance] turnOffHidInductiveUnlock:devId finished:^{
    NSLog(@"Turn off successfully");
} error:^(NSError * _Nonnull error) {
    NSLog(@"error: %@", error.localizedDescription);
}];

Set arming distance

API description

/**
 * @brief Record arming distance
 *
 * @param devId device ID
 * @param finishedBlock record result
 * @param errorBlock error message
 */
- (void)recordFortifyDistance:(NSString *)devId
                     finished:(void(^_Nullable)(void))finishedBlock
                        error:(void(^)(NSError* error))errorBlock;

Example

[[ThingODHidInductiveUnlock sharedInstance] recordFortifyDistance:devId finished:^{
    NSLog(@"Record successfully");
} error:^(NSError * _Nonnull error) {
    NSLog(@"Error: %@", error.localizedDescription);
}];

Set disarming distance

API description

/**
 * @brief Record Disarm Distance
 *
 * @param devId device ID
 * @param finishedBlock record result
 * @param errorBlock error message
 */
- (void)recordDisarmDistance:(NSString *)devId
                    finished:(void(^_Nullable)(void))finishedBlock
                       error:(void(^)(NSError* error))errorBlock;

Example

[[ThingODHidInductiveUnlock sharedInstance] recordDisarmDistance:devId finished:^{
    NSLog(@"Record successfully");
} error:^(NSError * _Nonnull error) {
    NSLog(@"error: %@", error.localizedDescription);
}];

Control class of BT automatic unlocking

Get control class of Bluetooth automatic unlocking

Example

ThingODBTInductiveUnlock *btManager = [ThingODBTInductiveUnlock sharedInstance];

Get automatic unlocking switch status

API description

/**
 * @brief Get the {@link paired status} of device
 *
 * @param devId device ID
 */
- (BOOL)checkPairedStatus:(NSString *)devId;

Example

[[ThingODBTInductiveUnlock sharedInstance] checkPairedStatus:device.devId];

Enable automatic unlocking

The automatic unlocking features is enabled along with the process of Bluetooth pairing with a mobile phone. Travel SDK provides the listener delegate method that handles the process of enabling this feature and Bluetooth pairing. After the success callback for enabled automatic unlocking is invoked, you must guide users to access Settings > Bluetooth on the mobile phone and start Bluetooth pairing. The delegate method will then invoke the callback for the HID binding status.

If users cancel pairing, the automatic unlocking status is disabled.

API description

/**
 * @brief Turn on the inductive unlock
 *
 * @param devId device ID
 * @param finishedBlock unlock result
 * @param errorBlock error message
 */
- (void)turnOnBTInductiveUnlock:(NSString *)devId
                       finished:(void(^_Nullable)(void))finishedBlock
                          error:(void(^)(NSError* error))errorBlock;

Example

[[ThingODBTInductiveUnlock sharedInstance] turnOnBTInductiveUnlock:devId finished:^{
    NSLog(@"Enter the hid unlocking process");
} error:^(NSError *error) {
    NSLog(@"error: %@", error.localizedDescription);
}];

Disable automatic unlocking

API description

/**
 * @brief Turn off the inductive unlocking
 *
 * @param devId device ID
 * @param finishedBlock unlock result
 * @param errorBlock error message
 */
- (void)turnOffBTInductiveUnlock:(NSString *)devId
                        finished:(void(^_Nullable)(void))finishedBlock
                           error:(void(^)(NSError* error))errorBlock;

Example

[[ThingODBTInductiveUnlock sharedInstance] turnOffBTInductiveUnlock:devId finished:^{
    NSLog(@"Turn off successfully");
} error:^(NSError * _Nonnull error) {
    NSLog(@"error: %@", error.localizedDescription);
}];

Get unlocking distance

API description

/**
 * @brief get the {@link unlock distance} of device
 *
 * @param devId device ID
 */
- (NSUInteger)getInductiveUnlockDistance:(NSString *)devId;

Return parameters

Type	Example	Description
Integer	1	The unlocking distance. The value can be 1, 2, 3, 4, and 5. A value of 0 indicates that automatic unlocking is not enabled.

Example

NSUInteger distance = [[ThingODBTInductiveUnlock sharedInstance] getInductiveUnlockDistance:devId];

Set unlocking distance

API description

/**
 * @brief Set the  {@link inductive unlock distance} of device
 *
 * @param devId device ID
 * @param distance  inductive unlock distance (range: 1 to 5)
 * @param finishedBlock unlock result
 * @param errorBlock error message
 */
- (void)setInductiveUnlockDistance:(NSString *)devId
                          distance:(long)distance
                          finished:(void(^_Nullable)(void))finishedBlock
                             error:(void(^)(NSError* error))errorBlock;

Example

[[ThingODBTInductiveUnlock sharedInstance] setInductiveUnlockDistance:devId distance:distance finished:^{
    NSLog(@"Set distance successfully");
} error:^(NSError * _Nonnull error) {
    NSLog(@"error: %@", error.localizedDescription);
}];

Device management

Get device control class

Example

ThingSmartDevice *device = [ThingSmartDevice deviceWithDeviceId:devId];

Remove a device

To remove a device that has automatic unlocking enabled, check the online status of the device. An offline device cannot be removed.

After the device is removed, you must guide users to access Settings > Bluetooth on the mobile phone and manually remove the Bluetooth connection.

API description

/// Removes the device and unbinds the device from the current user.
/// @param success Called when the task is finished.
/// @param failure Called when the task is interrupted by an error.
- (void)remove:(nullable ThingSuccessHandler)success failure:(nullable ThingFailureError)failure;

Example

// The offline device that supports Blueooth LE_HID and Bluetooth cannot be removed.
BOOL BTDeviceOffline = !device.isOnline && [[ThingODBTInductiveUnlock sharedInstance] checkPairedStatus:devId];
BOOL HIDDeviceOffline = !device.isOnline && [[ThingODHidInductiveUnlock sharedInstance] supportHIDAbility:devId];
if (BTDeviceOffline) {
    [Alert showBasicAlertOnVC:self withTitle:@"Attention" message:@"The device has turned on auto unlock function, and the device needs to be unbound when the device is online"];
    return;
} else if (HIDDeviceOffline) {
    [Alert showBasicAlertOnVC:self withTitle:@"Unbind Bluetooth device" message:@"The device is a HID device, please connect the device to unbind it."];
    return;
}
// After the device is removed, you must guide users to access Settings > Bluetooth on the mobile phone and manually remove the Bluetooth connection.
[device remove:^{
    [Alert showBasicAlertOnVC:[UIApplication sharedApplication].keyWindow.rootViewController withTitle:@"Attention" message:@"To ensure you won't receive notifications of the removed device, tap Go or go to Settings > Bluetooth to check if the device is removed from your phone."];
} failure:^(NSError *error) {
    NSLog(@"error: %@", error.localizedDescription);
}];

Restore factory defaults

To restore factory defaults for a device that has automatic unlocking enabled, check the online status of the device. Factory defaults cannot be restored for an offline device.

After factory defaults are restored for the device, the device data is cleared and the device gets ready for pairing again. Then, you must guide users to access Settings > Bluetooth on the mobile phone and manually remove the Bluetooth connection.

API description

/// Restores factory settings.
/// @param success Called when the task is finished.
/// @param failure Called when the task is interrupted by an error.
- (void)resetFactory:(nullable ThingSuccessHandler)success failure:(nullable ThingFailureError)failure;

Example

// Factory defaults cannot be restored for the offline device that supports Blueooth LE_HID and Blueooth.
BOOL BTDeviceOffline = !device.isOnline && [[ThingODBTInductiveUnlock sharedInstance] checkPairedStatus:devId];
BOOL HIDDeviceOffline = !device.isOnline && [[ThingODHidInductiveUnlock sharedInstance] supportHIDAbility:devId];
if (BTDeviceOffline) {
    [Alert showBasicAlertOnVC:self withTitle:@"Attention" message:@"The device has turned on auto unlock function, and the device needs to be unbound when the device is online"];
    return;
} else if (HIDDeviceOffline) {
    [Alert showBasicAlertOnVC:self withTitle:@"Unbind Bluetooth device" message:@"The device is a HID device, please connect the device to unbind it."];
    return;
}
// After factory defaults are restored for the device, you must guide users to access Settings > Bluetooth on the mobile phone and manually remove the Bluetooth connection.

[device resetFactory:^{
    [Alert showBasicAlertOnVC:[UIApplication sharedApplication].keyWindow.rootViewController withTitle:@"Attention" message:@"To ensure you won't receive notifications of the removed device, tap Go or go to Settings > Bluetooth to check if the device is removed from your phone."];
} failure:^(NSError *error) {
    NSLog(@"error: %@", error.localizedDescription);
}];