MinewSensorV3Kit SDK

# MTSensorKit Documentation

This set of SDK only supports the Bluetooth Sensor device produced by Minew, and is currently a temperature and humidity sensor and a door sensor. The SDK can help developers handle all the work between mobile phones and Sensors, مشتمل: أجهزة المسح, أجهزة التوصيل, كتابة البيانات على الأجهزة, استقبال البيانات من الأجهزة, إلخ.

## Preliminary work
Overall framework: MTCentralManager is a device management class, وهو دائمًا مفرد عند تشغيل التطبيق. MTPeripheral is a device instance class. This suite will generate a MTPeripheral instance for each device to facilitate monitoring and operating devices.

**MTCentralManager** : فئة إدارة الأجهزة, which can scan the surrounding Sensor devices, ويمكن ربطها, التحقق منها, إلخ.

**MTPeripheral** : فئة مثيل الجهاز. When MTCentralManager discovers a physical device, MTCentralManager will generate a MTPeripheral instance, الذي يتوافق مع جهاز مادي.

**MTBroadcastHandler** : فئة بث الجهاز, which can get the data when the device broadcasts.

**MTConnectionHandler** : Device connection class for receiving and sending data from the device.

**MTSensorHandler**：传感器操作类，进行设备的读写数据。

## Get started
### بيئة التطوير:
-Xcode10 +, the current SDK is compiled with Xcode11, please use Xcode10 and above for development; -iOS12.0, the minimum system version is iOS12;

## Import into the project:
1. Manually

Copy the development kit files: MTSensorKit.framework files to the project project directory, and then add them to the project.

2. ملاحظة:
* !!! In iOS10 and above, أضافت Apple قيودًا على الأذونات على Bluetooth API. تحتاج إلى إضافة سلسلة إلى ملف info.plist الخاص بالمشروع: Privacy-Bluetooth Peripheral Usage Description-"وصف الاستخدام الخاص بك".

* !!! في iOS13 وما فوق, أضافت Apple قيودًا على الأذونات على Bluetooth API. تحتاج إلى إضافة سلسلة إلى ملف info.plist الخاص بالمشروع: الخصوصية-وصف استخدام البلوتوث دائمًا-"وصف الاستخدام الخاص بك".

### ابدأ التطوير
#### Scanning equipment
First you need to get the singleton of MTCentralManager, ثم تحقق من حالة Bluetooth الحالية للهاتف, ومن ثم يمكنك فحص الجهاز.

```ج
// Get Manager singleton
MTCentralManagerV3 *manager = [MTCentralManagerV3 sharedInstance];

إرسال_بعد(إيفاد_تايم(DISPATCH_TIME_NOW, (int64_t)(1 * NSEC_PER_SEC)), send_get_main_queue(), ^{
    // The current state of the Bluetooth switch on the mobile phone
    if(self->manager.status == PowerStatePoweredOn) {
        // بدء فحص الجهاز
        [مدير startScan:^(NSArray<MTPeripheral *> *الأجهزة الطرفية) {
          //حسب نوع سمة البث, يمكن تصفية نوع المستشعر المطلوب.
        	self->deviceAry = peripherals;
    	}];
    }
});
// يمكن أيضًا الحصول على الأجهزة الممسوحة ضوئيًا باستخدام manager.scannedPeris
// إذا كنت بحاجة إلى الرد على حالة البلوتوث بهاتفك. يرجى الاستماع إلى رد الاتصال.
[قام المدير بتغيير حالة البلوتوث:^(حالة الطاقة){
    
    يُحوّل(حالة) {
        حالة PowerStatePoweredOn:
            NSLog(@"تغيير حالة البلوتوث إلى poweron");
            استراحة;
        حالة PowerStatePoweredOff:
            NSLog(@"تغيير حالة البلوتوث إلى poweroff");
            استراحة;
        حالة PowerStateUnknown:
            NSLog(@"تغيير حالة البلوتوث إلى غير معروف");
    }
}];
```
PS: The entire SDK works only when the Bluetooth state of the phone is in Poweron.

