HK Page app¶

The Page app records user’s voice and broadcasts it to a set of selected speakers in the network. User can select speakers individually or select rooms. The Page app also contain House Alert feature that broadcast an alarm sound like siren to all of the speakers in the network.

The application also has a feature for changing the speaker information, like speaker name, group name, taking a note, and so on.

HK Wake app¶

Wake app is a kind of Alarm clock. Instead of playing an alarm sound on your phone, the app play a song over the Omni speakers in the network. User can select a set of individual speakers or room to play the alarm sound with.

HK Time app¶

Time (Timer) app is a kind of timer app. Instead of playing a beep sound on your phone, the app plays a predefined song over the Omni speakers in the network. User can select a set of individual speakers or room to play the alarm sound with.

HKWPlayer app¶

HKWPlayer is a sample music player app that plays MP3 audio files with Omni speakers wirelessly. You can create and manage a playlist of MP3 titles from iOS Music app library, and play songs over the Omni speakers in the network. The purpose of the app is to demonstrate the key features of the HKWirelessHD SDK.

HKWHub App (Hub for IoT Integration)¶

HKWHub app is an iOS app that uses HKWirelessHD SDK and acts as a Web Hub that handles HTTP requests to control speakers and stream music. It enables any types of connected devices (e.g. sensors or smart devices like tablet, smart TV, etc.) and cloud-based services (e.g. SmartThings) to connect HK Omni speakers and stream music. HKWHub runs a web server inside that handles HTTP requests of REST API.

User can add songs or sound file from iOS Music app to the media list, so that client devices can access the list and play media in the list remotely by sending REST API request to the Hub app. For example, a door open/close sensor can send REST API request to play ‘dog-barking’ sound in the media list of the HKWHub app.

The following images are the screen captures of HKWHub app.

