Smart Config Application development information - Android

From Texas Instruments Wiki
Jump to: navigation, search

Overview

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

This application is the configuring side in the process of connecting a 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 as the package available for download above (SmartConfigCC3X\libs\smartconfiglib.jar).

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 application example, and complete a full Smart config process before continuing any further.

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 a CC3000 device to connect to a specific network.

In order to perform the above, SSID and IP address of the designated network are required.

The application sends configuration packet to the CC3000 device according to the network characteristic (IP, SSID, security type).

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

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

The application retrieves the SSID and IP gateway (see example application source code) according to network the Android device is currently connected to and using this information to configure the remote device.

In addition, if provided by the user, security key and encryption key are needed in order to build the configuration packets.

The application will continue sending the configuration packets until an acknowledgment packete will be 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:

Android Flow.PNG
 


Using the SmartConfig library

In order to use the library it is necessary to import it to the project.

The library exports the FirstTimeConfig class.

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

 1.  Extend the interface FirstTimeConfigListener by one of the classes in the app
 2.  Retrieve SSID and IP address
 3.  Create a FirstTimeConfig object by using one of the constructors, and pass a listener object to it
 4.  Call transmitSettings(), which opens a new library thread and returns immediately

At this point one of the following could happen:

  •  The App decides to stop the smartConfig, so it calls stopTransmitting.

     When this method returns, the library thread has already been stopped by the library itself, so no further transmission is occurring.

  •  ACK is received, so the library calls the listener's FtcEvent method with FTC_SUCCESS parameter, within the library thread.

    The library thread also stops transmitting, and the thread is stopped.

  • The defined timeout is reached, so the library calls the listener's FtcEvent method with FTC_TIMEOUT parameter, within the library thread.

    The library thread also stops transmitting, and the thread is stopped.

  • An error occurs. The library calls the listener's FtcEvent method with FTC_ERROR parameter, within the library thread.

    The library thread also stops transmitting, and the thread is stopped.


Please Note:

  • onFirstTimeConfigEvent() should be implemented in order to handle each one of the events: FTC_SUCCESS, FTC_TIMEOUT or FTC_ERROR. (See example code).
  • It is advised to construct a new object if the app wants to transmit again.


First Time Config Class

Constructors

The FirstTimeConfig is the main constructor of the class. It enables the caller to customize most aspects of the protocol. It is offered with different options, in order to provide flexibility.

  • The simplest call needs at least a listener, the wifi key, an encryption key, the destination IP, and the SSID of the network.
  • In addition to these parameters, the caller can set additional parameters such as an acknowledgement, the listening port, the local port, socket ackownledgement timeout, etc...

Refer to the options mentioned below, for the API which suits your needs.

FirstTimeConfig

This method is a constructor of the class.

In case of a failure the method throws java.lang.Exception.

/* *listener - A listener object, whose class derives from FirstTimeConfigListener. May be null but highly discouraged.*/ /* *Key - The Wi-Fi key which you wish to configure */ /* *EncryptionKey - A key used by the protocol to encrypt the Wi-Fi key. (Must be shared with the target device) */ /* *Ip - Destination IP address of packets. This should be the IP address of the Wi-Fi access point or router */ /* *Ssid - The Wi-Fi network name which you wish to configure */

FirstTimeConfig(FirstTimeConfigListener listener, java.lang.String Key, byte[] EncryptionKey, java.lang.String Ip, java.lang.String Ssid);


FirstTimeConfig

This method is a constructor of the class. It should be called in case ackstring is set to other than the default.

In case of a failure the method throws java.lang.Exception.

/* *listener - A listener object, whose class derives from FirstTimeConfigListener. May be null but highly discouraged.*/ /* *Key - The Wi-Fi key which you wish to configure */ /* *EncryptionKey - A key used by the protocol to encrypt the Wi-Fi key. (Must be shared with the target device) */ /* *Ip - Destination IP address of packets. This should be the IP address of the Wi-Fi access point or router */ /* *Ssid - The Wi-Fi network name which you wish to configure */ /* *ackString - The acknowledgment string which the target device is expected to send (over mDNS) after successful configuration (default "CC3000", must match the target device settings) */

FirstTimeConfig(FirstTimeConfigListener listener, java.lang.String Key, byte[] EncryptionKey, java.lang.String Ip, java.lang.String Ssid, java.lang.String ackString);  


FirstTimeConfig

This method is a constructor of the class. It should be called in case one of the following is set to other than the default: ackstring, notifyListenPort.

In case of a failure the method throws java.lang.Exception.


/* *listener - A listener object, whose class derives from FirstTimeConfigListener. May be null but highly discouraged.*/ /* *Key - The Wi-Fi key which you wish to configure */ /* *EncryptionKey - A key used by the protocol to encrypt the Wi-Fi key. (Must be shared with the target device) */ /* *Ip - Destination IP address of packets. This should be the IP address of the Wi-Fi access point or router */ /* *Ssid - The Wi-Fi network name which you wish to configure */ /* *ackString - The acknowledgment string which the target device is expected to send (over mDNS) after successful configuration (default "CC3000", must match the target device settings) */ /* *notifyListenPort - The UDP port over which the mDNS acknowledgment is supposed to be sent by the target device (default 5353, must match the target device settings) */

