Add Device

QR Code

QR Code is the main way to add IPC devices.Its design idea is to enter the Wi-Fi distribution network information on the mobile phone, e.g.,Wi-Fi name,Wi-Fi password,then call the API interface to create a QR Code image,and the image would be shown on the App interface.Place your phone with the QR code on screen in front of the camera lens, Scan and read image information. When the device scan it successfully ,(you will hear a "Beep" or ''WiFi connecting'') ,The app needs to call the API to add a device Information Listener ,when the device initialization is completed, app will receive the information of this device.Please remove the listener,meanwhile,call the interface of your private cloud server,to bind the device information with the user information.You could check your device information by call the interface of your private cloud server in the future.

Products that apply QR Code to add devices

EX Series
Sentry Series
X1 Lite Series
XC Series
CC Series

Flowchart for QR Code adding devices

QR Code adding devices steps we could use the relevant API of BosmaAddDevice.h ,to complete the process of adding devices by scanning QR Code.

1. Create Object

Adding a device by QR Code is done by using class BosmaAddDevice.h ,we have to create subject by a single mode when using this class ,API method as follows:

/// Create object
+ (BosmaAddDevice *)sharedInstance;

/// Initializes the data for the add device
/// @param block Callback block, that you can get the result of initializing
-(void) initDeviceWithBlock:(InitDeviceBlock)block;

2. Create QR Code image

First, obtain the distribution network data entered by the user (WiFi name,WiFi password)，then, create QR code image by calling API, at last, the QR code image appears on the app, we could scan it with device. Specific API as follows：

/// Create a QR Code image, and the device can scan this image to complete the configuration of the device.
/// @param ssid The Wi-Fi's name
/// @param password The Wi-Fi's name password
/// @param familyId Bosma AM's family ID,Can be nil
/// @param target Operating environment of the device
/// @param block Callback block, here you can get the image of QRcode and the create result
-(void) createQRcodeWithSSID:(NSString *) ssid password:(NSString *) password familyId:(NSString *__nullable) familyId target:(ENUM_BOSMA_APP_TARGET) target qrcodeImageBlock:(CreateQRcodeImageBlock)block;

3. Receive device information

If device scanned the code successfully,APP will call API to add a listening device ,for device information receiving ,when the device initialization is completed,app will receive the device information, the app needs to stop listening.Specific API as follows:

/// Add device information listening, we can get device information here
/// @param block Callback method, where you can get the data and the result, the return result refer to ENUM_BOSMA_APP_ADDDEVICE_RESULT
-(void) addObserverForDeviceInfo:(AddDeviceInfoBlock)block;

/// Removing the listening for device information
-(void) removeObserverForDeviceInfo;

4. Bind device

When App received device information, App could call the API interface of user's cloud server,to complete the binding relationship between the device and user information .App could obtain the device data though Cloud server's API interface,and control the device in the future.

5. Unbind device

Unbinding the the relationship between the device and user,the App needs to call the API interface of developer's cloud server. Meanwhile, the SDK of API interface would be called for device data restoration. Specific API as follows:

/// Remove the device. After the server removes the device, this method is called to notify the device to clear the user data.
/// @param devicePid The product identity of the device
/// @param block Callback block, where you can get the result of removing the device
-(void) removeDeviceWithDevicePid:(NSString *) devicePid removeDeviceBlock:(RemoveDeviceBlock)block;

LAN

Products that apply LAN to add devices

Home Station Pro

Flow chart for LAN adding devices

Steps of adding devices by LAN

As to add device via Bluetooth,we need to complete the process of Bluetooth searching and connecting by class BluetoothManager.h , you could also use official API to complete the process of device adding by class BosmaAddDevice.h via Bluetooth.

1. Mobile phone and device are connected to the same Wi-Fi router

Due to the need to use the broadcast packet of the local area network,please make sure that the mobile phone and device is connected to the same Wi-Fi router,it's prerequisite for adding devices by LAN,or it would not able to add device.For example:

2. Search device

