JBL Pulse2 iOS Framework Developer’s Guide¶

Version:	1.0

Prerequirements¶

The following steps should be done by Developer before start working with SDK:

Add the Pulse2SDK framework to Linked Frameworks and Libraries
Import API header file “HMNPulse2API.h”
Import Apple ExternalAccessory.framework to Xcode project
Add protocol string “com.jbl.connect” in the UISupportedExternalAccessoryProtocols section on the Info.plist

iPhone should esbablish BT connection with Pulse 2 Device in iPhone-> Settings -> Bluetooth.

API Description¶

Device General API methods¶

Application should be first establish BT connection with Device using connectToMasterDevice function (HMNDeviceGeneral.h).

The notification EVENT_DEVICE_CONNECTED (HMNCommonDefs.h) will be received if connection established successfully. Other API functions can be used after this step.

The notification EVENT_DEVICE_CONNECTED includes dictionary with the following keys (defined in HMNDeviceGeneral.h):

KEY_IAP_CONNECTION_ID;
KEY_IAP_MANUFACTURER;
KEY_IAP_NAME;
KEY_IAP_SERIAL_NUMBER;

The notification EVENT_DEVICE_DISCONNECTED (HMNCommonDefs.h) will be received if connection with device lost.

Device Info API methods¶

/**

* @discussion Change device name.

* @param deviceName An new device name. Nonnull.

* @return none.

*/

(void) setDeviceName :(NSString * _Nonnull)deviceName;

/**

* @discussion Request information from Device like name, battery, active channel.

* @return none.

*/

(void) requestDeviceInfo;

Application will receive notification “EVENT_DEVICE_INFO” with Dictionary included device info. The following keys can present in dictionary (HMNDeviceInfo.h):

KEY_DEVICE_INFO_DEVICE_INDEX;
KEY_DEVICE_INFO_DEVICE_NAME;
KEY_DEVICE_INFO_PRODUCT_ID;
KEY_DEVICE_INFO_MODEL_ID;
KEY_DEVICE_INFO_BATTERY_IS_CHARGING;
KEY_DEVICE_INFO_BATTERY_VALUE;
KEY_DEVICE_INFO_LINKED_DEVICE_COUNT;
KEY_DEVICE_INFO_ACTIVE_CHANNEL_VALUE;
KEY_DEVICE_INFO_AUDIO_SOURCE_VALUE;
KEY_DEVICE_INFO_MAC_ADDRESS_VALUE;

/**

* @discussion Request information from Device for the specified token

* @param token. Value from enumeration HMNToken

* @param index. Device index: 0 - master, 1 - slave.

* @return none.

*/

(void) requestDeviceInfoToken :(HMNToken)token forDeviceIndex:(UInt8)index;

DFU API methods¶

/**

* @discussion Request version from Device.

* @return none.

*/

(void) requestVersion;

Application will receive notification “EVENT_VERSION” with Dictionary included version info. The following keys can present in dictionary (HMNDFU.h):

KEY_SW_VERSION;

KEY_HW_VERSION;

Led Control API methods¶

/**

* @discussion Setup Background Color to Master Device

* @param color - UIColor object

* @param propageToSlaveDevice - Need to propagete background color to Slave device

* @return none.

*/

(void) setBackgroundColor:(UIColor * _Nonnull)color propagateToSlaveDevice:(BOOL)applyToSlave;

/**

* @discussion Draw 11(columns)x9(rows) color image bitmap on the Master Device

* @param imageMatrix - Array of 99 UIColor* objects,The color of each pixel is represented color by UIColor.

* @return none.

*/

(void) setColorImage:(NSArray * _Nonnull)imageMatrix;

/**

* @discussion Display Char on master and slave device

* @param charAsciiCode - Char ascii code - in hex; Supported ascii symbols: 0..9 A..Z ? ! $ + - = % * / # ” & ‘ ( ) , . : ; < > ` { | } ~

* @param charColor - Color of char;

* @param backgroundColor - Background color;

* @param applyToSlave - if need to propagate to slave device

* @return none.

*/