#### Connect to device

```c
// The scanned device can be obtained from the previous step
MTPeripheralV3 *device = deviceAry[0];
// قم بتوصيل الجهاز
[مدير ConnectToPeriperal:جهاز];
// استمع لحالة اتصال الجهاز.
[p.connector didChangeConnection:^(اتصال اتصال) {
    لو (اتصال == تم التحقق منه) {
      	// تم التحقق بنجاح, successfully connected to the device
        NSLog(@"تم التحقق منه");
      	//بحاجة إلى كتابة كلمة المرور, إجراء عمليات أخرى بعد التحقق من كلمة المرور بنجاح
    }
    لو (اتصال == غير متصل) {
        NSLog(@"تم قطع اتصال الجهاز.");
    }
}];
```

### Write password to device

Continuing from the previous step, عندما يقوم الهاتف المحمول بإنشاء اتصال بجهاز معين بنجاح ويتم التحقق بنجاح, you need to write a password to the device for password verification.

```ج
    [device.connector.sensorHandler writePassword:@"minew123" CompleteHandler:^(نجاح بول, MTRecieveErrorType errorType) {
        لو (نجاح) {
            NSLog(@"كلمة المرور صحيحة");
            //then do what you want for example:
        } آخر {
            NSLog(@"كلمة المرور خطأ");
        }
    }];

```

### Other command operations
Continuing from the previous step, when the device successfully verifies that the written password is correct, other command operations can be performed.

The following operations are in no particular order and can be selected by yourself.

#### Get device information
The specific properties of the device information can be found in the attached table.

```ج
 /// Get deveice info.
    /// @param completionHandler the receive block.
		[device.connector.sensorHandler readDeviceInfo:^(نجاح بول, MTDeviceInfoData * _Nonnull data) {
        لو (نجاح) {
            NSLog(@"readDeviceData successfully");
            
            NSString *firVersion = data.firmVersion;
            NSInteger advInterval = data.advInterval;
            NSInteger advTxpower = data.advTxpower;
            BOOL isOpenTempAlarmSwitch = data.isOpenTempAlarmSwitch;
            BOOL isOpenHumiAlarmSwitch = data.isOpenHumiAlarmSwitch;
            double highTempAlarm = data.highTempAlarm;
            double lowTempAlarm = data.lowTempAlarm;
            double highHumiAlarm = data.highHumiAlarm;
            double lowHumiAlarm = data.lowHumiAlarm;
            double temperatureResolution = data.temperatureResolution;
            double humidityResolution = data.humidityResolution;
            double currentTemperature = data.currentTemperature;
            double currentHumidity = data.currentHumidity;
            MTTemperatureUnitType unitType = data.unitType;
            BOOL isStorageSomethine = data.isStorageSomethine;
            NSString *deviceName = data.deviceName;

NSLog(@"firVersion:%@, advTxpower:%دينار, isOpenTempAlarmSwitch:%@, isOpenHumiAlarmSwitch:%@, highTempAlarm:%F, lowTempAlarm:%F, highHumiAlarm:%F, lowHumiAlarm:%F, temperatureResolution:%F, humidityResolution:%F, currentTemperature:%F, currentHumidity:%F, TemperatureUnitType:%@, isOpenStorageSwitch:%@, deviceName:%@", firVersion, advTxpower, isOpenTempAlarmSwitch==YES?@"نعم":@"لا", isOpenHumiAlarmSwitch==YES?@"نعم":@"لا", highTempAlarm, lowTempAlarm, highHumiAlarm, lowHumiAlarm, temperatureResolution, humidityResolution, currentTemperature, currentHumidity, unitType==Celsius?@"Celsius":@"Fahrenheit",  isStorageSomethine==YES?@"نعم":@"لا", deviceName);
            
            لو (data.deviceInfoType == MST01InfoOfHighVersion) {
                NSInteger advIntervalForHTFrame = data.advIntervalForHTFrame;
                NSInteger advIntervalForInfoFrame = data.advIntervalForInfoFrame;
                NSLog(@"advIntervalForHTFrame:%دينار, advIntervalForInfoFrame:%دينار", advIntervalForHTFrame, advIntervalForInfoFrame);
            } آخر {
                NSInteger advInterval = data.advInterval;
                NSLog(@"advInterval:%دينار", advInterval);
            }
            
        } آخر {
            NSLog(@"readDeviceData  failed");
        }
    }];
```
#### Set device name
The device name must not exceed eight digits/letters, and types other than numbers/letters are not supported.
```ج
   /// Set device name.
    /// @param deviceName the device name.
    /// @param completionHandler the receive block.
    [device.connector.sensorHandler setDeviceName:@"minew123" CompleteHandler:^(نجاح بول, MTRecieveErrorType errorType) {
        لو (نجاح) {
            NSLog(@"setDeviceName successfully");
        }
        آخر {
            NSLog(@"setDeviceName failed");
        }
    }];
```