Adding device via LAN is completed by class BosmaAddDevice.h , when using this class, we must use the singleton pattern to create objects,Then call the API method in the class BosmaAddDevice.h to complete the device search.when the searching is done,it would be callback by block, developer would need to select the result of searching which is LAN_DEVICE_PAIR_STATUS_WAIT,then stop searching device. Specific API as follows:

/// Create object
+ (BosmaAddDevice *)sharedInstance;

/// Initializes the data for the add device
/// @param block Callback block, that you can get the result of initializing
-(void) initDeviceWithBlock:(InitDeviceBlock)block;

/// Start search LAN devices
-(void) lanStartSerachDeviceBlock:(LANSearchDeviceBlock)block;

/// Exit add LAN devices
-(void) lanExitAddDevice;

3. Configure the device

After searching the device, we need to perform initial data setup of the device.This process could be done through the API of class BosmaAddDevice.h , Specific API as follows:

/// Setup LAN devices
/// @param deviceMAC The MAC of device
/// @param familyId  Bosma AM's family ID,Can be nil
/// @param block Setup device result callback
-(void) lanSetupDevice:(NSString *)deviceMAC familyId:(NSString *__nullable) familyId setupDeviceBlock:(LANSetupDeviceBlock)block;

4. Receive device information

If the initial data of the device is successfully set, the API method needs to be called,start a data listener to receive device information ,when the device initialization is completed,app will receive the device information , the app needs to stop listening. Specific API as follows:

/// Add device information listening in LAN, we can get device information here
/// @param block Callback method, where you can get the data and the result, the return result refer to ENUM_BOSMA_APP_ADDDEVICE_RESULT
-(void) lanAddObserverDeviceInfo:(AddDeviceInfoBlock)block;

/// Removing the listening for device information in LAN
-(void) lanRemoveObserverDeviceInfo;

5. Bind Device

When the APP received the device information ,Customer's cloud server API interface could be called by APP, the binding relation between device and user would be completed .The App can obtain the data of these devices through the API interface of the cloud server, and complete the control of the device in the future.

6. Unbind device

If the app needs to unbind the relation between device and user . Customer's cloud server API interface could be called by APP, to unbind the relation between device and user . Meanwhile,the SDK of API interface would be called for device data restoration.Specific API as follows:

/// Remove the device. After the server removes the device, this method is called to notify the device to clear the user data.
/// @param devicePid The product identity of the device
/// @param block Callback block, where you can get the result of removing the device
-(void) removeDeviceWithDevicePid:(NSString *) devicePid removeDeviceBlock:(RemoveDeviceBlock)block;

Bluetooth

Connecting the device via Bluetooth of mobile.First , search and connect the device, next , transmit the data , at last, adding device is completed .Adding steps as flows:

1.Seach the device and connect the device though Bluetooth of mobile.

2.The data of network is transmitted via Bluetooth, and device information is receiving via Bluetooth.

3.Register and activate the device.

Products that apply Bluetooth to add devices

X1
Home Station

Flow chart of adding device via Bluetooth

steps of adding device via Bluetooth

Since adding devices needs to be done via Bluetooth，we would need to complete the Bluetooth search and connect through class BluetoothManager.h ,you could use your official API to compete the Bluetooth connection of device ,and complete the process of adding device through class BosmaAddDevice.h .

1.Determine Bluetooth permissions

Create a member variable Management of Bluetooth

@property (strong, nonatomic) BosmaBluetoothManager *bluetoothCenter;

Before searching the Bluetooth, you need to determine whether the App can use the mobile phone's Bluetooth.If the system has allowed the App to use Bluetooth,you can start searching for devices.Sample code as following:

    
// Initialize
self.bluetoothCenter = [BosmaBluetoothManager sharedInstance] ;

__weak typeof(self) weakSelf = self;
if([self.bluetoothCenter bluetoothIsOn]){
    NSLog(@"Bluetooth is powered ON");
    // Scan target bluetooth devices
}
else{
    [self.bluetoothCenter bluetoothPowerStatusCallback:^(BSBluetoothManagerState status) {
        if (status == BSBluetoothManagerStatePoweredOn) {
            NSLog(@"Bluetooth is powered ON");
            // Scan target bluetooth devices
        }
        else{
            NSLog(@"Bluetooth is powered Error");
        }
    }];
}

