Smart Config Application development information - IOS

From Texas Instruments Wiki
Jump to: navigation, search

Overview

TI provides Smart Config example application for IOS devices which is available for download from the Apple App Store.

TI provides also the Smart Config example application for IOS devices source code which is available for download from here.

  • Please Note that the Application source code download is available only for MAC, and not for PC.

This application is the configurable side in the process of connecting CC3000 device to a specific AP using the Smart Config feature.

This application uses specific API from a binary library file which is available as part of the source code above (CC3x\libFTC_RELEASE.a  and CC3x\FirstTimeConfig.h)

In order to develop similar application for your product, please use the following sections in this wiki page to understand which are the APIs provided and the correct way to use them.


It is highly recommended to use the Smart Config example application and perform a full Smart config process before continuing.

For further details regarding the Smart Config process please refer to our Smart Config wiki page.



Application Description

Smart Config Application is used in order to configure CC3000 device to connect to a specific network.

In order to perform the above, the SSID and security key of the designated network are required.

The application sends configuration packets according to the network characteristic (SSID, security type and key).

The application can send the configuration packets with or without AES encryption.

The IOS device has to be connected to the same network that the CC3000 is about to connect to.

The class retrieves the SSID and gateway IP of the network that the IOS device is currently connected to and using this information to configure the remote device. The security key for the network is entered by the user.

In addition, if provided by the user, an encryption key is used in order to build the configuration packets.

The application will continue sending the configuration packets until an acknowledge is received from the CC3000 device.

  • Please note that MTU must be set to 1500.

Please use the following flow chart in order to understand the application operation:

IOS APP FLOW.PNG
 


Using the SmartConfig library

In order to use the library it is necessary to add it to the dependencies of the IOS project.

It supports projects that are built for IOS >= 4.1

The library exports the FirstTimeConfig class.

In order to use the FirstTimeConfig class you just need to:

  1. Create an instance of the FirstTimeConfig

  2. Call the transmitConfig method (start sending configuration packets)

  3. Run the waitForAck method from a thread that is different from the main thread (wait for ack from CC3000 device)


At any time while the library is transmitting you can call the stopTransmitting method in order to stop it.

In that case the waitForAck method that waits for an acknowledgment from the remote device will return false.


First Time Config Class

Constructors

Init

This method is the regular constructor of the class. It should be called in case the network is set with no security.
In case of a failure the method throws an OSFailureException.
- (id)init;


initWithKey

This method is a constructor of the class. It should be called in case the network is set with security and it receives one argument which is the network security passphrase.

If this method is called with an empty string ("") as an argument then it will behave the same as the Init method. </span>

In case of a failure the method throws an OSFailureException.</span>

/*Key - The WiFi security key for the specified AP*/
- (id)initWithKey:(NSString *)Key

initWithKey

This method is a constructor of the class. It should be called in case the network is set with security and supports AES encryption of the SmartConfig packets.

It receives two arguments which are the security key and encryption key.

In case of a failure the method throws an OSFailureException.


/* Key - The WiFi security key for the specified AP*/
/* encryptionKey - The SmartConfig AES encryption key. Must be a 16-characters string*/
 
(id)initWithKey:(NSString *)Key withEncryptionKey:(NSData *)encryptionKey;<br>


initWithData

This method is a constructor of the class. This is a lower-level function which gives more flexibility at the cost of complexity.

The last 5 parameters allow modifying various low-level parameters of the protocol, and should be set to the defaults in all cases.
/*delayInMicroSeconds:(useconds_t)uDelay*/
/*Ip - The IP address of the AP, to which the android device is currently connected, even if configuring a different SSID*/
/*Ssid - The SSID to use for smartConfig*/
/* Key - The network security key*/
/*EncryptionKey - The smartConfig encryption key. This is a pre-shared key with the CC3000 device. Must be a 16-characters string*/
/*numOfSetups - Please set to 4. This is the amount of setups in the protocol sequence*/
/*numOfSyncs - Please set to 10. This is the amount of syncs in the protocol sequence*/
/*lSync1 - Please set to 3*/
/*lSync2 - Please set to 23*/
/*uDelay - Please set to 1*/
 
(id)initWithData:(NSString *)Ip withSSID:(NSString *)Ssid withKey:(NSString *)Key withEncryptionKey:(NSData *)EncryptionKey
numberOfSetups:(int)numOfSetups numberOfSyncs:(int)numOfSyncs syncLength1:(int)lSync1 syncLength2:(int)lSync2 delayInMicroSeconds:(useconds_t)uDelay;
 

Class API

transmitSettings

This method begins the transmission of the configuration packets.

In case of a failure the method throws an OSFailureException.

- (void)transmitSettings;<br>

stopTransmitting

This method stops the sending of the configuration packets to the remote device.

In case of a failure the method throws an OSFailureException.

- (void)stopTransmitting;<br>


setDeviceName

This method sets the expected name of the device. This name is used when waiting for the CC3000 device to ACK its configuration.

The function waitForAck will return TRUE when a device with this name advertises its service via mDNS. (Default "CC3000", must match the target device settings)

-(void)setDeviceName:(const NSString *)deviceName;<br>


waitForAck

This method waits for an acknowledge from the remote device. After an acknowledge has received, the transmission of the configuration packets stops.

This method blocks until it gets respond.

The method will return true if it got the acknowledge from the remote device or false if it got aborted by a call to stopTransmitting.

In case of a failure the method throws an OSFailureException.

- (bool)waitForAck;<br>


isTransmitting

This method retrieves the current status of the library. Returns true if configuration packets are currently transmitting, false if not.

-(bool)isTransmitting;<br>