#### Set device storage switch
Set YES to start storing data, set NO to stop storing data.

```ج
  /// Device setting storageData.
    /// @param storageStatus the device whether to store data.
    /// @param completionHandler the receive block.
		[device..connector.sensorHandler setStorageStatusOfHistoricalData:isStorage completionHandler:^(نجاح بول) {
            لو (نجاح) {
                NSLog(@"تم تعيين setIsStorageData بنجاح");
            }
            آخر {
                NSLog(@"فشل setIsStorageData");
            }
    }];
```

#### Set temperature and humidity sensor temperature unit
Temperature units are divided into Celsius and Fahrenheit.

Unit conversion: When Celsius is 20, the conversion to Fahrenheit is 20*1.8+32 .

```ج
		/// Device setting temperature unit.
    /// @param temperatureUnitType  the device temperature unit type of temperature.
    /// @param completionHandler the receive block.
		[device.connector.sensorHandler setTemperatureUnit:Celsius completionHandler:^(نجاح بول, MTRecieveErrorType errorType) {
        لو (نجاح) {
            NSLog(@"setTemperatureUnit successfully");
        }
        آخر {
            NSLog(@"setTemperatureUnit failed");
        }
    }];
```

#### Set temperature and humidity sensor warning upper and lower bounds and warning switch
Note that in Celsius units, the maximum temperature is 85°C and the minimum is -40°C, in Fahrenheit, the maximum temperature is 185°F and the minimum is -40°F; the humidity is 100 maximum and 0 minimum. فضلاً عن ذلك, the upper bound value of the warning interval needs to be greater than or equal to the lower bound value.

```ج
  /// Set alarm temperature and humidity for normal v3 device
    /// @param maxTemp the hightest temperature of the device.
    /// @param minTemp the low temperature of the device.
    /// @param maxHumi  the hightest humidity of the device.
    /// @param minHumi the low humidity of the device.
    /// @param isTempWarn Whether to turn on the switch of the temperature alarm function.
    /// @param isHumiWarn Whether to turn on the switch of the humidity alarm function.
		[device.connector.sensorHandler setHTWarningWithMaxTemp:hTemp minTemp:lTemp maxHumi:hHumi minHumi:lHumi isTempWarn:YES isHumiWarn:YES completionHandler:^(نجاح بول) {
        
        لو (نجاح) {
            NSLog(@"setHTWarning successfully");
        }
        آخر {
            NSLog(@"setHTWarning  failed");
        }
    }];
```

#### Read temperature and humidity historical data