2. Search Bluetooth

Searching Bluetooth could be done though the API method of a BosmaBluetoothManager.h .when a device is searched by SDK ,it would be callback by block,developer would need to select the result of searching,and choose the one they need, and stop searching.it's recommended to choose the best signal Bluetooth. Specific API as follows:

/// Start searching for Bluetooth devices
/// @param devicePrefix Scan the prefix of the target device name
/// @param block Callback for searching Bluetooth device results, every time a device is found
- (void)scanForBluetoothWithDevicePrefix:(NSString *) devicePrefix scanCallback:(BluetoothManagerScanBlock)block;

/// Stop searching for Bluetooth
- (void)stopScanForBluetooth;

To ensure search accuracy,the above method of parameter devicePrefix could be filtered by which is defined by the broadcast name prefix of BosmaBluetoothDefine.h . As following:

// Bluetooth broadcast name prefix of Device
#define kBluetoothBroadcastNamePrefixDevice  @"Bosma"
// Bluetooth broadcast name prefix of Home Station
#define kBluetoothBroadcastNamePrefixStation  @"Station"
// Bluetooth broadcast name prefix of Aeigs
#define kBluetoothBroadcastNamePrefixAegis  @"DoorLock"
// Bluetooth broadcast name prefix of Keypad
#define kBluetoothBroadcastNamePrefixKeypad  @"Keypad"
// Bluetooth broadcast name prefix of Keypad when in OTA mode, such as: "KeypadR"
#define kBluetoothBroadcastNamePrefixKeypadOTA  @"KeypadR"

3. Connect to Bluetooth and receive Bluetooth data

Connecting management of Bluetooth could be done by API method of BosmaBluetoothManager.h ,once connected successfully,the SDK will return the data of the successfully connected Bluetooth object through the block,these data are required for initialization of the add device process.At the same time, if the SDK receives Bluetooth data, it will also be returned through the block, and these Bluetooth data need to be parsed and processed by the SDK. Specific API as follows:

/// Connect a Bluetooth device
/// @param peripheral Target connected Bluetooth device object
/// @param connectBlock Status callback of connected Bluetooth device
/// @param receiveDataBlock Callback when Bluetooth data is received
- (void)connectBluetooth:(CBPeripheral *)peripheral connectBlock:(BluetoothCenterConnectBlock)connectBlock receiveDataBlock:(BluetoothCenterReceiveDataBlock)receiveDataBlock;

/// Cancel the connected Bluetooth device
- (void)cancelConnectBluetooth;

/// Disconnect the connected Bluetooth device
- (void)disconnectBluetooth;

4. Parse Bluetooth data

After establishing a Bluetooth connection,the device and the mobile phone can transfer data through Bluetooth.When the developer receives these Bluetooth data,Data processing needs to be done through the class BosmaAddDevice.h ,So once the developer receives the Bluetooth data,the received data needs to be processed by the API method of BosmaAddDevice.h .Specific API as follows:

/// The notification component parses the data of the Bluetooth IPC device
/// @param data The data of the Bluetooth IPC device
-(void) parseBluetoothIpcDeviceReceivedData:(NSData *) data;

5. The initialization of the device adding process

After establishing a Bluetooth connection,enter the process of adding equipment.Adding devices is done by the class BosmaAddDevice.h ,when adding devices, first we need to use the connected Bluetooth object data to initialize the process of adding a device,after the successful initialization , we could proceed the next step.Specific API as follows:

/// Initialize the Bluetooth IPC device. This is a prerequisite for adding a device.
/// @param peripheral Connected Bluetooth device object.Returns when the device is successfully connected
/// @param txCharacteristic Represents a service's characteristic.Returns when the device is successfully connected
/// @param block Result callback for initializing a Bluetooth IPC device
-(void) initBluetoothIpcDeviceWithPeripheral:(CBPeripheral *)peripheral characteristic:(CBCharacteristic *)txCharacteristic  initDeviceBlock:(InitBluetoothIpcDeviceBlock)block;

6. Fetching a list of WiFi hotspots around the device