(void) setLedChar:(UInt8)charAsciiCode charColor:(UIColor * _Nonnull)charColor backgroundColor:(UIColor * _Nonnull)backgroundColor applyToSlaveDevice:(BOOL)applyToSlave;

/**

* @discussion Propagate Current Led Pattern on master to slave device

* @return none.

*/

(void) propagateCurrentLedPattern;

/**

* @discussion Query device led brightness.

* It will reply with EVENT_BRIGHTNESS notification

* @return none.

*/

(void) requestLedBrightness;

Application will receive notification “EVENT_BRIGHTNESS” with Dictionary included brightness info. The following keys can present in dictionary (HMNLedControl.h):

KEY_LED_BRIGHTNESS

/**

* @discussion Set Display Led Brightness on master device

* @param brightness - 0..255;

* @return none.

*/

(void) setLedBrightness:(UInt8)brightness;

/**

* @discussion Set Pattern on master device

* @param pattern - id of pattern

* @param patternData - array of 99 unsigned int values wrapped to NSNumbers for Canvas and Firefly:

* 0 - do not draw point

* non-0 - draw point on canvas

* - nil for other pattern types

* @return none.

*/

(void) setLedPattern:(HMNPattern)pattern withData:(NSArray * _Nullable)patternData;

/**

* @discussion Query device led pattern information.

* It will reply with EVENT_PATTERN_INFO notification.

* @return none.

*/

(void) requestLedPatternInfo;

Application will receive notification “EVENT_PATTERN_INFO” with Dictionary included pattern info. The following keys can present in dictionary (HMNLedPattern.h):

KEY_LED_PATTERN_ID its id of the pattern enumerated in the HMNCommonDefs.h

/// Device Patterns

typedef NS_ENUM(NSInteger, HMNPattern) {

HMNPattern_Firework = 0,

HMNPattern_Traffic,

HMNPattern_Star,

HMNPattern_Wave,

HMNPattern_FireFly,

HMNPattern_Rain,

HMNPattern_Fire,

HMNPattern_Canvas,

HMNPattern_Hourglass,

HMNPattern_Ripple

};

Sensor Control API methods¶

/**

* @discussion Request microphone sound level from Device.

* It will reply with EVENT_SOUND notification

* @return none.

*/

(void) requestMicrophoneSoundLevel;

Application will receive notification “EVENT_SOUND” with Dictionary included pattern info. The following key can present in dictionary (HMNSensorControl.h):

/// The Value has NSNumber value

KEY_MICROPHONE_LEVEL;

/**

* @discussion Request for capturing color by Color Picker from the Device

* It will reply with EVENT_SENSOR_CAPTURE_COLOR notification

* @return none.

*/

(void) requestColorFromColorPicker;

When device color sensor capture the color it send notification EVENT_SENSOR_CAPTURE_COLOR.

Application will receive notification “EVENT_SENSOR_CAPTURE_COLOR” with Dictionary included color info. The following keys can present in dictionary (HMNSensorControl.h):

KEY_LED_COLOR_R;

KEY_LED_COLOR_G;

KEY_LED_COLOR_B;

Notes¶

The device can accept one commad at second. If application required to send several commands it should send them with delay for 1 second for each command.

Sample Usage¶

Device Connection Example¶

(void) viewDidLoad {

[super viewDidLoad];

[self subscribeForNotification];

[HMNDeviceGeneral connectToMasterDevice];

}

(void) subscribeForNotification {

[[NSNotificationCenter defaultCenter] addObserver:self

selector:@selector(deviceConnected)

name:EVENT_DEVICE_CONNECTED

object:nil];

}

Color Sensor handler example¶

(void) sensorCaptureColorReceived:(NSNotification * )notification {

NSDictionary *devInfoDict = [notification userInfo];

NSInteger R = [devInfoDict[KEY_LED_COLOR_R] integerValue];

NSInteger G = [devInfoDict[KEY_LED_COLOR_G] integerValue];

NSInteger B = [devInfoDict[KEY_LED_COLOR_B] integerValue];

NSLog(@”RGB color: %ld %ld %ld ”, (long)R, (long)G, (long)B);

}

Device pattern handler example¶