```c
   NSDateFormatter *formatter = [[NSDateFormatter alloc] الحرف الأول];
    [formatter setDateStyle:NSDateFormatterMediumStyle];
    [formatter setTimeStyle:NSDateFormatterShortStyle];
    [formatter setDateFormat:@"YYYY/MM/dd HH:مم:ss"];
    //设置时区
    NSTimeZone* timeZone = [NSTimeZone timeZoneWithName:@"Asia/Beijing"];
    [formatter setTimeZone:timeZone];
    
    /// Get device HTSensor history.
    /// @param formatter the date formatter.
    /// @param unit the device temperature units.
    [device.connector.sensorHandler readHTHistoryWithDateFormatter:formatter Unit:Celsius completionHandler:^(نجاح بول, NSInteger totalNum, NSArray<MTHistoryData *> * _Nonnull data) {
        
        لو (نجاح) {
            NSLog(@"Success to read ht history.");
            ل (int i = 0; أنا < data.count; i++) {
                MTHistoryData *historyData = data[i];
                NSLog(@"originData:%@, timeInterval:%f timeStr:%@, temp:%f, humi:%f", historyData.historyOriginData, historyData.timeInterval, historyData.timeStr, historyData.temp, historyData.humi);
                
                // Historical data has been parsed within the SDK, but if you want to get the raw data and parse the data yourself, you can refer to the code.
                
                
            }
        } else {
            NSLog(@"Failed to read ht history.");
        }
        
    }];
```

#### Firmware upgrade

```c
 // ⚠️Note: The ota upgrade package that comes with the demo may not match the current device. Please use the matching firmware upgrade package to perform the ota upgrade after communicating with the business according to the hardware and firmware information of the device at hand. If you use the wrong firmware update package, this may make your device unusable.
		// It is not feasible to distinguish whether the firmware upgrade package matches the device only by looking at the s3 s4 keywords, because the firmware version and hardware version of the device with different factory settings may not match, so be sure to confirm that the firmware upgrade package is correct.
   
    NSData *otaPacketData = [NSData dataWithContentsOfFile:[[NSBundle mainBundle] pathForResource:@"S3V2_NV900_20210312_s3_ota_v1_0_23" ofType:@".bin"]];

/// ota device by using this method, input  firmware data, then start ota, get statusChange in stateHandler, get firmware file upload progress in progressHandler, get error in errorHandler
    /// @param originOtaData data of ota
    /// @param stateHandler listen status change, only "Completed" means ota successfully.
    /// @param progressHandler listen file uploading progress
    /// @param errorHandler listen errors in ota stage
    [device.connector startOTAWithOTAData:otaPacketData stateHandler:^(OTAState state) {
        if (state == OTAStateStarting) {
            NSLog(@"ota start");
        } else if(state == OTAStateUploading) {
            NSLog(@"ota uploading");
        } else if(state == OTAStateAborted) {
            NSLog(@"ota aborted");
        } else if(state == OTAStateDisconnecting) {
            NSLog(@"ota disconnect");
        } else if (state == OTAStateCompleted) {
            NSLog(@"ota successfully");
        } else if(state == OTAStateFailed) {
            NSLog(@"ota failed");
        }
    } progressHandler:^(float progress) {
        NSLog(@"ota progress:%f", progress);
    } errorHandler:^(NSError * _Nonnull error) {
        NSLog(@"ota  failed,error:%@",error);
    }];
```

### Special configuration of industrial device
#### Set delay recording time
```c
 /// Set delay record Time  for industrial device
    /// @param delayTime the recording delay time range is 0 minutes to 18 hours, set in seconds.
    /// @param completionHandler the receive block.
		[device.connector.sensorHandler setIndustrialHTWarningWithMaxTemp1:hTemp1 minTemp1:lTemp1 maxTemp2:hTemp2 minTemp2:lTemp2 maxHumi:hHumi minHumi:lHumi isTempWarn:YES isTempWarnSecond:YES isHumiWarn:YES completionHandler:^(BOOL success) {
        if (success) {
            NSLog(@"setIndustrialHTWarning successfully");
        }
        else {
            NSLog(@"setIndustrialHTWarning  failed");
        }
    }];
```

#### Set broadcast power

```c
 /// Set broadcast power
    /// @param broadcastPower the value of broadcast power can only be set to -40, -20, -16, -12, -8, -4, 0, 4 dbm
    /// @param completionHandler the receive block.
		[device.connector.sensorHandler setBroadcastPower:-40 CompletionHandle:^(BOOL success) {
        if (success) {
            NSLog(@"setBroadcastPower successfully");
        }
        else {
            NSLog(@"setBroadcastPower  failed");
        }
    }];
```