We also created a sample HTML5 app working as a client of the HKWHub app. The HTML5 app uses AJAX to send REST API requests to the HKWHub app to control speakers and stream music. The UI of the HTML5 app is based on Google’s Polymer v0.5 (https://www.polymer-project.org/0.5/).

The following images are the screen captures of the HTML5 app.

HKWSimple (a very simple music player for getting started with HKWirelessHDSDK)¶

HKWSimple app is a simple music player that was created to explain how to create an app with HKWirelessHD SDK. This app is very simple, but contains key features of HKWirelessHDSDK, such as, manage speakers, control audio playback and volume, play local media files and also web streaming audio, and so on.

Just get started with the HKWSimple app to quickly build your own HKWirelessHD app!

Include HKWirelessHDSDKlw into your project¶

• Add HKWirelessHDSDKlw to your project by dragging and dropping the HKWirelessHDSDKlw folder into the project navigator.

• When you get a dialog saying Choose options for adding these files :,

  • Check the checkmark of Copy items if needed
  • Select Create groups, and click finish.

• By doing this, the include headers and libraries for HKWirelessHDSDKlw are added to your project.

Make sure if libHKWirelessHDlw.a was added to your Link Binary With Libraries¶

• Project Setting > Your Targets > Build Phases > Link Binary With Libraries

  • Check if libHKWirelessHDlw.a was added to the list.
  • If it was not added, add it by clicking + and Add Other....

After adding the HKWirelessHDSDKlw folder into your project and adding libHKWirelessHD.a, the project navigator will look like as below:

Add Swift Bridging Header¶

HKWirelessHD SDK has been written in C++ and Objective-C. Therefore, when you use the SDK in Swift, you should include Swift Bridging Header in your project. To do this:

1. Go to Project Setting > Build Setting > Swift Compiler - Code Generation > Objective-C Bridging Header

2. Add [My-Project-Name]/[My-Project-Name]-Bridging-Header.h

   • In our example, it looks like : HKPage/HKPage-Bridging-Header.h

3. Add the following lines in the header file.

#import "HKWControlHandler.h"
#import "HKWPlayerEventHandlerSingleton.h"
#import "HKWDeviceEventHandlerSingleton.h"

Add -lstdc++ as linker flag¶

• Project Setting > Your Targets > Build Settings > Linking > Other Linker Flags

  • Add “-lstdc++” in the text field

Include HKWirelessHDSDK into your project¶

• Add HKWirelessHDSDK to your project by dragging and dropping the HKWirelessHDSDK folder into the project navigator.

• When you get a dialog saying Choose options for adding these files :,

  • Check the checkmark of Copy items if needed
  • Select Create groups, and click finish.

• By doing this, the include headers and libraries for HKWirelessHDSDK are added to your project.

Make sure if libHKWirelessHD.a was added to your Link Binary With Libraries¶

• Project Setting > Your Targets > Build Phases > Link Binary With Libraries

  • Check if libHKWirelessHDlw.a was added to the list.
  • If it was not added, add it by clicking ‘+’ and Add Other....

Add libz.dylib and libbz.dylib to your Link Binary With Libraries¶

• Project Setting > Your Targets > Build Phases > Link Binary With Libraries

  • Click ‘+’ and find and add libz.dylib and libbz2.dylib to the list

After adding the HKWirelessHDSDKw folder into your project and adding libHKWirelessHD.a, libz.dylib and libbz2.dylib, the project navigator will look like as below:

Add Swift Bridging Header and -lstdc++ as linker flag¶

Follow the instruction for adding Swift bridging header and -lstdc++ linker flag as described in the previous section.

1. Project Setup¶

For the project setup, please refer to the previous session of Project Setup with HKWirelessHDSDK (normal version).

2. Initialize HKWirelessHD Controller¶

In HKWSimple app, the initialization of HKWirelessHD Controller is done in the first ViewController called MainVC. When the app is launched, if HKWControlHandler is not initialized, then the app shows a dialog saying it is about to initialize the HKWControlHandler. This is done in viewDidLoad(). After that, in viewDidAppear(), the app actually tries to initialize HKWControlHandler. And it is successful, it dismisses the dialog. If not, it keeps showing the dialog so that the user can take an action.

As shown in the dialog message, if the app cannot initialize HKWControlHandler, then the reason would be one of the followings:

• The phone is not in Wi-Fi network.
• An app using HKWControlHandler is running on the same phone.

class MainVC: UIViewController {
    var g_alert: UIAlertController!

    override func viewDidLoad() {
        super.viewDidLoad()

        if !HKWControlHandler.sharedInstance().isInitialized() {
            // show the network initialization dialog
            g_alert = UIAlertController(title: "Initializing", message: "If this dialog does not disappear, please check if any other HK WirelessHD App is running on the phone and kill it. Or, your phone is not in a Wifi network.", preferredStyle: .Alert)

            self.presentViewController(g_alert, animated: true, completion: nil)
        }

    }

    override func viewDidAppear(animated: Bool) {

        if !HKWControlHandler.sharedInstance().initializing() && !HKWControlHandler.sharedInstance().isInitialized() {

            dispatch_async(dispatch_get_global_queue(DISPATCH_QUEUE_PRIORITY_DEFAULT, 0), {
                if HKWControlHandler.sharedInstance().initializeHKWirelessController(kLicenseKeyGlobal, withSpeakersAdded:false) != 0 {
                    println("initializeHKWirelessControl failed : invalid license key")
                    return
                }
                println("initializeHKWirelessControl - OK");

                // dismiss the network initialization dialog
                if self.g_alert != nil {
                    self.g_alert.dismissViewControllerAnimated(true, completion: nil)
                }

            })
        }
    }
}

3. Get the list of available speakers¶

The list of speakers are presented in SpeakerSelectionTVC TableViewController. In order to show the list of speakers with the latest status information, the ViewController should receive events about device status. So it implements the delegate functions defined in HKWDeviceEventHandelrDelegate.

First, SpeakerSelectionTVC class should have HKWDeviceEventHandlerDelegate in its class declaration to be a delegate object of it.

class SpeakerSelectionTVC: UITableViewController, HKWDeviceEventHandlerDelegate {

In viewDidLoad(), the class will set the delegate of HKWDeviceEventHandler instance as itself. And then, it starts to refresh the device information, by calling startRefreshDeviceInfo().

override func viewDidLoad() {
        super.viewDidLoad()
        HKWDeviceEventHandlerSingleton.sharedInstance().delegate = self
        HKWControlHandler.sharedInstance().startRefreshDeviceInfo()
}

If the SpeakerSelectionTVC disappears, for example, by clicking Back button of Navigation Controller, it should stop refreshing the device info, so it calls stopRefreshDeviceInfo() in viewDidDisappear().

override func viewDidDisappear(animated: Bool) {
        super.viewDidDisappear(animated)
        HKWControlHandler.sharedInstance().stopRefreshDeviceInfo()
}

The follow codes are all about listing the speakers with their detailed information in the TableView. If a speaker is active, that is, the speaker belongs to playback session, then it shows a checkmark in the cell.

override func numberOfSectionsInTableView(tableView: UITableView) -> Int {
        return HKWControlHandler.sharedInstance().getGroupCount()
}

override func tableView(tableView: UITableView, numberOfRowsInSection section: Int) -> Int {
        return HKWControlHandler.sharedInstance().getDeviceCountInGroupIndex(section)
}

override func tableView(tableView: UITableView, cellForRowAtIndexPath indexPath: NSIndexPath) -> UITableViewCell {
        let cell = tableView.dequeueReusableCellWithIdentifier("Speaker_Cell", forIndexPath: indexPath) as! UITableViewCell
        cell.selectionStyle = UITableViewCellSelectionStyle.None
        var deviceInfo: DeviceInfo = HKWControlHandler.sharedInstance().getDeviceInfoByGroupIndexAndDeviceIndex(indexPath.section, deviceIndex: indexPath.row)
        cell.textLabel?.text = deviceInfo.deviceName;
        var uniqueId: NSString = NSString(format: "ID:%llu, Vol:%d", deviceInfo.deviceId, deviceInfo.volume)
        cell.detailTextLabel?.text = uniqueId as String

        // Show the checkmark if the speaker is active
        if deviceInfo.active {
                cell.accessoryType = UITableViewCellAccessoryType.Checkmark
        } else {
                cell.accessoryType = UITableViewCellAccessoryType.None
        }
        return cell
}

override func tableView(tableView: UITableView, titleForHeaderInSection section: Int) -> String? {
        var header = HKWControlHandler.sharedInstance().getDeviceGroupNameByIndex(section);
        return header
}

override func tableView(tableView: UITableView, didSelectRowAtIndexPath indexPath: NSIndexPath) {
        let cell = tableView.dequeueReusableCellWithIdentifier("Speaker_Cell", forIndexPath: indexPath) as! UITableViewCell
        var deviceInfo: DeviceInfo = HKWControlHandler.sharedInstance().getDeviceInfoByGroupIndexAndDeviceIndex(indexPath.section, deviceIndex: indexPath.row)
        if deviceInfo.active {
                HKWControlHandler.sharedInstance().removeDeviceFromSession(deviceInfo.deviceId)
                cell.accessoryType = UITableViewCellAccessoryType.Checkmark
        } else {
                HKWControlHandler.sharedInstance().addDeviceToSession(deviceInfo.deviceId)
                cell.accessoryType = UITableViewCellAccessoryType.None
        }
}

The follow codes are for handling events from Device Handler. In this example, it just redraw the table when it receives any device update events from the HKWControlHandler.

        func hkwDeviceStateUpdated(deviceId: Int64, withReason reason: Int) {
                self.tableView.reloadData()
                nextBBI.enabled = !(HKWControlHandler.sharedInstance().getActiveDeviceCount() == 0)
        }

        func hkwErrorOccurred(errorCode: Int, withErrorMessage errorMesg: String!) {
                println("Error: \(errorMesg)")
        }
}

The following figure shows a screen of the speaker list.

4. Create the playlist to play¶

SongSelectionTVC shows the list of songs availabe for playback. It searches for the songs included in the app as bundle, and show the list of the songs in TableViewController. To be bundled within an app, mp3 or wav files should be included in the project setting. It also adds a list of songs with the URL information for web-based streaming.

In SongSelectionTVC, there is no use of HKWirelessHD APIs, because it is all about listing songs to play.

class SongSelectionTVC: UITableViewController {
    var g_wavFiles = [String]()
    var g_mp3Files = [String]()
    var curSection = 0
    var curRow = 0
    let serverUrlPrefix = "http://seonman.github.io/music/";
    var songList = ["ec-faith.wav", "hyolyn.mp3"]
    @IBOutlet var bbiNowPlaying: UIBarButtonItem!

    override func viewDidLoad() {
        super.viewDidLoad()

        var bundleRoot = NSBundle.mainBundle().bundlePath
        var dirContents: NSArray = NSFileManager.defaultManager().contentsOfDirectoryAtPath(bundleRoot, error: nil)!
        var fltr: NSPredicate = NSPredicate(format: "self ENDSWITH '.wav'")
        g_wavFiles = dirContents.filteredArrayUsingPredicate(fltr) as! [String]

        for var i = 0; i < g_wavFiles.count; i++ {
            println("wav file: \(g_wavFiles[i])")
        }

        var fltr2: NSPredicate = NSPredicate(format: "self ENDSWITH '.mp3'")
        g_mp3Files = dirContents.filteredArrayUsingPredicate(fltr2) as! [String]

        for var i = 0; i < g_mp3Files.count; i++ {
            println("mp3 file: \(g_mp3Files[i])")
        }

        bbiNowPlaying.enabled = HKWControlHandler.sharedInstance().isPlaying()
    }

    override func numberOfSectionsInTableView(tableView: UITableView) -> Int {
        return 3
    }

    override func tableView(tableView: UITableView, numberOfRowsInSection section: Int) -> Int {
        if section == 0 {
            return g_wavFiles.count
        } else if section == 1 {
            return g_mp3Files.count
        } else if section == 2 {
            return songList.count
        }else {
            return 0
        }
    }

    override func tableView(tableView: UITableView, cellForRowAtIndexPath indexPath: NSIndexPath) -> UITableViewCell {
        let cell = tableView.dequeueReusableCellWithIdentifier("SongTitle_Cell", forIndexPath: indexPath) as! UITableViewCell
        if indexPath.section == 0 {
            cell.textLabel?.text = g_wavFiles[indexPath.row]
        } else if indexPath.section == 1 {
            cell.textLabel?.text = g_mp3Files[indexPath.row]
        } else {
            cell.textLabel?.text = songList[indexPath.row]
        }
        return cell
    }

    override func tableView(tableView: UITableView, titleForHeaderInSection section: Int) -> String? {
        if section == 0 {
            return "WAV file"
        } else if section == 1 {
            return "MP3 file"
        }else {
            return "Web Streaming"
        }
    }

    override func prepareForSegue(segue: UIStoryboardSegue, sender: AnyObject?) {
        if segue.identifier == "Song_Cell" {
            let section = self.tableView.indexPathForSelectedRow()?.section
            curSection = section!
            let row = self.tableView.indexPathForSelectedRow()?.row
            curRow = row!

            let destTVC:NowPlayingVC = segue.destinationViewController as! NowPlayingVC
            destTVC.section = curSection
            destTVC.row = curRow
            if curSection == 0 {
                destTVC.songTitle = g_wavFiles[curRow]
            } else if curSection == 1 {
                destTVC.songTitle = g_mp3Files[curRow]
            } else {
                destTVC.songTitle = songList[curRow]
                destTVC.songUrl = serverUrlPrefix + songList[curRow]
                destTVC.serverUrl = serverUrlPrefix
            }

            destTVC.viewLoadByCellSelection = true
            destTVC.nsWavPath = NSBundle.mainBundle().bundlePath.stringByAppendingPathComponent(destTVC.songTitle)
            destTVC.songSelectionTVC = self
        }
        else if segue.identifier == "NowPlaying_BBI" {
            let destTVC:NowPlayingVC = segue.destinationViewController as! NowPlayingVC
            if curSection == 0 {
                destTVC.songTitle = g_wavFiles[curRow]
            } else if curSection == 1 {
                destTVC.songTitle = g_mp3Files[curRow]
            } else {
                destTVC.songTitle = songList[curRow]
                destTVC.songUrl = serverUrlPrefix + songList[curRow]
                destTVC.serverUrl = serverUrlPrefix
            }

            destTVC.viewLoadByCellSelection = false
            destTVC.nsWavPath = NSBundle.mainBundle().bundlePath.stringByAppendingPathComponent(destTVC.songTitle)
            destTVC.songSelectionTVC = self

        }
    }
}

The following figure shows an example of the SongSelectionTVC screen.

5. Playback and Volume Control¶

NowPlayingVC controls the playback and volume level, so we have to use the related HKWirelessHDSDK APIs. All playback and volume control related events are sent via HKWPlayerEventHandlerDelegate, so NowPlayingVC class should implement the delegate.

Add HKWPlayerEventHandlerDelegate in the class definition.

class NowPlayingVC: UIViewController, HKWPlayerEventHandlerDelegate {

In viewDidLoad(), the NowPlayingVC should set itself to the delegate attribute of HKWPlayerEventHandlerSingleton object, so that all delegate functions implemented in this class can be referenced by the HKWPlayerEventHandler.

override func viewDidLoad() {
    super.viewDidLoad()
    HKWPlayerEventHandlerSingleton.sharedInstance().delegate = self

    labelSongTitle.text = songTitle
    curVolume = HKWControlHandler.sharedInstance().getVolume()
    labelAverageVolume.text = "Volume: \(curVolume)"

    if viewLoadByCellSelection {
        playCurrentTitle()
    } else {
        if HKWControlHandler.sharedInstance().isPlaying() {
            btnPlayStop.setTitle("Stop", forState: UIControlState.Normal)
            labelStatus.text = "Now Playing"
        }
        else {
            btnPlayStop.setTitle("Play", forState: UIControlState.Normal)
            labelStatus.text = "Play Stopped"
        }
    }
}

The followings are several variable to show the list of songs in the ViewController.

var row = 0
var section = 0
var songTitle = ""
var nsWavPath = ""
var viewLoadByCellSelection = false
var songSelectionTVC: SongSelectionTVC!
var curVolume:Int = 50
var songUrl = ""
var serverUrl = ""

var g_alert: UIAlertController!

@IBOutlet var labelSongTitle: UILabel!
@IBOutlet var btnPlayStop: UIButton!
@IBOutlet var labelAverageVolume: UILabel!
@IBOutlet var btnVolumeDown: UIButton!
@IBOutlet var btnVolumeUp: UIButton!
@IBOutlet var labelStatus: UILabel!

The following codes are to play and pause the media file.

@IBAction func playOrStop(sender: UIButton) {
    if HKWControlHandler.sharedInstance().isPlaying() {
        HKWControlHandler.sharedInstance().pause()
        labelStatus.text = "Play Stopped"

        btnPlayStop.setTitle("Play", forState: UIControlState.Normal)

    }
    else {
        playCurrentTitle()
        labelStatus.text = "Now Playing"
    }
}

func playCurrentTitle() {
    // just to be sure that there is no running playback
    HKWControlHandler.sharedInstance().stop()

    if section == 0 {
        if HKWControlHandler.sharedInstance().playWAV(nsWavPath) {
            // now playing, so change the icon to "STOP"
            btnPlayStop.setTitle("Stop", forState: UIControlState.Normal)
        }
    } else if section == 1 {
        let assetUrl = NSURL(fileURLWithPath: nsWavPath)

        if HKWControlHandler.sharedInstance().playCAF(assetUrl, songName: songTitle, resumeFlag: false) {
            // now playing, so change the icon to "STOP"
            btnPlayStop.setTitle("Stop", forState: UIControlState.Normal)
        }
    } else {
        playStreaming()
    }
    songSelectionTVC.bbiNowPlaying.enabled = true
}

func playStreaming() {
    HKWControlHandler.sharedInstance().playStreamingMedia(songUrl, withCallback: {(bool result) -> Void in
        if result == false {
            println("playStreamingMedia: failed")
            self.btnPlayStop.selected = false

            self.g_alert = UIAlertController(title: "Warning", message: "Playing streaming media failed. Please check the Internet connection or check if the meida URL is correct.", preferredStyle: .Alert)
            self.g_alert.addAction(UIAlertAction(title: "OK", style: UIAlertActionStyle.Default, handler: nil))
            self.presentViewController(self.g_alert, animated: true, completion: nil)
        } else {
            println("playStreamingMedia: successful")
            self.btnPlayStop.setTitle("Stop", forState: UIControlState.Normal)
        }
    })
}

The following codes are to control volumes, e.g up and down.

@IBAction func volumeUp(sender: UIButton) {
    curVolume += 5
    if curVolume > 50 {
        curVolume = 50
    }
    HKWControlHandler.sharedInstance().setVolume(curVolume)
    labelAverageVolume.text = "Volume: \(curVolume)"
}

@IBAction func volumeDown(sender: UIButton) {
    curVolume -= 5
    if curVolume < 0 {
        curVolume = 0
    }
    HKWControlHandler.sharedInstance().setVolume(curVolume)
    labelAverageVolume.text = "Volume: \(curVolume)"
}

The following codes implements the delegate functions defined by HKWPlayerEventHandlerDelegate. Here, we can add codes to handle the events of PlayEnded and VolumeChanged.

    func hkwPlayEnded() {
        btnPlayStop.setTitle("Play", forState: UIControlState.Normal)
        songSelectionTVC.bbiNowPlaying.enabled = false
    }

    func hkwDeviceVolumeChanged(deviceId: Int64, deviceVolume: Int, withAverageVolume avgVolume: Int) {
        println("avgVolume: \(avgVolume)")
        curVolume = avgVolume
    }
}

Initialize HKWirelessHD Control Handler and start the Wireless Audio¶

Controlling HK Omni speakers are done by calling APIs provided by HKWControlHandler. So, the first thing to do to use HKWirelessHD APIs is to acquire the singleton object of HKWControlHandler and initialize it.

Once you acquire the HKWControlHandler object, you need to initialize it by calling initializeHKWirelessController(). initializeHKWirelessController() takes a string of license key as parameter. Every developer who signs up for Harman developer community will receive a license key. If you have not received it yet, then just use the license key specified in the sample code for temporary use until your own license key is delivered to you.

This API requires a boolean parameter that specifies if all speakers in the network will be added right after initialzation. If it is true, then all speakers will be added to session, so you can play music without adding speakers separately. If it is false, none of speakers will be added to playback session, so you need to add speakers separately to session to play music using APIs like AddDeviceToSession().

if HKWControlHandler.sharedInstance().isInitialized() == false {
        // HKWControlHandler has not been initialized before. Initialize it now.
        dispatch_async(dispatch_get_global_queue(DISPATCH_QUEUE_PRIORITY_DEFAULT, 0), {
                if HKWControlHandler.sharedInstance().initializeHKWirelessController(g_licenseKey, withSpeakersAdded:true) != 0 {
                        println("initializeHKWirelessControl failed")
                        return
                }

                ...
        })
}

Device Information¶

Each speaker information contains a list of attributes that specify its static information such as speaker name, group name, IP address, etc. and also dynamic information such as volume level, boolean value indicating if it is playing or not, Wi-Fi signal strength, etc.

You can retrieve all the attributes of device (speaker) information through DeviceInfo object, and it is specified in DeviceInfo.h. The following table shows the list of information that DeviceInfo provides.

In the table, “Fixed/Variable” column means if the attribute value is a fixed value during the execution, or can be changed by itself or by calling APIs. “Set by API” column means whether the value of the attribute can be changed by API calls.

Note that all the attributes in DeviceInfo.h are “readonly”. So, you can only read the value of each attribute. You need to use corresponding API functions to change the values of the attributes.

As shown in the table above, some of the attributes can be set by the APIs. And some attributes change during the runtime, so the app should keep the latest value of the attributes by calling corresponding APIs or by callback functions.

The following is an example of retrieving some of attributes of a speaker information.

let deviceInfo: DeviceInfo = HKWControlHandler.sharedInstance().getDeviceInfoByGroupIndexAndDeviceIndex(groupIndex, deviceIndex:deviceIndex)

println("deviceName: \(deviceInfo.deviceName")
println("groupName: \(deviceInfo.groupName")
println("volume: \(deviceInfo.volume")
println("deviceId: \(deviceInfo.deviceId")
println("deviceActive: \(deviceInfo.active")
println("deviceModel: \(deviceInfo.modelName")
...

- (DeviceInfo *) getDeviceInfoByIndex:(NSInteger)deviceIndex;

- (DeviceInfo *) getDeviceInfoByGroupIndexAndDeviceIndex:(NSInteger) groupIndex
                                                deviceIndex:(NSInteger)deviceIndex;

- (DeviceInfo *) getDeviceInfoById:(long long) deviceId;

Refreshing device status information¶

If any change happens on a speaker, the speaker sends an event with updated information to HKWControlHandler and then the speaker information stored in HKWControlHandler is updated. Then, HKWControlHandler calls corresponding delegate protocol functions registered by the app to make it processed by the event handler.

However, in our current implementation, the event dispatching initiated by speaker takes a little more time than the app polling to check if there is any update on speakers. To reduce the time of status update, we provide a pair of functions to refresh device status, which is a kind of polling speakers to check the update. Especially, if you need to show a list of speakers with the latest information, you’d better force to refresh the speaker information, not just waiting updates from speakers.

To discover and update the status of speakers immediately, you can use the following functions:

// start to refresh devices ...
g_HKWControlHandler.startRefreshDeviceInfo()

... ...

// stop to refresh devices
g_HKWControlHandler.stopRefreshDeviceInfo()

startRefreshDeviceInfo() will refresh and update every 2 seconds the status of the devices in the current Wi-Fi network.

Add or remove a speaker to/from a playback session¶

To play a music on a specific speaker, the speaker should be added to the current playback session.

You can check whether or not a speaker is currently added to the current playback session by check the “active” attribute of DeviceInfo object (in DeviceInfo.h).

/*! Indicates if the speaker is active (added to the current playback session) */
@property (nonatomic, readonly) BOOL active;

- (BOOL) addDeviceToSession:(long long) deviceid;

// add the speaker to the current playback session
g_HKWControlHandler.addDeviceToSession(deviceId)

- (BOOL) removeDeviceFromSession:(long long) deviceid;

// remove a speaker from the current playback session
g_HKWControlHandler.removeDeviceFromSession(deviceId)

Play CAF file (MP3, WAV, etc.)¶

If one or more speakers are available to the session, or if there is at least one speaker active, you can start to play a song.

The playback is based on the Apple Core Audio framework. So, the supported audio file and data formats by HKWirelessHDSDK are the same as those supported by Apple’s Core Audio framework. The detailed information is available at iOS audio file formats. According to the Apple developer documentation, CAF supports AIFF (.aif, .aiff), CAF (.caf), MPEG-1, Layer 3 (.mp3), MPEG-2 or MPEG-4 ADTS (.aac), MPEG-4 Audio (.mp4, .m4a), and WAVE (.wav).

- (BOOL) playCAF:(NSURL *)assetURL songName:(NSString*)songName resumeFlag:(BOOL)resumeFlag;

To play a song, you should prepare a AssetURL using NSURL first. Here is an example:

let assetUrl = NSURL(fileURKWithPath: nsPath)

HKWControlHandler.sharedInstance().playCAF(assetUrl, songName: songTitle, resumeFlag: false)

Here, resumeFlag is false, if you start the song from the beginning. If you want to resume to play the current song, then resumeFlag should be true. songTitle is a string, representing the song name. (This is only internally used as a file name to store converted PCM data in the memory temporarily.)

If you want to specify a starting point of the audio stream, then you can use playCAFFromCertainTime() to start the playback from a specified time.

- (bool) playCAFFromCertainTime:(NSURL *)assetURL
                                                songName:(NSString*)songName
                                                startTime:(NSInteger)startTime;

Here, startTime is in second.

playCAF() and playCAFFromCertainTime() can play both WAV and MP3 audio file. In case of WAV, it is played without conversion. In case of MP3, it is converted to PCM format first, and then played.

To play WAF audio file, use playWAV().

- (bool) playWAV:(NSString*)wavPath;

The following example shows how to play a WAV file stored in the application bundle.

nsWavPath = NSBundle.mainBundle().bundlePath.stringByAppendingPathComponent(songTitle)

HKWControlHandler.sharedInstance().playWAV(nsWavPath)

You can check the playback status anytime, that is, before and after as well as in the middle of the playback. You can get the player status by calling getPlayerState(). (HKPlayerState is defined in HKWControlHandler.h)

- (HKPlayerState)getPlayerState;

If you just want to check if the player is playing audio now, then use isPlaying().

- (bool) isPlaying;

Play Web Streaming Music¶

Use playStreamingMedia() to playt a streaming media. It uses a parameter of streamingMediaUrl to specify the URL of the media file in the streaming service. It starts with a protocol name, such as “http://” or “rtps://”. Currently, http:, rtps:, and mms: are supported. The supported file format is mp3, m4a, wav.

completedCallback is a callback that returns the result of the call, that is, if the call is successful or not. If it cannot find the media file on the server or some other errors occur, then it return false.

- (void)playStreamingMedia:(NSString *)streamingMediaUrl withCallback:(void (^)(bool result))completedCallback;

- (void) stop;

HKWControlHandler.sharedInstance().stop()

- (void) pause;

HKWControlHandler.sharedInstance().pause()

Volume Control¶

You can set volumes in two ways – one is set volume for an individual speaker, and the other is set volume for all speakers with the same volume level. The volume level ranges from 0 (mute) to 50 (max).

- (void) setVolume:(NSInteger)volume;

// set volume level to 25 to all speakers
var volume  = 25
HKWControlHandler.sharedInstance().setVolume(volume)

- (void) setVolumeDevice:(long long)deviceId volume:(NSInteger)volume;

// set volume level to 25 to a speaker
var volume  = 25
HKWControlHandler.sharedInstance().setVolumeDevice(deviceId volume:volume)

- (NSInteger) getVolume;

var averageVolume = HKWControlHandler.sharedInstance().getVolume()

Change speaker name¶

Use setDeviceName() to change the speaker name.

- (void) setDeviceName:(long long)deviceId deviceName:(NSString *)deviceName;

For example,

HKWControlHandler.sharedInstance().setDeviceName(deviceId, deviceName:”My Omni10”)

Set the group for a speaker¶

To set a group for a speaker (in other words, to join a speaker to a group), use setDeviceGroupName() as below:

- (void) setDeviceGroupName:(long long)deviceId groupName:(NSString *)groupName;

For example,

HKWControlHandler.sharedInstance().setDeviceGroupName(deviceId, groupName:”Living Room”)

Remove a speaker from a group¶

Use removeDeviceFromGroup() to remove the speaker from the currently belonged group. After being removed from a group, the name of group of the speaker is set to harman, which is a default group name implying that the speaker does not belong to any group.

- (void)removeDeviceFromGroup:(long long)deviceId;

For example,

HKWControlHandler.sharedInstance().removeDeviceFromGroup(deviceId)

HKWDeviceEventHandlerDelegate¶

hkwDeviceStateUpdated (required)

This function is invoked when some of device information have been changed on a particular speaker. The information being monitored incudes device status (active or inactive), model name, group name, and wifi signal strengths, etc. The parameter reason specifies what the update is about. The reason code is defined in HKWControlHandler.h.

Note that volume level change does not trigger this call. The volume update is reported by hkwVolumeLevelChanged() callback.

-(void) hkwDeviceStateUpdated:(long long)deviceId withReason:(NSInteger) reason;

This callback is essential to retrieve and update the speaker information in timely manner. If your app has a screen that shows a list of speakers available in the network with latest information, you can receive the event via this function and update the list.

A most common usage for this function is to invole tableView.reloadData() to update the list of speakers in a table view controller, as shown below.

func hkwDeviceStateUpdated(deviceId: CLongLong, withReason reason:Int) {
        self.tableView.reloadData()
}

hkwErrorOccured (required)

This function is invoked when an error occurs during the execution. The callback returns the error code, and also corresponding error message for detailed description. The error codes are defined in HKWCOntrolHandler.h.

-(void) hkwErrorOccurred:(NSInteger)errorCode withErrorMessage:(NSString*)errorMesg;

A most common usage of this function is to show an alert dialog to notice the user of the error.

-(void)hkwPlayEnded;

-(void)hkwDeviceVolumeChanged:(long long)deviceId deviceVolume:(NSInteger)deviceVolume withAverageVolume:(NSInteger)avgVolume;

-(void)hkwPlaybackStateChanged:(NSInteger)playState;

-(void)hkwPlaybackTimeChanged:(NSInteger)timeElapsed;

class SpeakerListViewController: UIViewController, UITableViewDataSource,
        SpeakerTableCellDelegate, HKWDeviceEventHandlerDelegate  {
        ... ...
}

HKDeviceEventHandlerSingleton.sharedInstance().delegate = self

HKWDeviceEventHandlerSingleton.sharedInstance().delegate

HKWPlayerEventHandlerSingleton.sharedInstance().delegate

override func viewDidAppear(animated: Bool) {
        HKWDeviceEventHandlerSingleton.sharedInstance().delegate = self
        HKWPlayerEventHandlerSingleton.sharedInstance().delegate = self

        ...

}

Overall Configuration¶

There are two types of entities in HKWirelessHD audio streaming - one is source device and the other is destination device. Source device sends audio stream to destination devices (speakers), and destination devices receive the audio stream from source and play it. In HKWirelessHD audio, audio streaming is in a one-to-many way. That is, there is one single source device sending an audio stream, and multiple destination devices receive the audio stream by synchronizing with other speakers.

In case of multi-channel streaming, each speaker is assigned with a role to process a dedicated audio channel. For example, a speaker can play either left channel or right channel in stereo mode.

Source device can be iOS device, such as iPhone and iPad, and destination devices are Harman Kardon Omni speakers (Omni Adapt, Omni 10, Omni 20, Omni Bar, etc.) You can find more information on HK Omni speakers at http://www.harmankardon.com/content?ContentID=omni-v2.

Use of HKWirelessHD API to stream audio to Omni Speakers¶

To send audio stream to destination devices, an App has to use HKWirelessHD API. HKWirelessHD SDK provides the library of the APIs for arm32/64bit architecture.

Note that as of date of writing, no x86 architecture is supported, so developer cannot use iOS Simulator for running the app with HKWirelessHD API.

Communication channels between source and destinations¶

As shown in the figure above, there are two kind of communications between a source device and (multiple) destination devices.

• Channel for audio streaming - one way communication from a source to multiple destinations

  • This channel is used for transmitting audio data to destination speakers

• Channel for control commands and device status - bidirectional communication

  • This channel is used to send commands from the source to the destinations to control the device, like volume control, etc.

  • Destination device can also send commands to the source device in some cases.

    • For example, a speaker which is not belonging to the current playback session can send a command to the source to add itself to the current playback session.
    • User can add Omni 10 or Omni 20 speaker to the current running playback session by long-pressing the Home button on the control panel. Please refer to Omni 10 or 20 User’s Manual for more information.

  • This channel is also used to send the device information and the status data of a destination speakers to the source device.

    • Device information includes the speaker name, the group name, IP address and port number, firmware version, etc.
    • Device status information includes the status about the device availability and changes of its attributes, whether or not it is playing music, Wi-Fi signal strength, volume change, etc.

Asynchronous Communication¶

The communication between the source device and the destination speakers are accomplished in asynchronous way. Asynchronous behavior is natural because all the commands and status updates are executed in a way like RPC (Remote Procedure Call). Even more, audio streaming always involves some amount of buffering of audio data packets, so the timing gap between the source and the destinations is inevitable.

Below are some examples of asynchronous communications.

• Device availability

  • When a speaker is turned on, the availability of the speaker is reflected to the source device a few second later. This is because several steps are involved to be attached the network and become discoverable by other speakers in the same network. Likewise, if a speaker is turned off or disconnected from the network, its unavailability is reflected to the source device a few second later.

• Playback control

  • When the source device starts music playback and streaming to destination speakers, actual playback in destination speakers occurs a few hundreds milliseconds later. Similar things occur when the source pauses or stops the current audio streaming, although stop or pause requires much less time.

• Volume Control

  • When the source changes the volume level of speakers, actual volume changes occur a few millisecond later.

Speaker Management¶

Whenever a speaker updates its status, the latest status information should be updated on the source device side as well. HKWirelessHD API manages the latest device status information inside DeviceInfo instances. HKWControlHandler instance maintains a list of DeviceInfo objects, each of which corresponds to a speaker found in the network.

The detailed description on each attribute in the device are described in DeviceInfo.h.

Controlling speakers¶

Speaker controls, like start/pause/resume/stop audio streaming, change volume level, etc. are done by calling APIs provided by the HKWControlHandler singleton object. The app just needs to acquire the HKWControlHandler object, initialize it, and then use it to control the speakers. For example, as shown in the figure above, the app can call playCAF() with the HKWControlHandler to start to play a CAF audio file. The control APIs are described in HKWControlHandler.h.

HKWControlHandler is a singleton object, and it can be acquired by calling as below. Note that there is no initializer API for the object. The sharedInstance() singleton API will create and initialize it if there is no instance in the runtime.

HKWControlHandler.sharedInstance()

Handling events from speakers¶

On the other hand, the events from speakers are sent to the app through Delegate protocol APIs. By implementing the event handler delegate functions (in ViewController class in most cases), you can receive and handle the events from speakers. Whenever an event occurs from speakers, the corresponding handler is called and the event information is passed to the handler as parameter.

The SDK provides two delegate protocols:

• HKWDeviceEventHandlerDelegate (defined in HKWDeviceEventHandlerSingleton.h)

  • All the events related to the status of speakers. There are two cases the event is sent:

    • device status updated
    • error occurred

  • To register an object as the delegate, do as below (self is the object that implements the delegate protocols):

    • HKWDeviceEventHandlerSingleton.sharedInstance().delete = self

• HKWPlayerEventHandlerDelegate (defined in HKWPlayerEventHandlerSingleton.h)

  • All the events related to play music.

    • play ended
    • playback state changed
    • playback time changed
    • volume changed

  • To register an object as the delegate, do as below (self is the object that implements the delegate protocols):

    • HKWPlayerEventHandlerSingleton.sharedInstance().delete = self

initializeHKWirelessController()¶

Initializes and starts HKWirelessHD controller. This API requires a boolean parameter that specifies if all the speakers in the network will be added right after initialzation. If it is true, then all speakers will be added to session, so you can play music without adding speakers. If it is false, none of speakers will be added to playback session, so you need to add speakers separately to session to play music.

This API also requires a license key as string. If the input license key fails in key validation, then the API returns -1. If it is successful, return 0.

The license key will be delivered to you once you sign on to developer.harman.com. Until it is delivered, you may use the license key included in the sample apps.

Signature:

- (NSInteger) initializeHKWirelessController:(NSString*)licenseKey withSpeakersAdded:(BOOL)withSpeakersAdded;

Parameters:

• (NSString*) licenseKey - a string containing the license key
• (BOOL) withSpeakersAdded - boolean value specifying if all speakers are added to session after initialization

Returns:

NSInteger - an integer indicating success (0 or HKW_INIT_SUCCESS) or failure (-1 or HKW_INIT_FAILURE_LICENSE_INVALID)

isInitialized()¶

Checks if HKWirelessHD controller is already initialied.

Signature:

- (BOOL) isInitialized;

Returns:

BOOL - boolean value indicating if HKWirelessController has been initialized or not.

initializing()¶

Checks if HKWirelessHD controller is being initialied.

Signature:

- (BOOL) initializing;

Returns:

BOOL - boolean value indicating if HKWirelessController is being initialized

refreshDeviceInfoOnce()¶

Refreshes the device status one time. The device information will be refreshed and updated to DeviceInfo objects (defined in DeviceInfo.h). If there is any update on DeviceInfo, then hkwDeviceStateUpdated delegate function defined by HKWDeviceEventHandlerDelegate will be called. From there, you can see which device has been updated and what was the reason of the update.

Signature:

- (void) refreshDeviceInfoOnce;

Returns:

void

startRefreshDeviceInfo()¶

Starts to keep refreshing DeviceInfo every two seconds. It continues until stopRefreshDeviceInfo() is called.

Signature:

- (void) startRefreshDeviceInfo;

Returns:

void

stopRefreshDeviceInfo()¶

Stops refreshing DeviceInfo, which was initiated by startRefreshDeviceInfo().

Signature:

- (void) stopRefreshDeviceInfo;

Returns:

void

playCAF()¶

Plays a CAF audio file in local storage. If it is successful, hkwPlaybackStateChanged() delegate function will called and return the status value of HKPlayerState.EPlayerState_Play.

The playback uses Apple Core Audio framework. So, the types of supported audio files and data formats by HKWirelessHDSDK are the same as those supported by Apple’s Core Audio framework. The detailed information is available at iOS audio file formats. According to the Apple developer documentation, CAF supports AIFF (.aif, .aiff), CAF (.caf), MPEG-1, Layer 3 (.mp3), MPEG-2 or MPEG-4 ADTS (.aac), MPEG-4 Audio (.mp4, .m4a), and WAVE (.wav).

Signature:

- (BOOL) playCAF:(NSURL *)assetURL songName:(NSString*)songName resumeFlag:(BOOL)resumeFlag;

Parameters:

• (NSURL*) assetURL - NSURL to the audio file
• (NSString*) songName - the song name to be played. The songName is used internally to save the temporary PCM file generated from the original audio file.
• (BOOL) resumeFlag - a boolean specifying if the playback should resume from the point where it was paused in the previous playback. When you want to start a song from the beginning, resumeFlag must be false. If the previous playback was stopped not paused, then the playback will start from the beginning even with resumeFlag true.

Returns:

BOOL - boolean value indicating success or failure

playCAFFromCertainTime()¶

Plays a CAF audio file beginning from a certain time of playback specified by startTime. For example, you can start a song from the point of 10 seconds of the song. hwkPlaybackStateChanged() delegate function will be called and return the status value of HKPlayerState.EPlayerState_Play.

Signature:

- (BOOL) playCAFFromCertainTime:(NSURL *)assetURL songName:(NSString*)songName startTime:(NSInteger)startTime;

Parameters:

• (NSURL *)assetURL - NSURL to the audio file.
• (NSString*)songName - the song name to be played. The songName is used internally to save the temporary PCM file generated from the original audio file.
• (NSInteger)startTime - time in second that specifies the start time.

Returns:

BOOL - boolean value indicating success or failure

playWAV()¶

Plays a WAV file. hkwPlaybackStateChanged delegate function will be called and return the status value of HKPlayerState.EPlayerState_Play.

Signature:

- (BOOL) playWAV:(NSString*)wavPath;

Returns:

BOOL - boolean value indicating success or failure

playStreamingMedia()¶

Plays a streaming media from web server. Because this API takes a little while to get the result of play because of all networking stuffs, the API just returns immediately, and instead it takes a callback to be called when the result is ready. You should take the result of the call inside of the callback.

Signature:

- (void)playStreamingMedia:(NSString *)streamingMediaUrl withCallback:(void (^)(bool result))completedCallback;

Parameters:

• (NSString*)streamingMediaUrl - a string that specifies the URL of the streaming media source. It starts with a protocol name, such as “http://” or “rtps://”. Currently, http, rtps, and mms are supported. The supported file format is mp3, m4a, and wav.
• (void (^)(bool result))completedCallback - a callback that returns the result of the playback

Returns:

void

pause()¶

Pauses the current playback. hkwPlaybackStateChanged() delegate function will be called and return the status value of HKPlayerState.EPlayerState_Pause. Once the playback is paused, it can resume by calling playCAF() with resumeFlag true and the same songName. A playback by playStreamingMedia() cannot be paused. If pause() is called, then the playback will stop.

Signature:

- (void) pause;

Returns:

void

stop()¶

Stops the current playback. hkwPlaybackStateChanged() delegate function will be called and return the status value of HKPlayerState.EPlayerState_Stop.

Signature:

- (void) stop;

Returns:

void

isPlaying()¶

Checks if the player is playing some audio or not.

Signature:

- (bool) isPlaying;

Returns:

BOOL - boolean value indicating if the player is playing or now.

getPlayerState()¶

Gets the current state of playback.

Signature:

- (HKPlayerState)getPlayerState;

Returns:

HKPlayState - indicates the current player state.

setVolume()¶

Sets a volume level to all speakers. The same volume level is set to all speakers.

The range of volume level is 0 to the maximumVolumeLevel (currently, 50) defined by getMaximumVolumeLevel().

Setting volume is asynchronous call. So, the effect of the API call will occur after a few milliseconds. The hkwDeviceVolumeChanged() delegate function defined in HKWPlayerEventHandlerDelegate (in HKWPlayerEventHandlerSingleton.h) will be called when the volume level of the specified speaker has actually changed.

If the volume is being muted by calling mute(), the volume level is changed from the original volume level before mute.

Signature:

- (void) setVolume:(NSInteger)volume;

Parameters:

• (NSInteger)volume - the volume level to set

Returns:

void

setVolumeDevice()¶

Set a volume level to a speaker specified by device ID. The range of volume level is 0 to the maximumVolumeLevel (currently, 50) defined by getMaximumVolumeLevel(). setVolume is asynchronous call. So, the effect of the API call will occur after a few milliseconds. The hkwDeviceVolumeChanged() delegate function defined in HKWPlayerEventHandlerDelegate (in HKWPlayerEventHandlerSingleton.h) will be called when the volume level of the specified speaker has actually changed.

If the volume is being muted by calling mute(), the volume level is changed from the original volume level before mute.

Signature:

- (void) setVolumeDevice:(long long)deviceId volume:(NSInteger)volume;

Parameters:

• (long long)deviceId - the device ID of the speaker
• (NSInteger)volume - the volume level to set

Returns:

void

getVolume()¶

Gets the average volume level for all devices.

Signature:

- (NSInteger) getVolume;

Returns:

NSInteger - the average volume level of all speakers

getDeviceVolume()¶

Gets the volume level of the specified speaker.

Signature:

- (NSInteger) getDeviceVolume:(long long)deviceId;

Parameters: - (long long)deviceId - the deviceId of the speaker inquired.

Returns:

NSInteger - the device volume level

getMaximumVolumeLevel()¶

Returns the maximum volume level that the system provides. Currently, it is 50.

Signature:

- (NSInteger) getMaximumVolumeLevel;

Returns:

NSInteger - the maximum volume level

mute()¶

Mutes the current volume of all speakers.

Signature:

- (void) mute;

Returns:

void

unmute()¶

Unmute the volume. It returns the previous volume level before mute.

Signature:

- (void) unmute;

Returns:

void

isMuted()¶

Check if volume is muted or not.

Signature:

- (bool) isMuted;

Returns:

BOOL - the Boolean value indicating if mute is on or not.

addDeviceToSession()¶

Adds a speaker to the current playback session. The added speaker will start playing audio. This can be done during the audio playback.

Signature:

- (BOOL) addDeviceToSession:(long long) deviceid;

Parameters:

• (long long)deviceId - The ID of the device to add

Returns:

BOOL - boolean value indicating whether the addition is successful or not.

removeDeviceFromSession()¶

Removes a speaker from the current playback session. The removed speaker will stop playing audio. This can be done during the audio playback.

Signature:

- (BOOL) removeDeviceFromSession:(long long) deviceid;

Parameters:

• (long long)deviceId - The ID of the device to remove

Returns:

BOOL - boolean value indicating whether the removal is successful or not.

getDeviceCount()¶

Gets the number of all speakers in the HKWirelessHD network.

Signature:

- (NSInteger) getDeviceCount;

Returns:

NSInteger - the number of speakers.

getGroupCount()¶

Gets the number of the groups of speakers.

Signature:

- (NSInteger) getGroupCount;

Returns:

NSInteger - the number of the groups

getDeviceCountInGroupIndex()¶

Gets the number of the speakers that belongs to a group specified by the index.

Signature:

- (NSInteger) getDeviceCountInGroupIndex:(NSInteger)groupIndex;

Parameters:

• (NSInteger)groupIndex - the index of the group looking for. It starts from 0 to (GroupCount-1).

Returns:

NSInteger - the number of speakers

getDeviceInfoByGroupIndexAndDeviceIndex()¶

Returns the DeviceInfo object (defined in DeviceInfo.h) pointed by groupIndex and deviceIndex. This API is useful to find a DeviceInfo that will be shown in a TableViewCell. For example, to show a speaker information in two section TableView, the groupIndex can correspond to the section number, and deviceIndex can correspond to the row number.

Signature:

- (DeviceInfo *) getDeviceInfoByGroupIndexAndDeviceIndex:(NSInteger) groupIndex deviceIndex:(NSInteger)deviceIndex;

Parameters:

• (NSInteger)groupIndex - The index of the group where the speaker belongs to.
• (NSInteger)deviceIndex - The index of the speaker in the group.

Returns:

DeviceInfo* - the DeviceInfo object

getDeviceInfoByIndex()¶

Returns the DeviceInfo object pointed by deviceIndex from the table containing all speakers. The range of deviceIndex will be 0 to (deviceCount - 1).

Signature:

- (DeviceInfo *) getDeviceInfoByIndex:(NSInteger)deviceIndex;

Parameters: - (NSInteger)deviceIndex - The index of the device from the table with all devices.

Returns:

DeviceInfo* - the DeviceInfo object

getDeviceGroupByDeviceId()¶

Returns the object of the DeviceGroup that a speaker belongs to.

Signature:

- (DeviceGroup *)getDeviceGroupByDeviceId:(long long)deviceId;

Parameters:

– (long long) - the ID of the speaker that belongs to a DeviceGroup

Returns:

DeviceGroup* - the DeviceGroup object

getDeviceInfoById()¶

Finds a DeviceInfo from the table by device Id. It is useful to retrieve DeviceInfo with a particular deviceId.

Signature:

- (DeviceInfo *) getDeviceInfoById:(long long) deviceId;

Parameters:

• (long long)deviceId - the ID of the device we are looking for.

Returns:

DeviceInfo* - The DeviceInfo object

isDeviceAvailable()¶

Checks whether the specified speaker is available on the network or not.

Signature:

- (BOOL) isDeviceAvailable:(long long)deviceId;

Parameters: - (long long)deviceId - The ID of the speaker

Returns:

(BOOL) - boolean indicating if the speaker is available or not.

isDeviceActive()¶

Checks whether the speaker is active (added to the current playback session) or not.

Signature:

- (BOOL) isDeviceActive:(long long)deviceId;

Parameters: - (long long)deviceId - The ID of the speaker

Returns:

(BOOL) - boolean indicating if the speaker is active or not.

removeDeviceFromGroup()¶

Removes (ungroup) the specified speaker from the currently belonged group. It is done internally by setting the GroupName as “harman” (which is factory default device name, and implies Not-Assigned.).

Signature:

- (void)removeDeviceFromGroup:(long long)deviceId;

Parameters: - (long long)deviceId - The ID of the speaker to ungroup.

Returns:

void

getDeviceGroupByIndex()¶

Gets the DeviceGroup object by index.

Signature:

- (DeviceGroup *)getDeviceGroupByIndex:(NSInteger)groupIndex;

Parameters:

• (NSInteger)groupIndex - the index of the group

Returns:

DeviceGroup* - The object of DeviceGroup

getDeviceGroupByGroupId()¶

Gets DeviceGroup by group ID.

Signature:

- (DeviceGroup *)getDeviceGroupByGroupId:(long long)groupId;

Parameters:

• (long long)groupId - the ID of the group

Returns:

DeviceGroup* - the object of device group.

getDeviceGroupNameByIndex()¶

Gets the name of the DeviceGroup by index.

Signature:

- (NSString *)getDeviceGroupNameByIndex:(NSInteger)groupIndex;

Parameters:

• (NSInteger)groupIndex - the index of the group in the group table.

Returns:

NSString* - the string of group name

getDeviceGroupIdByIndex()¶

Gets the ID of the DeviceGroup by index.

Signature:

- (long long)getDeviceGroupIdByIndex:(NSInteger)groupIndex;

Parameters:

• (NSInteger)groupIndex - the index of the group in the table

Returns:

long long - the group id

setDeviceName()¶

Sets device name to a speaker. Note that you cannot set the device name by setting “deviceName” property directly. The property is read-only.

Signature:

- (void) setDeviceName:(long long)deviceId deviceName:(NSString *)deviceName;

Parameters:

• (NSInteger)deviceId - The ID of the device
• (NSString*)deviceName - The name of the device to set

Returns:

void

setDeviceGroupName()¶

Sets device group to a speaker with Group name. Note that you cannot set the group name by setting “groupName” property directly. The property is read-only.

Signature:

- (void) setDeviceGroupName:(long long)deviceId groupName:(NSString *)groupName;

Parameters:

• (NSInteger)deviceId - The ID of the device
• (NSString*)groupName - The name of the group name to set

Returns:

void

setDeviceRole()¶

Sets the role for the speaker. The role information is used to define which part of audio channel the speaker takes for the playback.

Signature:

- (void)setDeviceRole:(long long)deviceId role:(int)role;

Parameters:

• (long long)deviceId - The id of the device
• (int)role - the interger value indicating the role of the speaker. The possible options are listed in the HKRole enumeration type. The default value is EMono (21).

Returns:

void

getActiveDeviceCount()¶

Gets the number of active speakers (the speakers that are being added to the current playback session.)

Signature:

- (NSInteger) getActiveDeviceCount;

Returns:

NSInteger - the number of active devices

getActiveGroupCount()¶

Gets the number of active groups. An active group is defined as a group that all the speakers that belongs to a group are active. If even one of the speakers in the same group is inactive, then the group is inactive.

Signature:

- (NSInteger) getActiveGroupCount;

Returns:

NSInteger - the number of active groups

refreshDeviceWiFiSignal()¶

Refreshes the device’s Wifi Signal strength value. This is asynchronous call, and the result of refreshing will come a few milliseconds later. The new WiFi signal strength value will be reported by hkwDeviceStateUpdated() delegate function defined in HKWDeviceEventHandlerDelegate (in HKWDeviceEventHandlerSingleton.h). In hkwDeviceStateUpdated(), you should get the wifi signal value by getting wifiSignalStrength attribute of DeviceInfo object.

Signature:

- (void)refreshDeviceWiFiSignal:(long long)deviceId;

Parameters:

• (long long)deviceId - The ID of the device

Returns:

void

getWifiSignalStrengthType()¶

Gets Wifi signal strength type by signal value.

Signature:

- (HKWifiSingalStrength)getWifiSignalStrengthType:(NSInteger)wifiSignal;

Parameters:

• (NSInteger)wifiSignal - the wifi signal value

Returns:

HKWifiSingalStrength - a value of HKWifiSignalStrength type

sharedInstance()¶

Returns the singleton object to HKWDeviceEventHandler.

Signature: +(HKWDeviceEventHandlerSingleton*)sharedInstance;

delegate¶

The delegate attribute to be set by an object to be a HKWDeviceEventHandlerDelegate.

@property (nonatomic, weak) id<HKWDeviceEventHandlerDelegate> delegate;

hkwDeviceStateUpdated() - required¶

Invoked when some of device information have been changed for any speakers.It is also invoked when the network is disconnected ans no speakers are available any longer, or when the network becomes up from down, so speakers in the network become added to the HKWirelessHD network. <p>The information monitored includes device status (active or inactive), model name, group name, and wifi signal strengths.<p>Volume change does not trigger this call. The volume update is reported by CallbackVolumeLevelChanged.

Signature:

-(void)hkwDeviceStateUpdated:(long long)deviceId withReason:(NSInteger)reason;

Parameters:

• (long long)deviceId - the deviceId of the speaker
• (NSInteger)reason - the reason code about the updated status

Returns:

void

hkwErrorOccurred() - required¶

Invoked when an error occures.

Signature:

-(void)hkwErrorOccurred:(NSInteger)errorCode withErrorMessage:(NSString*)errorMesg;

Parameters:

• (NSInteger)errorCode - an integer value indicating error code.
• (NSString*)errorMesg - a string value containing a description about the error.

Returns:

void

sharedInstance()¶

Returns the singleton object to HKWPlayerEventHandler.

Signature:

+(HKWPlayerEventHandlerSingleton*)sharedInstance;

delegate¶

The delegate attribute to be set by an object to be a HKWPlayerEventHandlerDelegate.

@property (nonatomic, weak) id<HKWPlayerEventHandlerDelegate> delegate;

hkwPlayEnded() - required¶

This is called when the current playback has ended.

Signature:

-(void)hkwPlayEnded;

hkwDeviceVolumeChanged() - optional¶

This is called when volume level has changed for any spekaers.

Signature:

-(void)hkwDeviceVolumeChanged:(long long)deviceId deviceVolume:(NSInteger)deviceVolume withAverageVolume:(NSInteger)avgVolume;

Parameters:

• (long long)deviceId - the device unique ID (long long type)
• (NSInteger)deviceVolume - the volume level of the device (speaker)
• (NSInteger)avgVolume - the average volume level

hkwPlaybackStateChanged() - optional¶

This is called when player state has changed during the playback.

Signature:

-(void)hkwPlaybackStateChanged:(NSInteger)playState;

Parameters:

• (NSInteger)playState - The player state

hkwPlaybackTimeChanged() - optional¶

This is called when the current time of playback has changed. It is called every one second.

Signature:

-(void)hkwPlaybackTimeChanged:(NSInteger)timeElapsed;

Parameters:

• (NSInteger)timeElapsed - the time (in second) passed since the beginning of the playback.

Use Cases¶

HKWHub App¶

Web Hub handles all the requests from and response to smart devices, sensors or clouds to control audio playback with wireless speakers in the house.

Usage¶

• User may place an iOS device on the cradle and run WebHub app. Then the app acts as Web Hub. (A stationary device in a house lik AppleTV can be a nice iOS device for WebHub.)

Overall Architecture¶

HKWHub App handles requests from and sends responses to sensors, smart devices or cloud-based services to control audio playback with wireless speakers in the house.

The latest version of HKWHub app supports the following three modes:

• Cloud mode (HKIoTCloud)

  • HKWHub app communicates with HKIoTCloud to receive speaker control commands by REST API call from 3rd party services or clients.
  • HKIoTCloud handles the REST API request from any clients in the Internet. The clients can be 3rd party apps or services or devices like smartphone or sensors.
  • In this mode, any 3rd party services or clients in the Internet can reach out to HKWHub app and then control speakers and playback of audio.
  • All the 3rd party apps or services should be authorized with OAuth2 to get access token. An access token is required when 3rd party apps call the REST APIs. The detailed information about OAuth2 is available at this link.

• Local Server Mode

  • HKWHub app lauches a web server internally, and then handles the REST API requests for speaker control and playback from devices, sensors or applications in the same local network.
  • HKWHub app opens a HTTP port in the local network, so if devices or services outside of the local network want to reach out to HKWHub (and then speakers) then user needs to configure the route so that a request coming from outside can be routed to HKWHub app accordingly, such as firewall, etc.

• PubNub Cloud mode

  • HKWHub app uses PubNub API/SDK to connect to PubNub server and communicate with it to receive commands from other PubNub clients, and also sends events to other PubNub client, through a common PubNub channel.
  • By setting the same PubNub channel, any client devices or services can communicate with the HKWHub app, and then control speakers and playback of audio.

The following figure shows how HKWHub app handles three modes.

Overview of HKWHubApp¶

Main Screen¶

The main screen is composed of two parts - Select Server mode (amonng HKIoTCloud, Local Server and PubNub Cloud), and Settings.

The Select Server mode has three options:

• Connect to HK IoT Cloud

  • HKWHub app connects to HKIotCloud, and communicate with it with WebSocket to receive REST API commands from and send the responses back to the Cloud.

• Run Local Web Server

  • HKWHub app runs a local web server and processes incoming REST requests to control speakers and playback of audio

• Connect to PubNub Cloud

  • HKWHub app uses PubNub APIs to connect PubNub server and communicate with other PubNub client through a common channel.

The Settings menu has four sub menus:

• Media List

  • User can maintain the list of audio files for audio playback.
  • User can add audio from iOS Media Library.

  Note

  Note that only the media file available offline and not from Apple Musica can be added. The music file that came from Apple Music cannot be added by DRM issue.

  

• Set API Keys

  • To use PubNub mode, user needs to enter PubNub API keys. It requires Publish Key and Subscribe Key. And also, user needs to set the channel where it exchanges the command and events with other clients.
  • If user (or developer) wants to use TTS APIs such as play_tts, then user needs to enter VoiceRSS (http://www.voicerss.org) API keys. You can get a free API key.

  

• Speaker List

  • You can see the list of speakers available in the current local network.
  • You can also change the device name or group name from this screen.

  

• About

  • The information of the app and the links to Harman developer documentation site.

From now on, we will explain a little more detail about each server mode.

HKIoTCloud Mode¶

Connecting to HKIoTCloud¶

In HKIoTCloud demo, 3rd party clients can connect to HKIoTCloud (http://hkiotcloud.herokuapp.com) and send REST requests to control speakers and play audio. In order to use HKIoTCloud mode, user needs to sign up to the cloud with username, emaill address and password. Once sign up is done, user need to sign in to the server. User sign-up and sign-in can be done within the HKWHub app, as shown below.

Once the HKWHub app successfully signs in to HKIoTCloud, the screen will be switched to Log screen, like shown as below. You can see all the message logs received from or sent to the cloud. Each log contains a JSON data, so you can see what information is being sent and received between the server.

If you want to disconnect the server and return to the main screen, press Disconnect button on the top righthand corner.

Sending REST Requests to HKIoTCloud¶

Once the HKWHub App is running, you can now connect a client to HKIoTCloud and send REST requests to the server. We will explain about the REST APIs supported with a little more detailed example of curl commands in the next section.

Note

For a client to connect to HKIoTCloud, the same username and password are required.

As an example of client, HKIoTCloud hosts a Web-based client app, at http://hkiotcloud.herokuapp.com/webapp/. The following is a screenshot of the web app.

Once user authentication is done successfully, the Web app will switch the screen to the Playlist screen.

Now, you can click one of the titles in the list, and see how the web app is playing the title, showing the information of the title, volume, and playback time, and so on.

If you click Speaker List menu on the left, you can see more detailed information of speakers like below, and can control speakers, like remove a speaker from the current playback session or add a speaker to playback.

Local Server Mode¶

Running Local Server¶

Loca Server Mode is almost the same as HKIoTCloud, except that HKWHub app runs a web server inside, instead connecting to HKIoTCloud. Therefore, HKWHub app can receive REST requests directly from clients in the same network. If you want to connect speakers from any type of devices in the same local network, then Local Server mode can be easier solution.

Once you click Run Local Web Server menu, then you will see the following screen. From the screen, you can see a URL indicating where a client should connect to. In this example, the client should enter the URL http://10.0.1.37:8080/ followed by REST command and parameters.

The RESI APIs are almost the same as the ones of HKIoTCloud mode.

Sending REST Requests to LocalServer¶

As a sample client app, you can use WebHubWebApp that you can download from Harman Developer web site (http://developer.harman.com) or direclty from here. The Web app is created using Polymer v0.5 (https://www.polymer-project.org/0.5/).

Once you download the app, unzip it. You will see the following sub directories.

• bower_components: THis is the folder where polymer libraries are located.
• hkwhub: this is the folder containing the WebHubApp source code.

$ cd WebHubWebApp
$ python -m SimpleHTTPServer

You will get some log messages like “Serving HTTP on 0.0.0.0 port 8000 ...”

Next, launch your web browser (Chrome, Safari, ...) and go to http://localhost:8000/hkwhub/

Note

Your iOS device running HKWHub app and your Desktop PC running web browser should be in the same network.

At the fist screen looking like this:

Enter the URL that the HKWHub app says: http://10.0.1.37:8080/, like this:

If you press Submit, then you will see the first screen like below. This is the list of media items available at the HKWHub app.

The UI of the Web app is exactly the same as HKIoTCloud web app. So, we skip to explain the rest parts of the app.

PubNub Server Mode¶

Connect to PubNub Server¶

With PubNub server mode, any PubNub client can connect to and control Omni speakes managed by HKWHub app. Just click Connect to PubNub Cloud menu in the main screen, then you will see the screen like below. Please check if the logs are saysing something like “Received: Hello from HKWHubApp” which is the message sent back from PubNub server after the HKWHub app published the message. This means the app is now connected to PubNub cloud.

Differently from HKIoTCloud or Local Server mode that relies on REST API for control and playback of speakers, PubNub is using Publish/Subscribe messaging instead. And in order to route the message among clients, we should set PubNub Channel so that all the published messages are correctly routed to subscribed clients of the same channel.

So, for HKWHub app successfully connects to PubNub cloud, user needs to set PubNub Publish Key, Subscribe Key, and Channel. As explained already, user can set these keys in the Settings/Set API Keys menu in the main screen.

Sample Web App¶

As a sample client app, you can use WebHubPubNubApp that you can download from Harman Developer web site (http://developer.harman.com) or directly from here.. Likewise, The Web app is created using Polymer v0.5 (https://www.polymer-project.org/0.5/).

Once you download the app, unzip it. You will see the following sub directories.

• bower_components: THis is the folder where polymer libraries are located.
• hkwhub: this is the folder containing the WebHubApp source code.

$ cd WebHubPubNubApp
$ python -m SimpleHTTPServer

You will get some log messages like “Serving HTTP on 0.0.0.0 port 8000 ...”

Next, launch your web browser (Chrome, Safari, ...) and go to http://localhost:8000/hkwhub/

Note

Your iOS device running HKWHub app and your Desktop PC running web browser should be in the same network.

At the fist screen looking like below. Note that it looks different from the screen from Local Server mode, which requires only URL of the web server.

Enter the same PubNub publish key, subscribe key, and channel name that you used for HKWHub app, and click Submit, as below.

https://chrome.google.com/webstore/detail/postman/fhbjgbiflinjbdggehcddcbncdddomop/related?hl=en

If you press Submit, then you will see the first screen like below. This is the list of media items available at the HKWHub app.

The UI of the Web app is exactly the same as HKIoTCloud web app. So, we skip to explain the rest parts of the app.

Use curl command to send REST requests¶

We show how to control Omni speakers by sending REST requests to HKIoTCloud. Sending REST requests to Local Server is almost the same.

You can use curl command in your shell to send REST requests.

If you are a chrome browser user, you can use Postman (https://chrome.google.com/webstore/detail/postman/fhbjgbiflinjbdggehcddcbncdddomop/related?hl=en) chrome extension to send HTTP requests with browser-based UI.

{"token_type":"bearer",
 "access_token":"15c0507f3a550d7a31f7af5dc45e4dd9fd9f4bc8",
 "expires_in":3600,
 "refresh_token":"1b470edc539681803de95c919bc3779acdf34e01"}

{"ResponseOf":"init_session","SessionToken":"r:abciKaTbUgdpQFuvYtgMm0FRh"}

{"Result":"true","ResponseOf":"set_party_mode"}

{"DeviceList":[
        {
                "IsPlaying":false,
                "MacAddress":"",
                "GroupName":"Garage",
                "Role":21,
                "Version":"0.1.6.2",
                "Port":44055,
                "Active":true,
                "GroupID":"4625984469",
                "ModelName":"Omni Adapt",
                "DeviceID":"4625984469168",
                "IPAddress":"10.0.1.6",
                "Volume":17,
                "DeviceName":"Adapt",
                "WifiSignalStrength":-62
        },
        {
                "IsPlaying":false,
                "MacAddress":"b0:38:29:11:19:54",
                "GroupName":"Living Room",
                "Role":21,
                "Version":"0.1.6.2",
                "Port":44055,
                "Active":true,
                "GroupID":"9246663882",
                "ModelName":"Omni 10",
                "DeviceID":"92466638829744",
                "IPAddress":"10.0.1.9",
                "Volume":17,
                "DeviceName":"Omni Left",
                "WifiSignalStrength":-67
        }
],
"ResponseOf":"device_list"
}

{"Result":"true","ResponseOf":"add_device_to_session"}

{"MediaList": [
        {"PersistentID":"7387446959931482519",
        "Title":"I Will Run To You",
        "Artist":"Hillsong",
        "Duration":436,
        "AlbumTitle":"Simply Worship"
        },
        {"PersistentID":"5829171347867182746",
        "Title":"I'm Yours [ORIGINAL DEMO]",
        "Artist":"Jason Mraz",
        "Duration":257,
        "AlbumTitle":"Wordplay [SINGLE EP]"}
]}

{"Result":"true","ResponseOf":"play_hub_media"}

{"Result":"true","ResponseOf":"play_hub_media_selected_speakers"}

{"Result":"true","ResponseOf":"play_web_media_party_mode"}

{"Result":"true","ResponseOf":"stop_play"}

{"Result":"true","ResponseOf":"set_volume"}

Playback Session Creation¶

• When a client wants to start a playback, it sets the priority of the session (using Priority=<priority value> parameter).
• If Priority parameter is not specified, HKWHub app assumes it as default value, that is, 100.

Priority of Session¶

• Each session is associated with a priority value which will be used to determine which request can override the current on-going playback session.

• The priority value is specified as parameter (Priority) when the client calls play_xxx.

  • If the command does not specify the Priority parameter, 100 is set as default value.

• If the priority of a new playback request, such as play_hub_media or play_web_media, and so on, is greater than or equal to the priority of the current playback session, then it interrupts the current playback session, that is, stops the current playback session and start a new playback for itself.

  • The playback status of the interrupted session becomes PlayerStateStopped. (see the related API in the next section)

The following diagrams show how HKWHub app handles incoming playback request based on the session priorities.

Session Timeout¶

• A session becomes expired and invalid when about 60 minutes is passed since the last command was received.
• Session timer is extended (renewed) once a playback is executed successfully.
• All requests with expired session will be denied and “SessionNotFound” error returns.

Session Management¶

Device Management¶

Media Playback Management¶

Volume Control¶

Introduction¶

In order to access the HKIoTCloud REST APIs to control Omni speakers, your HKIoTCloud-enabled product needs to obtain a HKIoTCloud access token that grans access to the APIs on behalf of the product’s user.

The workflow for obtaining and using an access token is as follows:

1. The user visits your product registration website and enters information about their specific instance of your product.
2. Your website creates a HKIoTCloud consent request using the user-supplied registration information and forwards the user to the HKIoTCloud website.
3. The user logs in to HKIoTCloud.
4. The user authorizes their instance of your product to be used with HKIoTCloud on their behalf.
5. HKIoTCloud returns an access token to your product registration website.
6. Your product registration website securely transfers the access token to the user’s specifi instance of your product.
7. The user’s speific instance of your product uses the access token to make HKIoTCloud API calls.

Types of Authorization¶

HKIoTCloud supports two types of authorization:

• Authorization Code Grant - Send a client ID and a client secret to get an access token and a refresh token.
• Password Grant - Send username and password along with client ID and client secret to get an access token and refresh token

Using the Password Grant Type¶

To obtain an access token (and a refresh token) with password grant, you should POST to /oauth/token. You should include your client ID and client secret in the Authorization header by combining them with a colon ”:” and then encoding in Base64. That is, Base64(client_id:client_secret). And also, you should include grant_type: password, username and passworkd in the request body.

Sample Request:

POST /oauth/token HTTP/1.1
Host: hkiotcloud.herokuapp.com
Authorization: Basic RkZjUE9iS2h4OThvNXhtMzpjcENZQ1BrUjA4NXFSR3hFempDMUlGeEoxQWRhZFQ=
Content-Type: application/x-www-form-urlencoded

grant_type=password&username=johndoe&password=A3ddj3w

Here, RkZjUE9iS2h4OThvNXhtMzpjcENZQ1BrUjA4NXFSR3hFempDMUlGeEoxQWRhZFQ= is the result of Base64 encoding of clientId:clientSecret.

Sample Response:

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache

{
   "access_token":"62b8c11cfa0840b506230cb8af747230052775e1",
   "token_type":"bearer",
   "expires_in":3600,
   "refresh_token":"7a7687b6b32247573b366d5bf2eeb707ba0a1b4d"
 }

Creating a Consent Request¶

By creating a consent request, your user will be redirected to the HKIoTCloud website where they can enter their HKIoTCloud credentials in order to authorize their devices of your product to be used with the HKIoTCloud service.

The consent request is constructed as follows:

• Redirect the user to HKIoTCloud at https://hkiotcloud.herokuapp.com/oauth/token with the following URL-encoded query parameters:

  • client_id : The client ID of your application. This information can be found on the HKIoTCloud website.
  • response_type: code for authorization code grant.
  • redirect_uri : Specifies the return URI that you added to your app’s profile when signing up.

Sample Request:

Send as GET request.

https://hkiotcloud.herokuapp.com/oauth/authorize?response_type=code&client_id=n7HhiTnKYjJd4zmM&redirect_uri=https://your.app.com/oauthCallbackHKIoTCloud

HKIoTCloud Returns a Response to Your Registration Website¶

After the user is authenticated, the user is redirected to the URI that you provided in the redirect_uri parameter of the request.

The response includes an authorization code.

Sample Authorizatino Code Grant Response:

https://your.app.com/oauthCallbackHKIoTCloud?code=0b368d49809048dd7424d6f7fd869a98f2372859

Next, your service leverages the returned authorization code to ask for an access token:

• Send a POST request to https://hkiotcloud.herokuapp.com/oauth/token with the following parameters:

HTTP Header Parameters:

• Content-Type: application/x-www-form-urlencoded

HTTP Body Parameters:

• grant_type: authorization_code
• code : The authorization code that was returned in the response.
• client_id : Your application’s client ID. This information can be found on the HKIoTCloud website.
• client_secret : The application’s client secret. This information can be found on the HKIoTCloud website.
• redirect_uri : The return URI that you added to your app’s profile when signing up.

Sample Request:

POST /oauth/token HTTP/1.1
Host: hkiotcloud.herokuapp.com
Content-Type: application/x-www-form-urlencoded
Cache-Control: no-cache

grant_type=authorization_code&code=2b3711911f4f2263e785eeda386046ccc8da6aee&client_id=n7HhiTnKYjJd4zmM&client_secret=ANRfB9z94xtcxFGXrd5XHXEiKg43UY&redirect_uri=https://hkvoicecloud.herokuapp.com/oauthCallbackHKIoTCloud

Sample Response:

{
        "access_token": "902da699ed1d5d511bd750366889f3260c2015b4",
        "expires_in": 3600,
        "refresh_token": "5defcb0a9a49ac9b2403b8c78600638238d81011",
        "token_type": "bearer"
}

Transfer the access and refresh tokens to the user’s product.

Using the Access Token to Make HKIoTCloud API Calls¶

When you call the HKIoTCloud API calls, pass the value of the access token into the request header. Specifically, create an Authorization header and give it the value Bearer <access token>.

Sample Request using curl:

• curl -X GET -H “Authorization: Bearer 15c0507f3a550d7a31f7af5dc45e4dd9fd9f4bc8” http://hkiotcloud.herokuapp.com/api/v1/init_session

Getting a New Access Token with Refresh Token¶

The access token is valid for one hour. When the access token expires or is about to expire, you can exchange the refresh token for new access and refresh tokens.

• Send a POST request to https://hkiotcloud.herokuapp.com/oauth/token with the following parameters:

HTTP Header Parameters:

• Content-Type: application/x-www-form-urlencoded

HTTP Body Parameters:

• grant_type: refresh_token
• refresh_token : The refresh token returned with the last request for a new access token.
• client_id : Your application’s client ID. This information can be found on the HKIoTCloud website.
• client_secret : The application’s client secret. This information can be found on the HKIoTCloud website.

Sample Request:

POST /oauth/token HTTP/1.1
Host: hkiotcloud.herukuapp.com
Content-Type: application/x-www-form-urlencoded
Cache-Control: no-cache

grant_type=refresh_token&refresh_token=5defcb0a9a49ac9b2403b8c78600638238d81011&client_id=n7HhiTnKYjJd4zmM&client_secret=ANRfB9z94xtcxFGXrd5XHXEiKg43UY

Sample Response:

HTTP/1.1 200 OK

{
        "access_token": "90da03bdceb15cf75d99ff99715ce87b29602651",
        "expires_in": 3600,
        "refresh_token": "6a762dfce9146dbf149f881c5aa15fc6cfdf1fd0",
        "token_type": "bearer"
}