(void) patternReceived:(NSNotification * )notification {

NSDictionary *devInfoDict = [notification userInfo];

HMNPattern pattern = [devInfoDict[KEY_LED_PATTERN_ID] integerValue];

NSLog(@”Pattern ID = %ld ”, (long)pattern);

}

Version handler example¶

(void) versionReceived:(NSNotification * )notification {

NSDictionary *devInfoDict = [notification userInfo];

NSString *swVersion = devInfoDict[KEY_SW_VERSION];

NSString *hwVersion = devInfoDict[KEY_HW_VERSION];

NSLog(@”swVersion %@, hwVersion %@”, swVersion, hwVersion);

return;

}

Brightness handler example¶

(void) brightnessReceived:(NSNotification * )notification {

NSDictionary *devInfoDict = [notification userInfo];

NSUInteger brightness = [devInfoDict[KEY_LED_BRIGHTNESS] unsignedIntegerValue];

NSLog(@”brightness %lu”, (unsigned long)brightness);

return;

}

Sound handler example¶

(void) soundEventReceived:(NSNotification * )notification {

NSDictionary *devInfoDict = [notification userInfo];

NSUInteger microphoneLevel = [devInfoDict[KEY_MICROPHONE_LEVEL] unsignedIntegerValue];

NSLog(@”microphone level %lu”, (unsigned long)microphoneLevel);

return;

}

Show Letter example¶

(void) showAChar {

Byte charCode = 65; // A

UIColor *charColor = [UIColor redColor];

UIColor *backgroundColor =[UIColor blueColor];

[HMNLedControl setLedChar:charCode charColor:charColor backgroundColor:backgroundColor applyToSlaveDevice:NO];

}

Show Hourglass example¶

(void) showHourglassPattern {

Byte imageMatrix[] = {

0, 0, 0, 0, 0, 0, 0, 0, 0, 1, 0,

0, 0, 0, 0, 0, 0, 0, 0, 1, 1, 0,

0, 0, 0, 0, 0, 0, 0, 1, 0, 1, 0,

0, 0, 0, 0, 0, 0, 0, 0, 0, 1, 0,

0, 0, 0, 0, 0, 0, 0, 0, 0, 1, 0,

0, 0, 0, 0, 0, 0, 0, 0, 0, 1, 0,

0, 0, 0, 0, 0, 0, 0, 0, 0, 1, 0,

0, 0, 0, 0, 0, 0, 0, 0, 0, 1, 0,

0, 0, 0, 0, 0, 0, 0, 0, 0, 1, 0

};

NSMutableArray *array = [NSMutableArray arrayWithCapacity:LED_COUNT];

for (int i=0; i<LED_COUNT; i++) {

[array addObject:[NSNumber numberWithUnsignedInt:imageMatrix[i]]];

}

[HMNLedControl setLedPattern:HMNPattern_FireFly withData:array];

}

Show color image example¶

(void)setDigit1ColorImage {

Byte imageMatrix[] = {

0, 0, 0, 0, 0, 0, 0, 0, 0, 1, 0,

0, 0, 0, 0, 0, 0, 0, 0, 1, 1, 0,

0, 0, 0, 0, 0, 0, 0, 1, 0, 1, 0,

0, 0, 0, 0, 0, 0, 0, 0, 0, 1, 0,

0, 0, 0, 0, 0, 0, 0, 0, 0, 1, 0,

0, 0, 0, 0, 0, 0, 0, 0, 0, 1, 0,

0, 0, 0, 0, 0, 0, 0, 0, 0, 1, 0,

0, 0, 0, 0, 0, 0, 0, 0, 0, 1, 0,

0, 0, 0, 0, 0, 0, 0, 0, 0, 1, 0

};

NSMutableArray *colors = [NSMutableArray arrayWithCapacity:LED_COUNT];

UIColor *redColor = [UIColor redColor];

UIColor *blueColor = [UIColor blueColor];

for (int i=0; i<LED_COUNT; i++) {

UIColor *color = (imageMatrix[i] == 0)? redColor: blueColor;

[colors addObject:color];

}

[HMNLedControl setColorImage:colors];

}