# MinewModuleKit Programming Guide for iOS

This SDK only supports the module device producted by Minew. The developers can handle all bluetooth operations between iPhone and modules. such as: scan modules, connect modules, write data to modules, receive data from modules and so on.

# PreWorks

This framework is very simple: the MTModuleManager is device managing Class, always using shared instance when the APP is running. the MTModule is device instance Class, the SDK will create instances for devices. the developer can use the MTModule instance for operate module devices.

The framework is as the screenshot below:

设计说明

MTModuleManager： Device managing class, you can scan module devices around, and connect to the modules.

MTModule： the Module instance class, when the manager found a physical module device it will create a module instance for the device, the instance is correspond to the module device.

# Start Developing

# Environment：

  • Xcode9+，This SDK is compiled by Xcode9, Please use Xcode 9 or higher version.
  • iOS8，Limit the lowest system version to iOS8;

# Import to project:

# CocoaPods

MTModuleKit is available through CocoaPods (opens new window). To install it, simply add the following line to your Podfile, and then import <MTModuleKit/MTModuleKit.h>:

pod 'MTModuleKit'
1

# Manually

  1. please copy the framework file "MTModuleKit.framework" to your project, then add to your project. as the screenshot below:

    添加framework

  2. Please Click: “Target” -> General -> Embedded Binaries , then click the "+" button and click "Add Other" add the framework to "Embedded Binaries", same in ”Linked Frameworks and Libraries“, as the screenshot below:

frameworkadded

  1. if you are using Swift for development, you should add a "Objective C BridgingHeader .h" file (do it yourself please), and add "import <MTModuleKit/MTModuleKit.h>" to the file.
  2. !!! from iOS10, the developer should add a usage description for the project: add Key-Value "Privacy - Bluetooth Peripheral Usage Description" - "You description" to the info.plist file. as the screenshot below:

bluetoothdescription

  1. !!! In iOS13 and above, Apple added permission restrictions on Bluetooth APi. You need to add a string to the project's info.plist file: Privacy-Bluetooth Always Usage Description-"Your usage description".

# Start Developing

# init SDK & scan devices

First of all, you need get the shared instance of MTModuleManager, then this SDK will call the Corebluetooth of iOS system and it will take some time. the SDK only works well when the bluetooth status is Poweron, you can listen the change of the iOS system bluetooth status. refer to the code below.

// get the shared
MTModuleManager *manager = [MTModuleManager sharedInstance];

// if you need to response for the changes of bluetooth status. please listen to the block
[manager didChangesBluetoothStatus:^(BluetoothStatus status){
    
    switch(status) {
        case Poweron:   // !!! make sure bluetooth Poweron.
        {
            NSLog(@"bluetooth status change to poweron");
            // start scan devices.
            [manager startScan:^(NSArray<MTModule *> *Modules){
             // scanned devices callback.
            }];      
            break;
         }
        case Poweroff:
            NSLog(@"bluetooth status change to poweroff");
            break;
        case Unknown:
            NSLog(@"bluetooth status change to unknown");
    }
}];
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
# get current bluetooth status

if you want to check current bluetooth status, please refer to the code below.

PS: this is a Instant status, please refer to the last step for listenning changes.

if(manager.status == Poweron) {
   NSLog(@"the bluetooth status is Poweron."); 
}
1
2
3
# connect to the device
// get the module from last step.
MTModule *module = modules[0];

// listen to the changes of device connection
// ！！！writing data to device needs connected status.
[module didChangeConnection:^(Connection con){
    if(con == Connected) {
        NSLog(@"the device is connected.");
    }
}];

// connect to a module device.
[manager connect:module];
1
2
3
4
5
6
7
8
9
10
11
12
13
# Write data to device

from last step, you can write or receive data from device when the device connected to iPhone.

// write data to device
// at first, make the data you want to write
// This is a 4 bytes data: 0x01,0x02,0x03,0x04.
uint8_t bytes[4] = {0x01, 0x02, 0x03, 0x04};
NSData *data = [NSData dataWithBytes:&bytes length:4];

// then write the data above to device
// you can get a writing result from the block.
[module writeData:data completion:^(BOOL success, NSError *error){
    if(success) {
        NSLog(@"write data successfully.");
    }
    else {
        NSLog(@"write data failed.");
    }
}];
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
# Receiving data from device.

We don't know when the device send data, so please implementate the block.

// the data receiving block.
[module didReceiveData:^(NSData *data){
    NSLog(@"Data received：%@",data);
}];
1
2
3
4
# Get device information.

You can get device information from the property "infos" of MTModule instatnce.

/*
  property infos is a Dictionary of BLE DIS, it contains all the information of the current connection device.
*/
NSDictionary<String *, String *> *disDict = aMTModule.infos;
1
2
3
4
5

"infos == nil" means the device doesn't support DIS, you can check firmware version to find out the device support or not.

Firmware Version(Verison) Support or not
Version < 1.6.0 NO
1.6.0 <= Version < 2.0.0 YES
2.0.0 <= Version < 2.3.0 NO
2.3.0 <= Version < 3.0.0 YES
3.0.0 <= Version < 3.1.0 NO
3.1.0 <= Version YES

# Tables

# MTModuleManager's properties
Name Type Description
status BluetoothStatus the iPhone's bluetooth status
scannedModules NSArray the scanned devices.
connectedModules NSArray the connected devices.
# MTModule
Name Type Description
name NSString the bluetooth name
identifier NSString the id of the device *
advertisingData NSData the advertisement data
lastUpdate NSDate last scanned timestamp
connection Connection the connection status
rssi NSInteger the RSSI
uuids NSDictionary the Service UUID
infos NSDictionary Device informations **

*：due to the limit of iOS, the SDK can't get the device's Mac address, but you can use the identifier. please note every scan task you will get different identifier for every device.

**： only some device can get the device's information, nil value means not supported.

# Tips

  1. If the running display cannot find the path after adding the SDK, remove the package and add it again at General-> Frameworks,Libraries,and Embedded Content.

  2. If the project crashes after running the SDK, the error is **Reason: image not found**, you can check whether the settings are correct in General -> Frameworks, Libraries, and Embedded Content.

    Tips_1

# Change log

  • v1.0 first version;
  • 2021.02.01 v1.1 Fix wrong log printing;
Last Updated:: 1/12/2024, 2:37:29 PM