Since the device's WiFi module does not works with all WiFi hotspots, developers need to call the API interface,request WiFi hotspot information nearby, SDK will return the data of the WiFi hotspot information through the block.The WiFi hotspot information searched by the device is supported by the device.Specific API as follows:

/// Request WiFi list from Bluetooth IPC device
/// @param block WiFi list callback
-(void) requestBluetoothIpcDeviceSearchWiFiListBlock:(CommandGetWiFiListBlock)block;

7. Device's network configuration

Our products are all wireless products,most of the work requires the support of the network.Therefore, the developer needs to select a WiFi hotspot from the list of WiFi hotspots searched by the device to complete the network configuration of the device,it's recommended to choose the strongest WiFi hotspot.Once the device is networked,It will return to the network configuration status through the block first, after the device is initialized, return the device information that has not been registered and activated through block, Specific API as follows:

If the model of product is X1,please use below method:

/// Set the network configuration information of the Bluetooth IPC device
/// @param ssid WiFi name, only supports 2.4G
/// @param password WiFi password, only supports 2.4G
/// @param block Network configuration result callback
/// @param deviceInfoBlock Callback of device information. This device has not been registered and activated. You need to register and activate this device before it can be used normally.
-(void) setupX1DeviceWiFiInformation:(NSString *) ssid password:(NSString *) password wiFiInformationBlock:(SendWiFiInformationBlock) block addDeviceInfoBlock:(AddBleIpcDeviceInfoBlock)deviceInfoBlock;

If the model of product is not X1,for example(Home Station),then use the following method:

/// Set the network configuration information of the Bluetooth IPC device
/// @param ssid WiFi name, only supports 2.4G
/// @param password WiFi password, only supports 2.4G
/// @param familyId Bosma AM's family ID,Can be nil
/// @param target Operating environment of the device
/// @param block Network configuration result callback
-(void) setupBluetoothDeviceWiFiInformation:(NSString *) ssid password:(NSString *) password familyId:(NSString *__nullable) familyId target:(ENUM_BOSMA_APP_TARGET) target wiFiInformationBlock:(SendWiFiInformationBlock) block;

8. Get device information

If the model of product is X1,you need to activate the registered device,call the following API methods of the SDK to complete the registration and activation,it could be used normally.Once the device is activated you will receive device information,then you need to bind the device information and user information on your own cloud server, so as to query the user's device information later,Specific API as follows:

/// @param addDeviceInfoModel Need to register the activated device object
/// @param familyId Bosma AM's family ID,Can be nil
/// @param block Callback method, where you can get the data of the  device
-(void) registerX1Device: (BosmaAddDeviceInfoModel *)addDeviceInfoModel familyId:(NSString *__nullable) familyId block:(RegisterBleIpcDeviceBlock)block;

If the model of product is not X1,for example(Home Station), After completing the device network configuration,you need to start a device information listener,to receive device information.When you receive device information, you need to stop this listener,at the same time, you need to bind the device information and user information on your own cloud server, so as to query the user's device information later,Specific API as follows:

/// Add device information listening, we can get device information here
/// @param block Callback method, where you can get the data and the result
-(void) addObserverForDeviceInfo:(AddDeviceInfoBlock)block;

/// Removing the listening for device information
-(void) removeObserverForDeviceInfo;

Sub-device - Security Kit

Sub-devices would works when were bound to a gateway device or a device with gateway function.The design idea of adding sub-devices is: select a gateway device first, then connect this gateway,and notify it to enter the state of searching for sub-devices,next direct the user to trigger the sub-device,so that the gateway can search for this sub-device.After receiving the information of the sub-device, the sub-device needs to be activated, and at the same time, the gateway is notified to update the sub-device list.

Products that apply to Sub-device(Security Kit) adding

Door Sensor
Motion Detector
Door/Window Sensor
Keypad
Gateway

Flowchart of adding Sub-device (Security Kit)

Sub-device(Security Kit) adding steps

Since the sub-device needs to be bound to the gateway device first, bind to the user.So we need to connect the gateway device first and get the connection object BosmaCamera.h , Then use the API method provided in the property cameraAddAccessories of this connection object to complete the search for sub-devices, This property type is CameraAddAccessories.h ，Finally, use the class BosmaAddDevice.h to complete the registration and activation of sub-devices.