### Set broadcast interval
Please note that the industrial temperature and humidity firmware version number is below 3.1.0 for devices, and S3-V3 devices can use this directive.

```c
 /// Set broadcast interval  for industrial device
    /// @param broadcastInterval the broadcast interval range is 100-5000ms.
    /// @param completionHandler the receive block.
		[device.connector.sensorHandler setBroadcastInterval:1000 CompletionHandle:^(BOOL success) {
        if (success) {
            NSLog(@"setBroadcastInterval successfully");
        }
        else {
            NSLog(@"setBroadcsetBroadcastIntervalastPower  failed");
        }
    }];
```

Please note that for industrial temperature and humidity, firmware version 3.1.0 and above devices, use this command to set the broadcast interval.

```c
	/// Set the broadcast interval, only for industrial temperature and humidity. This command is used by devices with firmware version 3.1.0 and above.
		/// @param broadcastIntervalForHTFrame the broadcast interval of the temperature and humidity broadcast frame, the range is 1000-60000ms.
		/// @param broadcastIntervalForDeviceInfoFrame the broadcast interval for device info frame range is 100-5000ms.
		[device.connector.sensorHandler setBroadcastIntervalForHTFrame:1000 BroadcastIntervalForDeviceInfoFrame:500 CompletionHandle:^(BOOL success) {
            if (success) {
                NSLog(@"setBroadcastIntervalForMST01HighFirmVersion successfully");
            }
            else {
                NSLog(@"setBroadcsetIntervalForMST01HighFirmVersion  failed");
            }
    }];
```

#### set collection interval
Please note that for industrial temperature and humidity, firmware version 3.1.0 and above devices, use this command to set the collection interval. The collection interval range is 1s--24h. Unit is second.
```c
/// set collect interval
    /// @param collectInterval the collection interval range is 1s--24h. Unit is second.
    [device.connector.sensorHandler setCollectInterval:30 CompletionHandle:^(BOOL success) {
        if (success) {
            NSLog(@"setCollectIntervalForMST01HighFirmVersion successfully");
        }
        else {
            NSLog(@"setCollectIntervalForMST01HighFirmVersion  failed");
        }
    }];
```
#### Set alarm temperature and humidity for industrial device
```c
  /// Set alarm temperature and humidity for industrial device
    /// @param maxTemp1 the hightest temperature of the device.
    /// @param minTemp1 the low temperature of the device.
    /// @param maxTemp2 the second hightest temperature of the device.
    /// @param minTemp2 the second low temperature of the device.
    /// @param maxHumi  the hightest humidity of the device.
    /// @param minHumi the low humidity of the device.
    /// @param isTempWarn Whether to turn on the switch of the temperature alarm function.
    /// @param isTempWarnSecond Whether to turn on the switch of the second temperature alarm function.
    /// @param isHumiWarn Whether to turn on the switch of the humidity alarm function.
		[device.connector.sensorHandler setIndustrialHTWarningWithMaxTemp1:hTemp1 minTemp1:lTemp1 maxTemp2:hTemp2 minTemp2:lTemp2 maxHumi:hHumi minHumi:lHumi isTempWarn:YES isTempWarnSecond:YES isHumiWarn:YES completionHandler:^(BOOL success) {
        if (success) {
            NSLog(@"setIndustrialHTWarning successfully");
        }
        else {
            NSLog(@"setIndustrialHTWarning  failed");
        }
    }];
```
### Schedule
#### MTCentralManager property description

| Name	| Type	| Remark | 
| -------- | -------- | -------- |
| state	| PowerState	| current iphone bluetooth state | 
| scannedPeris	| NSArray	| current scanned devices | 
##### MTPeripheral property description
| Name	| Type	| Remark | 
| -------- | -------- | -------- |
| identifier	| NSString	| Uniquely identifier like "MAC address" | 
| broadcast	| MTBroadcastHandler	| advertising stage handler | 
| connector	| MTConnectionHandler	| connection stage handler | 
#### MTBroadcastHanler property description
| Name	| Type	| Remark | 
| -------- | -------- | -------- |
| name	| NSString	| name of device | 
| rssi	| NSInteger	| current rssi value | 
| battery	| NSString	| battery left, sometimes available | 
| mac	| NSString	| mac string, sometimes available | 
| identifier	| NSString	| identifier string, sometimes available | 
| temp	| double	| Temperature | 
| humi	| double	| Humidity | 
| reseInfo	| uint8_t	| Temperature unit | 
| type	| SensorType	| broadcast frame type | 
| doorStatus	| NSString	| 门磁设备门磁状态 | 
| warningStatus	| uint8_t	| 设备报警状态 |