FirstTimeConfig(FirstTimeConfigListener listener, java.lang.String Key, byte[] EncryptionKey, java.lang.String Ip, java.lang.String Ssid, java.lang.String ackString, int notifyListenPort);



FirstTimeConfig

This method is a constructor of the class. It should be called in case one of the following is set to other than the default: ackstring, notifyListenPort,localPort.

In case of a failure the method throws java.lang.Exception.

/* *listener - A listener object, whose class derives from FirstTimeConfigListener. May be null but highly discouraged.*/ /* *Key - The Wi-Fi key which you wish to configure */ /* *EncryptionKey - A key used by the protocol to encrypt the Wi-Fi key. (Must be shared with the target device) */ /* *Ip - Destination IP address of packets. This should be the IP address of the Wi-Fi access point or router */ /* *Ssid - The Wi-Fi network name which you wish to configure */ /* *ackString - The acknowledgment string which the target device is expected to send (over mDNS) after successful configuration (default "CC3000", must match the target device settings) */ /* *notifyListenPort - The UDP port over which the mDNS acknowledgment is supposed to be sent by the target device (default 5353, must match the target device settings) */ /* *localPort - The UDP port over which the first-time configuration packets are transmitted (default 15000, must match the target device settings) */

FirstTimeConfig(FirstTimeConfigListener listener, java.lang.String Key, byte[] EncryptionKey, java.lang.String Ip, java.lang.String Ssid, java.lang.String ackString, int notifyListenPort, int localPort);

 


FirstTimeConfig

This method is a constructor of the class. It should be called in case one of the following is set to other than the default: ackstring, notifyListenPort, localPort, WaitForAckSocketTimeout.

In case of a failure the method throws java.lang.Exception.

/* *listener - A listener object, whose class derives from FirstTimeConfigListener. May be null but highly discouraged.*/ /* *Key - The Wi-Fi key which you wish to configure */ /* *EncryptionKey - A key used by the protocol to encrypt the Wi-Fi key. (Must be shared with the target device) */ /* *Ip - Destination IP address of packets. This should be the IP address of the Wi-Fi access point or router */ /* *Ssid - The Wi-Fi network name which you wish to configure */ /* *ackString - The acknowledgment string which the target device is expected to send (over mDNS) after successful configuration (default "CC3000", must match the target device settings) */ /* *notifyListenPort - The UDP port over which the mDNS acknowledgment is supposed to be sent by the target device (default 5353, must match the target device settings) */ /* *localPort - The UDP port over which the first-time configuration packets are transmitted (default 15000, must match the target device settings) */ /* *WaitForAckSocketTimeout - The maximum time, in milliseconds, to wait for acknowledgment of successful configuration (default 5 minutes) */

FirstTimeConfig(FirstTimeConfigListener listener, java.lang.String Key, byte[] EncryptionKey, java.lang.String Ip, java.lang.String Ssid, java.lang.String ackString, int notifyListenPort, int localPort, int WaitForAckSocketTimeout)  


FirstTimeConfig

This method is the full size constructor of the class which enables the caller to customize most aspects of the protocol, to match the settings of the target device.

All other constructors call this one, and pass various sets of default values as parameters.

In case of a failure the method throws java.lang.Exception.

/* *listener - A listener object, whose class derives from FirstTimeConfigListener. May be null but highly discouraged.*/ /* *Key - The Wi-Fi key which you wish to configure */ /* *EncryptionKey - A key used by the protocol to encrypt the Wi-Fi key. (Must be shared with the target device) */ /* *Ip - Destination IP address of packets. This should be the IP address of the Wi-Fi access point or router */ /* *Ssid - The Wi-Fi network name which you wish to configure */ /* *ackString - The acknowledgment string which the target device is expected to send (over mDNS) after successful configuration (default "CC3000", must match the target device settings) */ /* *notifyListenPort - The UDP port over which the mDNS acknowledgment is supposed to be sent by the target device (default 5353, must match the target device settings) */ /* *localPort - The UDP port over which the first-time configuration packets are transmitted (default 15000, must match the target device settings) */ /* *WaitForAckSocketTimeout - The maximum time, in milliseconds, to wait for acknowledgment of successful configuration (default 5 minutes) */ /* *numberOfSetups - The amount of times to repeat the setup packets between each sync sequence (default 4) */ /* *numberOfSyncs - The amount of sync packet sequences between each setup sequence (default 10) */ /* *syncL - The data for "low" sync packets within a sync sequence. (default "abc") – Content is not relevant as long as the length is 3. In any case, this value should not be set by user. */ /* *syncH - The data for "high" sync packets within a sync sequence (default "abcdefghijklmnopqrstuvw") Content is not relevant as long as the length is 23. In any case, this value should not be set by user. */


FirstTimeConfig(FirstTimeConfigListener listener, java.lang.String Key, byte[] EncryptionKey, java.lang.String Ip,

java.lang.String Ssid, java.lang.String ackString, int notifyListenPort, int LocalPort, int WaitForAckSocketTimeout,
int numberOfSetups, int numberOfSyncs, java.lang.String syncL, java.lang.String syncH);  





Class API

transmitSettings

This method begins the transmission of the configuration packets.

In case of a failure the method throws java.lang.Exception.
 

void transmitSettings();

stopTransmitting

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

In case of a failure the method throws java.lang.Exception.
void stopTransmitting();