1. Select gateway device

Select a gateway device in your device list, for example: X1, X1-G, XC-G, XC-GS, etc. If the gateway device has not been added, please add the gateway device first and then add the sub-device.

2. Connect the gateway device

For the connection of the gateway device, please refer to the SDK flow chart.For specific API methods, see the method description of BosmaCamera.h .

3. Search Sub-device

After the gateway device is successfully connected, the gateway is notified to start searching for nearby sub-device information, which is done through the class CameraAddAccessories.h .Specific API methods as flows:

/**
 Notify the gateway device to enter or exit the search accessories state
 
 @param controlValue Control command，enter or exit the search accessories state
 */
-(void)sendCommandWithControlValue:(ENUM_BOSMA_APP_MARTHOME_CONTROL_VALUE)controlValue;

4. Receive Sub-device data

First guide the user to complete the initialization of the sub-device, and then call the SDK API to start the process of receiving the information of the sub-device. When the APP receives the sub-device information, it needs to stop the process. These work are done through the class CameraAddAccessories.h ,the specific API methods are as follows:

/**
 To get the list of accessories scanned by the gateway, you need to manually call the stopGetAccessoriesList to stop the data listening of the accessories list
 */
-(void)getAccessoriesDevices;

/**
Stop accessories list data listening
 */
-(void) stopGetAccessoriesList;

5. Register and activate sub-devices

After the App receives the data of the sub-device, it needs to register and activate the sub-device. This work is done by the class BosmaAddDevice.h .The specific API methods are as follows:

/// Register the accessory device and activate the device
-(void) registerAccessoriesDevice:(BosmaAddAccessoriesInfoModel *) accessoriesModel familyId:(NSString *__nullable) familyId  gatewayDeviceId:(NSString *)gatewayDeviceId registerDeviceBlock:(RegisterAccessoriesBlock)block;

6. Notify the gateway device to update the list of child devices

After the App registers and activates the sub-device, it also needs to notify the gateway device to update the binding record of its sub-device, otherwise the gateway device cannot provide relevant support for this sub-device.This work is done by the class CameraAddAccessories.h .The specific API methods are as follows:

/**
 Notifies the gateway device to update the list of accessories
 */
-(void)notifactionFWUpdateAccessories;

7. Bind Sub-device

After the App receives the sub-device data sent by the gateway device, the App can call the API interface of the cloud server to complete the binding relationship between the device and the user. In the future, the App can obtain the data of these devices through the API interface of the cloud server to complete the control of the device.

8. Unbind Sub-device

If the app needs to release the binding relationship between a sub-device and the user, the app needs to call the API interface of the customer's cloud server to release the binding relationship between the device and the user.At the same time, it is also necessary to call the API interface of the SDK's class BosmaAddDevice.h , restore the data of the device, and call the API interface of the SDK's class CameraAddAccessories.h , to notify the gateway device to update the data of its peripheral devices.

The API interface of the class AddBosmaDevice.h is as follows:

/// Remove the device. After the server removes the device, this method is called to notify the device to clear the user data.
/// @param devicePid The product identity of the device
/// @param block Callback block, where you can get the result of removing the device
-(void) removeDeviceWithDevicePid:(NSString *) devicePid removeDeviceBlock:(RemoveDeviceBlock)block;

The API interface of the class CameraAddAccessories.h is as follows:

/**
 Notifies the gateway device to update the list of accessories
 */
-(void)notifactionFWUpdateAccessories;

Sub-device - Camera

Sub-devices (camera) need to be bound to a storage gateway device to work properly.Its design idea is: first select a storage gateway device. Then connect the gateway and notify it to enter the state of searching for sub-devices.Then instruct the user to trigger the sub-device so that the gateway can search for this sub-device.After receiving the information of the sub-device, you need to activate the sub-device and notify the gateway to update the list of sub-devices.

Products that apply Sub-devices (camera) to adding

EverView

Flowchart of adding Sub-device (camera)

Sub-device(camera) adding steps