#### MTConnectionHandler property description

| Name	| Type	| Remark | 
| -------- | -------- | -------- |
| macString	| NSString	| macString of device | 
| connection	| Connection	| current connection status. | 
| sensorHandler	| MTSensorHandlerV3	| sensor read and write operation handler |

#### MTDeviceInfo property description
| Name	| Type	| Remark | 
| -------- | -------- | -------- |
| firmVersion	| NSString	| firm version | 
| advInterval	| NSInteger	| broadcast interval, ms | 
| advTxpower	| NSInteger	| broadcast power, dam | 
| isOpenTempAlarmSwitch	| BOOL	| temperature alarm switch | 
| isOpenHumiAlarmSwitch	BOOL	| humidity alarm switch | 
| highTempAlarm	| double	| temperature warning upper bound | 
| lowTempAlarm	| double	| temperature warning lower bound | 
| highHumiAlarm	| double	| humidity warning upper bound | 
| lowHumiAlarm	| double	| humidity warning upper bound | 
| temperatureResolution	| double	| temperature resolution, Only V3 devices are available | 
| humidityResolution	| double	| humidity resolution, Only V3 devices are available | 
| realTimeTemperature	| double	| real-time temperature | 
| realTimeHumidity	| double	| real-time humidity | 
| temperatureUnitType	| MTTemperatureUnitType	| temperature unit, Celsius/Fahrenheit | 
| isStorage	| BOOL	| whether to store history date | 
| deviceName	| NSString	| device name | 
| delayRecordTime	| int	| delay record time | 
| isOpenTempAlarmSwitchSecond	| BOOL	| the second temperature alarm switch | 
| secondHighTempAlarm	| double	| the second temperature warning upper bound, Only MST01 devices are available | 
| secondLowTempAlarm	| double	| the second temperature warning lower bound, Only MST01 devices are available | 
| advIntervalForHTFrame	| NSInteger	| broadcast interval for htFrame, ms, only when firmware version 3.1.0 and above industrial temperature and humidity equipment | 
| advIntervalForInfoFrame	| NSInteger	| broadcast interval for info frame, ms, only when firmware version 3.1.0 and above industrial temperature and humidity equipment | 
| deviceInfoType	| MTDeviceInfoType	| MST01Info, PR2122Info, MST01InfoOfHighVersion |

#### MTHistoryData property description

| Name	| Type	| Remark | 
| -------- | -------- | -------- |
| historyOriginData	| NSData	| origin history data | 
| humi	| double	| humidity of device | 
| temp	| double	| temperature of device | 
| timeStr	| NSString	| Formatted time string | 
| timeInterval	| NSTimeInterval	| The original value of the time. |

## Precautions
1. During the development process, you may find that if you continue to scan for a period of time, there will be multiple instances of MTPeripheral on some devices. We consulted with Apple engineers about this. The answer is that under the current iOS platform, CoreBluetooth is not friendly to multi-channel broadcast (especially when the broadcast data is changing) devices.

This problem no longer exists in iOS11.

2. If after adding the SDK, the operation shows that the path cannot be found, you can go to General -> Frameworks, المكتبات, والمحتوى المضمن, and change MSensorV3Kit.framework -> Embed ， from ‘Do Not Embed’ to ‘Embed& Sign’.

3. Writing multiple instructions at the same time may cause an exception. It is recommended to write a new instruction after each instruction is completed.

## Documentation version record
2022.05.12 الإصدار الأول v1.0;
2022.08.31 v1.0.1 second version;