The Particle Device Setup library is meant for integrating the initial setup process of Particle devices in your app. This library will enable you to easily invoke a standalone setup wizard UI for setting up internet-connected products powered by a Particle device (Photon, P0, P1). The setup UI can be easily customized by a customization proxy class, that includes: look & feel, colors, texts and fonts as well as custom brand logos and custom instructional video for your product. There are good defaults in place if you don’t set these properties, but you can override the look and feel as needed to suit the rest of your app.
The wireless setup process for the Photon uses very different underlying technology from the Core. Where the Core used TI SmartConfig, the Photon uses what we call “soft AP” — i.e.: the Photon advertises a Wi-Fi network, you join that network from your mobile app to exchange credentials, and then the Photon connects using the Wi-Fi credentials you supplied.
With the Device Setup library, you make one simple call from your app, for example when the user hits a “Setup my device” button, and a whole series of screens then guide the user through the setup process. When the process finishes, the app user is back on the screen where she hit the “setup my device” button, and your code has been passed an instance of the device she just setup and claimed.
Rebranding notice
Spark has been recently rebranded as Particle.
Code currently contains SparkSetup keyword as classes prefixes. this will soon be replaced with ParticleDeviceSetup. A new Cocoapod library will be published and current one will be depracated and point to the new one. This should not bother or affect your code in any way.
Official documentation can be found in Particle docs website.
Import SparkSetup.h in your view controller implementation file, and invoke the device setup wizard by:
Objective-C
SparkSetupMainController *setupController = [[SparkSetupMainController alloc] init];
setupController.delegate = self; // why? see "Advanced" section below
[self presentViewController:setupController animated:YES completion:nil];Swift
if let setupController = SparkSetupMainController()
{
setupController.delegate = self
self.presentViewController(setupController, animated: true, completion: nil)
}Alternatively if your app requires separation between the Particle cloud authentication process and the device setup process you can call:
Objective-C
SparkSetupMainController *setupController = [[SparkSetupMainController alloc] initWithAuthenticationOnly:YES];
[self presentViewController:setupController animated:YES completion:nil];Swift
if let setupController = SparkSetupMainController(authenticationOnly: true)
{
self.presentViewController(setupController, animated: true, completion: nil)
}This will invoke Particle Cloud authentication (login/signup/password recovery screens) only after user has successfully logged in or signed up, control will be returned to the calling app. If an active user session already exists control will be returned immediately.
Customize setup look and feel by accessing the SparkSetupCustomization singleton appearance proxy [SparkSetupCustomization sharedInstance]
and modify its default properties. Setting the properties in this class is optional. (Replace NSString with String for Swift projects)
NSString *deviceName; // Device/product name
NSString *brandName; // Your brand name
UIImage *brandImage; // Your brand logo to fit in header of setup wizard screens
UIColor *brandImageBackgroundColor; // brand logo background color
NSString *instructionalVideoFilename; // Instructional video shown when "show me how" button pressed
NSString *appName; // Your setup app name NSString *modeButtonName; // The mode button name on your product
NSString *listenModeLEDColorName; // The color of the LED when product is in listen mode
NSString *networkNamePrefix; // The SSID prefix of the Soft AP Wi-Fi network of your product while in listen mode NSURL *termsOfServiceLinkURL; // URL for terms of service of the app/device usage
NSURL *privacyPolicyLinkURL; // URL for privacy policy of the app/device usage
NSURL *forgotPasswordLinkURL; // URL for user password reset (non-organization setup app only)
NSURL *troubleshootingLinkURL; // URL for troubleshooting text of the app/device usage
NSString *termsOfServiceHTMLFile; // Static HTML file for terms of service of the app/device usage
NSString *privacyPolicyHTMLFile; // Static HTML file for privacy policy of the app/device usage
NSString *forgotPasswordHTMLFile; // Static HTML file for user password reset (non-organization setup app only)
NSString *troubleshootingHTMLFile; // Static HTML file for troubleshooting text of the app/device usage UIColor *pageBackgroundColor; // setup screens background color
UIImage *pageBackgroundImage; // optional background image for setup screens
UIColor *normalTextColor; // normal text color
UIColor *linkTextColor; // link text color (will be underlined)
UIColor *elementBackgroundColor; // Buttons/spinners background color
UIColor *elementTextColor; // Buttons text color
NSString *normalTextFontName; // Customize setup font - include OTF/TTF file in project
NSString *boldTextFontName; // Customize setup font - include OTF/TTF file in project
CGFloat fontSizeOffset; // Set offset of font size so small/big fonts can be fine-adjusted
BOOL tintSetupImages; // This will tint the checkmark/warning/wifi symbols in the setup process to match text color (useful for dark backgrounds) BOOL organization; // enable organization mode - activation codes, other organizational APIs
NSString *organizationName; // organization nameYou can get an active instance of SparkDevice by making your viewcontroller conform to protocol <SparkSetupMainControllerDelegate> when setup wizard completes:
-(void)sparkSetupViewController:(SparkSetupMainController *)controller didFinishWithResult:(SparkSetupMainControllerResult)result device:(SparkDevice *)device;func sparkSetupViewController(controller: SparkSetupMainController!, didFinishWithResult result: SparkSetupMainControllerResult, device: SparkDevice!);method will be called, if (result == SparkSetupMainControllerResultSuccess) or (or simply (result == .Success) in Swift) the device parameter will contain an active SparkDevice instance you can interact with
using the iOS Cloud SDK.
To use Particle Device Setup library from within Swift based projects read here, also be sure the check out Apple documentation on this matter.
Usage example app (in Swift) can be found here. Example app demonstates - invoking the setup wizard, customizing its UI and using the returned SparkDevice instance once setup wizard completes (delegate). Feel free to contribute to the example by submitting pull requests.
Check out the Reference in Cocoadocs website or consult the javadoc style comments in SparkSetupCustomization.h and SparkSetupMainController.h for each public method or property.
If the Device Setup library installation completed successfully - you should be able to press Esc to get an auto-complete hints from XCode for each public method or property in the library.
- iOS 8.0 and up supported
- Currently setup wizard displays on portait mode only.
- XCode 6.0 and up is required
Particle Device Setup library is available through CocoaPods under the pod name SparkSetup.
To install it, simply add the following line to your Podfile:
pod "SparkSetup"- If you need help, use Our community website
- If you found a bug, and can provide steps to reliably reproduce it, open an issue.
- If you have a feature request, open an issue.
- If you want to contribute, submit a pull request.
Particle Device Setup library is available under the Apache license 2.0. See the LICENSE file for more info.