Since the sub-device needs to be bound to the gateway device first, it can be bound to the user. So we need to connect the gateway device first and get the connection object BosmaCamera.h ,Then use the API method of which connection object provided in the property cameraStation to complete the search of sub-devices,This property type is CameraStation.h ，and finally use the class BosmaAddDevice.h to complete the registration and activation of sub-devices.

1. Select gateway device

Select a gateway device in your device list, for example:Home Station,Home Station Pro. If the gateway device has not been added, please add the gateway device first and then add the sub-device.

2. Connect the gateway device

For the connection of the gateway device, please refer to the SDK flowchart. For the specific API method, see the method description in BosmaCamera.h .

3. Enter pairing mode

After connecting to the gateway device successfully, need to notify the gateway to enter pairing mode.After entering the pairing mode, the gateway starts to search for the information of nearby sub-devices.These work are done through the class CameraStation.h and the specific API methods are as follows:

/**
 Control the pairing status of the device
 
 @param control Pairing status of the device
 @param timeout The timeout of device binding, the default is 120 seconds
 */
-(void) pairingControl:(ENUM_DEVICE_PAIR_STATUS) control timeout:(int) timeout;

/**
 Get the status of pair devices
 */
-(void) pairingStatus;

4. Search sub-device data

Call the SDK API to notify the gateway device to start searching for the information of the sub-device, and guide the user to complete the initialization of the sub-device (Graphical Guidelines),When the gateway searches for sub-device information, it will return the sub-device information through the proxy method. These work are done through the class CameraStation.h ,and the specific API methods are as follows:

/**
 Get device information that can be paired
 */
-(void) pairingSearchDevices;

Implement the method of proxying CameraStationDelegate and receive device information in the delegation protocol method, as follows:

/**
 The delegate method,it will be called when receive device basic information
 
 @param cameraHub The object of CameraHub manager
 @param modelCode The product type
 @param firmwareVersion Current software version
 @param deviceMAC Device mac
 @param result Request the results
 */
- (void)cameraStation:(CameraStation *) cameraStation pairDeviceModelCode:(NSString * __nullable)modelCode firmwareVersion:(NSString * __nullable)firmwareVersion deviceMAC:(NSString * __nullable)deviceMAC result:(ENUM_BOSMA_APP_RESULT)result;

5. Register and activate sub-devices

After the App receives the data of the sub-device, it needs to register and activate the sub-device.This work is done by the class BosmaAddDevice.h .The specific API methods are as follows:

/// Register LAN peripherals
-(void) lanRegisterPeripheralsWithMAC:(NSString * __nullable)deviceMAC modelCode:(NSString * __nullable)modelCode firmwareVersion:(NSString * __nullable)firmwareVersion gatewayDeviceId:(NSString * __nullable)gatewayDeviceId familyId:(NSString *__nullable) familyId registerBlock:(AddDeviceInfoBlock)block;

6. Notify the gateway device to update the list of sub-devices

After the App registers and activates the sub-device, it also needs to notify the gateway device to update the binding record of its sub-device,otherwise, the gateway device cannot provide relevant support for this sub-device.This work is done by the class CameraStation.h .The specific API methods are as follows:

/**
 Notify device binding result
 
 @param isSuccess Device binding result, YES succeeded, NO failed
 @param deviceMAC The MAC address of the device to be remove
 */
-(void) pairingNoticeResult:(BOOL) isSuccess deviceMAC:(NSString *) deviceMAC;

7. Bind Sub-device

The app can call the API interface of the customer's cloud server to complete the binding relationship between the device and the user.In the future, the App can obtain the data of these devices through the API interface of the customer's cloud server to complete the control of the device.

8. Unbind Sub-device

If the App needs to release the binding relationship between a sub-device and the user,The app needs to call the API interface of the customer's cloud server to release the binding relationship between the device and the user.At the same time, it is also necessary to call the SDK's API interface of the class BosmaAddDevice.h to restore the data of the device.The specific API methods are as follows:

/// Remove the device. After the server removes the device, this method is called to notify the device to clear the user data.
/// @param devicePid The product identity of the device
/// @param block Callback block, where you can get the result of removing the device
-(void) removeDeviceWithDevicePid:(NSString *) devicePid removeDeviceBlock:(RemoveDeviceBlock)block;