English / 日本語

Aroma Shooter SDK (iOS)

The iOS version of AromaShooterController SDK which is used to communicate with Aroma Shooter devices.

v2.0.0 is a breaking release. The diffuse* methods are renamed to shoot*, the CartridgePort model becomes AromaChamber (intensityPercent → concentration), and the booster/fan parameters become internalBooster/externalBooster. See the CHANGELOG.

Table of Contents

1. Supported devices
2. Prerequisites
3. Installation
4. Usage
   • Connect/Disconnect devices
   • Get connected devices
   • Shoot scents
   • Stop shooting
5. License

Supported devices

• Aroma Shooter Bluetooth version

Prerequisites

• iOS version: >= 12.0
• Swift version: >= 5.0

Installation

• Download the AromaShooterSwiftSDK.xcframework at the release page.
• Drag and drop it into your project, then set it to Embed & Sign under your target's General → Frameworks, Libraries, and Embedded Content.

Watch a video walkthrough of this process to simplify your life.

Usage

Add Bluetooth usage description to Info.plist file

From iOS 13 and later, it is required to add the Bluetooth usage description, if not the app will be crashed. So, please add the key and its value to the app's Info.plist file.

<key>NSBluetoothAlwaysUsageDescription</key>
<string>The app uses Bluetooth to connect to Aroma Shooter</string>

Besides, if you get the "Target Integrity" in XCode 12.3, please check out the solution here.

Get Controller references

• Import Controller module

import AromaShooterSwiftSDK

• Get the Controller class reference

var controller = AromaShooterController.sharedInstance

Connect/disconnect devices

We have done the connection UI part for you. You can easily open the connection view controller by one of two ways. if you are using NavigationController, please use these codes.

let connectionVC = controller.getConnectionViewController()
if let connectionVC = connectionVC {
  self.navigationController?.pushViewController(connectionVC, animated: true)
}

In other cases, you can use the below codes.

let connectionVC = controller.getConnectionViewController()
if let connectionVC = connectionVC {
  self.present(connectionVC, animated: true, completion: nil)
}

Manual connection (custom UI)

If you build your own device list instead of the built-in screen, drive the scan/connect flow directly and receive results through AromaShooterDelegate.

class MyManager: AromaShooterDelegate {
  let controller = AromaShooterController.sharedInstance

  init() { controller.delegate = self }

  func startDiscovery() { controller.startScanning() }
  func stopDiscovery()  { controller.stopScanning() }

  // AromaShooterDelegate
  func aromaShooter(didDiscoverDevice device: AromaShooter) { /* add to your list */ }
  func aromaShooter(didConnectDevice device: AromaShooter) { /* update UI */ }
  func aromaShooter(didDisconnectDevice device: AromaShooter) { /* update UI */ }
}

// Connect / disconnect discovered devices
controller.connect(aromaShooters: [device])
controller.disconnect(aromaShooter: device)

Get connected devices

let connectedDevices = controller.connectedDevices

Shoot scents

Note: the internal booster must be enabled for any scent to emit — pass internalBooster: true (simple) or internalBoosterIntensity > 0 (with intensity). If it is off, nothing comes out. The external booster (externalBoosterIntensity, formerly "fan") exists on AS3 only.

Simple mode (AS1 / AS2) — chambers on/off, no per-chamber intensity:

// All connected devices, multiple chambers
controller.shootAllSimple(duration: 3000, internalBooster: true, chambers: [1, 2, 3])

// Specific devices, multiple chambers
controller.shootSimple(aromaShooters: devices, duration: 3000, internalBooster: true, chambers: [1, 2, 3])

// A single chamber (one device, or several)
controller.shootSimple(aromaShooter: device, duration: 3000, internalBooster: true, chamber: 1)
controller.shootSimple(aromaShooters: devices, duration: 3000, internalBooster: true, chamber: 1)

// One device, multiple chambers
controller.shootSimple(aromaShooter: device, duration: 3000, internalBooster: true, chambers: [1, 2])

Intensity mode (AS2 / AS3) — per-chamber concentration + internal/external booster (external booster is AS3 only):

// All connected devices
controller.shootAllWithIntensity(durationInMilli: 1000, internalBoosterIntensity: 50, externalBoosterIntensity: 50, chambers: [AromaChamber(number: 3, concentration: 100)])

// Specific devices
controller.shootWithIntensity(aromaShooters: controller.connectedDevices, durationInMilli: 1000, internalBoosterIntensity: 50, externalBoosterIntensity: 40, chambers: [AromaChamber(number: 3, concentration: 100)])

Stop shooting

Stop all chambers of the connected devices while they are shooting.

// Simple mode — all devices / a specific device
controller.stopAllSimple()
controller.stopSimple(aromaShooter: device)

// Intensity mode (AS2 / AS3) — all devices / a specific device
controller.stopAllWithIntensity()
controller.stopWithIntensity(aromaShooter: device)

For more information, please checkout this repository and refer to the sample project.
If you get any issues or require any new features, please create a new issue.

License

Please check the LICENSE file for the details.