isolatedwww.dm8.cc

User'sGuideSimpleLinkWi-FiCC3x20andCC3x3xProvisioningforMobileApplicationsABSTRACTThisuser'sguidedescribesTexasInstrumentsSimpleLinkWi-Fiprovisioningsolutionformobileapplications,specificallyontheusageoftheAndroidandiOSbuildingblocksforUIrequirements,networking,andprovisioningAPIsrequiredforbuildingthemobileapplication.
TermsandAbbreviationsAbbreviationorTermMeaningandExplanationAPAccessPointAPIsApplicationInterfacesBcastBroadcastHTTPHypertextTransferProtocolJSONJavascriptObjectNotationmDNSMulticastDNSSCSmartConfigUDPUserDatagramProtocolUIUserInterfaceTableofContentsTrademarks.
11Introduction.
22Top-LevelArchitecture.
43Provisioning-SmartConfig64AndroidBlockDiagram.
95Provisioning–APMode.
146iOSversusAndroidDevelopmentGuidelines.
187PortingInstructions.
198Settings.
209LoggerandEmail.
21RevisionHistory.
21TrademarksSimpleLink,SmartConfig,andTexasInstrumentsaretrademarksofTexasInstruments.
AndroidisatrademarkofGoogle,Inc.
.
Wi-FiisaregisteredtrademarkofWi-FiAlliance.
iOSisaregisteredtrademarkofCisco.
BluetoothisaregisteredtrademarkofBluetoothSIG,Inc.
Allothertrademarksarethepropertyoftheirrespectiveowners.
www.
ti.
comTableofContentsSWRU472B–FEBRUARY2017–REVISEDAUGUST2020SubmitDocumentFeedbackSimpleLinkWi-FiCC3x20andCC3x3xProvisioningforMobileApplications1Copyright2020TexasInstrumentsIncorporated1Introduction1.
1OverviewThisdocumentdescribestheTexasInstrumentsSimpleLinkWi-Fiprovisioningsolutionformobileapplications.
ThemainfocusofthisdocumentisontheusageoftheAndroidandiOSbuildingblocksforUIrequirements,networking,andprovisioningAPIsrequiredforbuildingthemobileapplication.
TheCC31xxandCC32xxdevicesarepartoftheSimpleLinkmicrocontroller(MCU)platformwhichconsistsofWi-Fi,Bluetoothlowenergy,Sub-1GHzandhostMCUs,whichallshareacommon,easy-to-usedevelopmentenvironmentwithasinglecoresoftwaredevelopmentkit(SDK)andrichtoolset.
Aone-timeintegrationoftheSimpleLinkplatformenablesyoutoaddanycombinationoftheportfolio'sdevicesintoyourdesign,allowing100percentcodereusewhenyourdesignrequirementschange.
Formoreinformation,visitwww.
ti.
com/simplelink.
ThefirststepinutilizingaCC32xx/CC31xxdeviceinaWi-Fi-enabledapplicationistoconnectthedevicetoaWi-Finetwork(accesspoint).
ThisprocessiscalledWi-Fiprovisioninganditinvolvesloadingtheinformationoftheaccesspoint(SSIDnameandsecuritycredentials)tothedevice.
ThisprocesscanbecomplexconsideringthatembeddedWi-Fiapplicationsgenerallylackuserinterfacessuchaskeypadsortouchscreens.
Introductionwww.
ti.
com2SimpleLinkWi-FiCC3x20andCC3x3xProvisioningforMobileApplicationsSWRU472B–FEBRUARY2017–REVISEDAUGUST2020SubmitDocumentFeedbackCopyright2020TexasInstrumentsIncorporatedFigure1-1illustratesageneraloverviewofthisprocedure:adevicewhichisnotconnectedtothenetwork,butexistsinthenetworkrange,canaccepttheinformationrequiredforconnectingtothenetwork,usingthecombinationoftheembeddedapplication(seeSimpleLinkWi-FiCC3x20,CC3x3xDeviceProvisioning)andthemobileapplication.
Figure1-1.
GeneralOverviewwww.
ti.
comIntroductionSWRU472B–FEBRUARY2017–REVISEDAUGUST2020SubmitDocumentFeedbackSimpleLinkWi-FiCC3x20andCC3x3xProvisioningforMobileApplications3Copyright2020TexasInstrumentsIncorporated1.
2ProvisioningMethodsWi-Fiprovisioningisusuallydoneonce,eitherwhileconnectinganewdevicetothenetworkorafteranupdateonthelocalnetworkwhichrequiresconfigurationchanges.
Aftertheprovisioning,theCC32xxdevicesavestheacceptedWi-Fiinformationasanencryptedprofile.
Usingthisprofile,theCC3xxx/CC31xxdeviceisabletoautomaticallyconnecttothenetworkwhenitisavailableasaWi-Fistation.
TherearetwomainprovisioningmethodstoconnectaCC3xxxdevicetoadesiredaccesspointusingTI'smobileapplicationforWi-Fiprovisioning,Wi-FiStarterPro:SmartConfig–UsingtheSmartConfigalgorithmeliminatestheneedtoknowtheCC32xx/CC31xxdeviceidentityaheadoftime.
Theprocessconfiguresanylisteningdevice.
Usingthismethod,theuserdoesnotneedtoknowthedevicename,oranyotherdeviceidentity.
APmode–ThemobileapplicationconnectstothedeviceasaWi-Fistation,andsendsthenetworkinformationforthedesirednetworkconnection.
Byusingthismode,theusershouldknowwhichdevicetoconnecttoaccordingtoitspublishedSSID,whilefunctioningasanAP.
TheusercanselectwhichmodetouseusingtheWi-FiStarterProapp:SmartConfigorAPmode.
Wi-FiStarterProcontainsaSettingstabforhandlingconfigurations;switchingbetweenSmartConfigandAPmodeisoneoftheoptionsonthistab.
2Top-LevelArchitecture2.
1Top-LevelBlocksFigure2-1illustratesthetop-levelarchitecture.
Figure2-1.
Top-LevelArchitectureIntroductionwww.
ti.
com4SimpleLinkWi-FiCC3x20andCC3x3xProvisioningforMobileApplicationsSWRU472B–FEBRUARY2017–REVISEDAUGUST2020SubmitDocumentFeedbackCopyright2020TexasInstrumentsIncorporated2.
2BasicProvisioningStepsTherearefourstepsforcompletingprovisioning:1.
UserInputs–Theuserprovidesinformationabouttheidentityofthenetwork.
2.
Sendingconfigurations–Themobileappsendsnetworkcredentialstothedevice.
3.
Findingthedeviceonthenetwork–Themobileappsearchesforthedevice.
Thedevicepublishesinformationsuchasservicesanddevicename,andrespondstonetworkqueries.
4.
Connectingtothedeviceandgettingfeedback–Themobileappconnectstothedeviceoverthesharednetwork,andconfirmsthatthedeviceisresponding.
2.
2.
1Step1:UserInputsThisisthefirststepoftheapplication.
ThemobilephoneshouldbeconnectedtotheWi-Finetworkbeforetheprovisioningisactivated.
Ifusingasecurednetwork,themandatoryfieldsforbothoptions(SmartConfigorAPmode)arethenetworkSSID(usuallytheactiveWi-Ficonnectionofthemobilephone)andpassword.
Ifthedevicenameisnotsettoanewvalue,thenthedefaultdevicenameisused.
2.
2.
2Step2:SendingConfigurationsThesecondstepistosendtheinformationtothenon-configureddevice,usingtheactivenetwork.
TheactivenetworkisthelinkbetweentheMobilephoneandtheRouter.
Inthiscase,themobileappsideisresponsiblefortransmittingtheinformationtothenetworkwhilethedevicelistenstotheinformationtransmitted(evenifitisasecurednetwork).
Afterverifyingthevalidityoftheinformation,thedevicecreatesandstoresaprofileofthisnetworkthatiskeptonthedevice'sstorage.
Thesavedprofileisnowactivatedandconnectedtothenetwork.
2.
2.
3Step3:FindingtheDeviceontheNetworkThethirdstepistofindtheIPaddressofthedeviceafteritisconnectedtotheWi-Finetwork,andacquireanIPaddressfromtheDHCPserver.
Themobileappusesthreeoptionsfordetectingthedeviceonthenetwork:ListeningtoUDPbroadcastpacketsfromthedevicespecifyingthenameandIPaddressListeningtoUDPmulticastpacketsfrommDNSonthenetwork,andfilteringbyservicessupportedbythedeviceSendingbroadcastpingpacketsandcatchingpingresponsepacketsfromthedevicesonthenetworkIfthenetworkisnottotallyisolated,thedevicewillbedetectedandverifiedbythemobileapplicationinoneormoreofthethreeoptionsdescribed.
2.
2.
4Step4:ConnectingtotheDeviceandGettingFeedbackThefinalstepistocheckiftheprovisioningcompletedsuccessfully.
Thisisdonebysendingaqueryfromthemobileapptothedevice,askingfortheprovisioningresults.
ThisstepisperformedassumingthedeviceIPaddressisalreadyknownfrompreviousstep,andthatthedevicesupportsHTTPrequests.
Afterthequeryissenttothedevice,thereareseveralpossibleresponsesthatcanbereceived.
Asuccessfulresponsemeansthattheprovisioningcompleted.
Incaseofatimeoutorafailure,APfallbackmodeisautomaticallysuggestedtotheuserbythemobileapplication.
2.
2.
5FallbackStep:ConfirmationFailedIfthemobileappfailedtoconnecttothedeviceandreceivefeedback,themobileappshouldconnecttothedevicedirectly.
TheappcanactasanAPincaseofaconnectionfailure,andthedeviceswitchestotheconfigurationsstageasnormal.
Inthiscase,thedeviceisconfiguredbuttheconfirmationfeedbackistransferredusingthedirectconnection.
www.
ti.
comTop-LevelArchitectureSWRU472B–FEBRUARY2017–REVISEDAUGUST2020SubmitDocumentFeedbackSimpleLinkWi-FiCC3x20andCC3x3xProvisioningforMobileApplications5Copyright2020TexasInstrumentsIncorporated3Provisioning-SmartConfig3.
1OverviewTI'sSmartConfigalgorithmsendsconnectioninformationtothedevicewithoutarealconnection.
SmartConfigisresponsibleforsendingthedata,andthenetworkingblocks(ping,UDPlistener,mDNS)areresponsibleforgettingthenewIPoftheconnecteddeviceaftertheconnection.
SmartConfigleveragesthestandardmechanismspresentinWi-FitoconfigureaCC32xx/CC31xxdevice'sassociationinformationonthefly,regardlessofwhetherauserinterfaceisavailable.
Inthisprocess,aWi-Fi-enableddevicesuchasasmartphone,tablet,oralaptopsendstheassociationinformationtotheCC32xx//CC31xxdevice.
Additionally,SmartConfigdoesnotdependontheI/Ocapabilitiesofthehostmicrocontroller,andthuscanbeusedbyembeddedapplications.
SmartConfigcanbeusedtoassociatemultipledevicestothesameAPsimultaneously.
Additionally,theconfigureddevice(suchasasmartphoneortablet)staysconnectedtotheuser'shomenetworkduringtheconfigurationprocess(asopposedtoothermethodsthatrequiredisconnection).
Provisioning-SmartConfigwww.
ti.
com6SimpleLinkWi-FiCC3x20andCC3x3xProvisioningforMobileApplicationsSWRU472B–FEBRUARY2017–REVISEDAUGUST2020SubmitDocumentFeedbackCopyright2020TexasInstrumentsIncorporated3.
2SmartConfigFlowChartFigure3-1illustratestheSmartConfigflowchart.
Figure3-1.
SmartConfigFlowChartwww.
ti.
comProvisioning-SmartConfigSWRU472B–FEBRUARY2017–REVISEDAUGUST2020SubmitDocumentFeedbackSimpleLinkWi-FiCC3x20andCC3x3xProvisioningforMobileApplications7Copyright2020TexasInstrumentsIncorporated3.
3SmartConfigSequenceFigure3-2illustratestheSmartConfigsequence.
Figure3-2.
SmartConfigSequenceProvisioning-SmartConfigwww.
ti.
com8SimpleLinkWi-FiCC3x20andCC3x3xProvisioningforMobileApplicationsSWRU472B–FEBRUARY2017–REVISEDAUGUST2020SubmitDocumentFeedbackCopyright2020TexasInstrumentsIncorporated4AndroidBlockDiagram4.
1OverviewFigure4-1illustratestheAndroidblockdiagram.
Figure4-1.
AndroidBlockDiagram4.
2SmartConfigInitializationTheSmartConfiglibrarycontainsasetofAPIstoactivateSmartConfig.
TheseAPIscovertheinitializationofSmartConfigobjects,andsetconfigurationssuchasSSID,password,andstart/stoptransmission.
Thetransmissionworksrepeatedlyuntilitisstopped.
TherepeateddatatransmissionimprovestheprobabilityforsuccessonalimitedWi-Ficoveragenetworkoronacongestedenvironment.
ActivateSmartConfigwhenthephone,theAP,andthetargetdeviceareallonthesamelocalnetwork,withnohiddendevices.
Forexample,ifthephoneisnotwithintherangeofthedevice,butboththedeviceandthephoneareintherangeoftheAP.
Thedeviceandthephonearehidden.
TheSmartConfigcommandisactivatedbythefollowingclass:www.
ti.
comAndroidBlockDiagramSWRU472B–FEBRUARY2017–REVISEDAUGUST2020SubmitDocumentFeedbackSimpleLinkWi-FiCC3x20andCC3x3xProvisioningforMobileApplications9Copyright2020TexasInstrumentsIncorporatedAndroid:classSmartConfigTable4-1.
AndroidParametersStringValueListenerAlistenerobject,whoseclassderivesfromFirstTimeConfigListenerbaseclass;canbenull.
FreeDataNullincaseofnodevicename.
Ifthedevicenameexists,thefirstbyteshouldbevalue0x3,secondbytespecifiesdevicestringlength,andtherestaredevicenamecharacters.
KeyTheWi-FikeytoconfigureEncryptionKeyAkeyusedbytheprotocoltoencrypttheWi-Fikey(mustbesharedwiththetargetdevice);canbenullStringIPDestinationIPaddressofpackets.
ThisshouldbetheIPaddressoftheWi-Fiaccesspointorrouter.
StringSsidTheWi-FinetworknametoconfigureGroupGroup–shouldbe0TokenTokenshouldbenullForexample:try{smartConfig=newSmartConfig(smartConfigListener,freeData,passwordKey,paddedEncryptionKey,gateway,SSID,(byte)0,"");}catch(SocketExceptione){Log.
e(TAG,"Failedtocreateinstanceofsmartconfig");return;}iOS:classFirstTimeConfig::initWithDataTable4-2.
iOSParametersStringValueStringIPDestinationIPaddressofpackets.
ThisshouldbetheIPaddressoftheWi-Fiaccesspointorrouter.
StringSsidTheWi-FinetworknametoconfigureFreeDataNullincaseofnodevicename.
Ifthedevicenameexists,thefirstbyteshouldbevalue0x3,secondbytespecifiesdevicestringlength,andtherestaredevicenamecharacters.
KeyTheWi-FikeytoconfigureEncryptionKeyAkeyusedbytheprotocoltoencrypttheWi-Fikey(mustbesharedwiththetargetdevice);canbenull.
numberOfSetups4numberOfSyncs10syncLength13syncLength223delayInMicroSeconds100004.
3SmartConfigTransmissionStartsSmartConfigpacketstransmission,basedontheinitvalues.
transmitSettings()Forexample:smartConfig.
transmitSettings();AndroidBlockDiagramwww.
ti.
com10SimpleLinkWi-FiCC3x20andCC3x3xProvisioningforMobileApplicationsSWRU472B–FEBRUARY2017–REVISEDAUGUST2020SubmitDocumentFeedbackCopyright2020TexasInstrumentsIncorporated4.
4StoppingSmartConfigTransmissionsSmartConfigcontinuestobroadcastnetworkcredentialsuntilstoppedbytheuser.
SmartConfigisunawareofthesuccessorfailureofthetransmission.
Therefore,itshouldbestoppedbycontrollinglayersafteroneofthefollowingscenarios:Activatedfor40sec+20secforgettingnetworkindications,butthedevicewasnotdetected.
Itisassumedthatafterthisperiodoftime,thatthedeviceisnotconnectedtothenetwork,theconfigurationiswrong,orthedeviceisnotonthecorrectmodeforprovisioning.
Thedevicewasdetectedsuccessfully,andthereisnoneedtokeepsendingthedataagainuntiltime-outexpires.
stopTransmitting()Forexample:smartConfig.
stopTransmitting();4.
5UDPListenerUDPlistenerisaUDPserverrunningonaspecificthread(AndroidUIthreadoriOSthread).
UDPlistenershouldbeactivatedasabackgroundtask,sothatitcanfindUDPbroadcastsfromthedevice,uponacquiringanIPaddressfromthenetwork.
Thedeviceshouldsendafewmessages,withdelaysbetweenthemtopublishitsIPaddressandname.
Thedataispublishedusingportnumber1501,andcontainsboththedevicenameandthedeviceIPaddress,withacommaseparationinatextualformat.
Uponsuccessfullyreceivingandparsingthedata,theUDPlistenercallbackisactivated,andthedeviceisaddedtothedevicecontainersafteritisconvertedtoJSONformat.
Forexample–startingUDPserveronAndroid:udpBcastServer=newUdpBcastServer(mCallback);4.
6mDNSListenermDNSlistenerassumesthedevice,usingitsdefaultconfigurations,supportsbothmDNSandHTTPserver.
mDNSlistenerwillbeactiveaslongnastheprovisioningprocessisngoing.
Inthiscase,uponacquiringanIPaddress,thedeviceannouncesitsservicesbyusingmulticastmessages.
HTTPisoneoftheservicestobepublishedonthenetwork.
BecausetheHTTPservicecontainssomeknowninformation,thisinformationisusedtoaddthedevicecontainingthisspecificinformationtothedevicelist.
ThetxtfieldsonthecheckedmDNSpacketshouldcontainthestring"srcvers=1D90645"toconfirmthecorrectnessofthisdevice.
IfavalidCC32xx/CC31xxdevicedetectedusingmDNS,constructaJSONmessagewiththedevicenameanditsIPaddress,andaddittothedevicecontainer.
Thedeviceinformationandcontainerareonlyexamplesofusingtheinformationandsendingitacrossmobileapplicationlayers.
Thisimplementationcanbemodifiedbythemobileprogrammer.
OnAndroid–mDNSHelperhandlesmDNSinitializationandcallbackfunctionsforacceptingandparsingincomingmDNSinformationfromthelocalnetwork.
4.
7PingTaskPingisabackgroundtask,activatedafterSmartConfigisdonetofinddevicesonthelocalnetwork.
PingisbasedonsendingabroadcastICMPECHOrequest(pingrequest)fromthedevice,andwaitingforanECHOreply(pingreply)fromdevicesonthelocalnetwork.
TheSimpleLinkdeviceisdesignedtoreplytobroadcastpingrequestsbydefault.
Uponacceptingaresponsefromthenetworkdevices,themobileapplicationfiltersonlySimpleLinkdevicesbyqueryingspecifichttpwww.
ti.
comAndroidBlockDiagramSWRU472B–FEBRUARY2017–REVISEDAUGUST2020SubmitDocumentFeedbackSimpleLinkWi-FiCC3x20andCC3x3xProvisioningforMobileApplications11Copyright2020TexasInstrumentsIncorporatedrequestandgettingthedeviceversion.
Incaseofavalidresponse,itindicatesthatthisisaSimpleLinkdevice,anditcanbeaddedtothedevicescontainerinaJSONformat.
Pingclasshandlesbothpinggeneration,acceptingpingresponses,andcreatinganHTTPrequestforvalidatingthedevicename.
4.
8HTTPRequestsforSmartConfigHTTPrequestssendorrequestinformationfromthemobileappside(HTTPclient)tothedeviceside(HTTPserver).
TherearesomeservicesusedbySmartConfig,andotherservicesusedbyAPmode.
Eachserviceusuallyhastwooptions:R1,whichisthefirstrevisionoftheSimpleLinkdevice,andsupportsdifferentAPIsthanR2.
MostHTTPAPIsrequireaninputparametertoindicateswhethertheAPIshouldactasR1orasR2.
BecauseHTTPqueriesareusuallylongandmaytaketimetocomplete(dependingonthehostspeed,interface,orlinkquality),allHTTPactionsarewrappedonanasyncthread,andshouldnotstallanyUIactivity.
4.
8.
1GetDeviceVersionTheHTTPcallisbasedonhttp://[ipaddress]/param_product_version.
txt.
ThisspecificAPIisgoodforbothR1andforR2,anditreturnsthecurrentversion.
Aftergettingversioninformation,thisinformationshouldbeusedonthenextHTTPAPIasoneoftheinputparameters.
Devicemethod:publicstaticDeviceVersiongetSLVersion(StringbaseUrl)4.
8.
2GetConfigurationsResultsThisAPIiscalledafterthedeviceisalreadyconnectedtothelocalnetwork,andthereasonsitactivatesare:Tochecktheerrorcodestoredonthedevice,fornotifyingtheuseraboutthesuccessorfailureoftheprovisioning.
Ifthedevicewaitsfor30secondsandthisrequestisnotactivatedbythemobileappside,itassumestheprovisioningisuncompleted,anditswitchestoAProleasfallback.
publicstaticStringgetCGFResultFromDevice(StringbaseUrl,DeviceVersionversion)4.
8.
3GetResponseNumberCodeThestringfetchedfromthepreviousAPI,getCGFResultFromDevice,shouldbeconvertedtoanumberbyusingthestringinTable4-3.
Table4-3.
StringValuesStringValue"5"or"4"Success"UnknownToken"Unknown_token"Timeout"Timeout"0"Not_Started"1"Ap_not_found"2"Wrong_Password"3"Ip_add_failedAnyotherstringFailureForexample:CFG_Result_Enumresult_Enum=NetworkUtil.
cfgEnumForResponse(resultString)AndroidBlockDiagramwww.
ti.
com12SimpleLinkWi-FiCC3x20andCC3x3xProvisioningforMobileApplicationsSWRU472B–FEBRUARY2017–REVISEDAUGUST2020SubmitDocumentFeedbackCopyright2020TexasInstrumentsIncorporated4.
8.
4GetErrorMessageFromNumberThisAPIconvertsthenumberintoareadablestring.
Thisstringisshowntotheuserasaresultoftheprovisioningactionsuponcompletion,asshowninTable4-4.
publicstaticStringgetErrorMsgForCFGResult(CFG_Result_Enumresult)Table4-4.
ErrorStringEnumStringSuccess"ProvisioningSuccessful"Unknown_token"CFG_Result_Enum:Unknown_Token";Timeout"CFG_Result_Enum:Time_Out"Not_Started"Theprovisioningsequencehasnotstartedyet.
Deviceiswaitingforconfigurationtobesent"Ap_not_found"CouldnotfindtheselectedWiFinetwork;itiseitherturnedofforoutofrange.
WhentheWiFinetworkisavailablepleaserestartthedeviceinordertoconnect.
"Wrong_Password"ConnectiontoselectedAPhasfailed.
Pleasetryoneofthefollowing:CheckyourpasswordenteredcorrectlyandtryagainCheckyourAPisworking\nRestartyourAP"Ip_add_failed"FailedtoacquireIPaddressfromtheselectedAP.
Pleasetryoneofthefollowing:TryconnectinganewdevicetotheWiFiAPtoseeifitisOKRestarttheWiFiAP"Failure"Pleasetrytorestartthedeviceandtheconfigurationapplicationandtryagain"Forexample:result=NetworkUtil.
getErrorMsgForCFGResult(result_Enum);4.
8.
5GetDeviceNameThisAPIreadsthedevicenamefromthedevice.
ThedevicenameispresentedontheUI,iftheuserdecidestogetthedefaultdevicenameandnottosetadevicename.
publicstaticStringgetDeviceName(StringbaseUrl,DeviceVersionversion)TexasInstrumentsrecommendssettingadevicename,becauseifotherdevicesrespondtomDNS,themobiledevicecannotdecidewhichonebelongstotheactiveone,asnonamewasset.
4.
8.
6SetDeviceNameSetthedeviceURNname,incasethedevicenamefieldisbeingusedbytheuser.
publicstaticBooleansetNewDeviceName(StringnewName,StringbaseUrl,DeviceVersionversion)www.
ti.
comAndroidBlockDiagramSWRU472B–FEBRUARY2017–REVISEDAUGUST2020SubmitDocumentFeedbackSimpleLinkWi-FiCC3x20andCC3x3xProvisioningforMobileApplications13Copyright2020TexasInstrumentsIncorporated5Provisioning–APMode5.
1OverviewAPmodeistheprocessofusingtheAProleofthedeviceforconfigurations.
AfterselectingthedesiredAPforconfigurations,allsettings(ssid,password,devicename,anduuid)aresentbyHTTPprotocol.
Whentheconfigurationsareready,thedeviceswitchestostation(STA)role,andusestheprofile(ssid+password)toconnecttothelocalnetwork.
Atthisstage,themobileapplicationsalsoconnecttothesameAPandwillsearchfortheSimpleLinkdevice,usingoneormoreofthethreemethods:ping,mDNS,andUDPbroadcasts.
IfthereisaproblemfindingtheSimpleLinkdevice,thedevicechangestherolebacktoAP.
ThemobilesideconnectstotheSimpleLinkdeviceagain,butthistimetoclosetheloopandfetchtheprovisioningresults.
OnTI'smobileapplication("Wi-FiStarterPro")thetransitionbetweenAPmodeandSmartConfigissetbyabuttononthe"Settings"screen.
Provisioning–APModewww.
ti.
com14SimpleLinkWi-FiCC3x20andCC3x3xProvisioningforMobileApplicationsSWRU472B–FEBRUARY2017–REVISEDAUGUST2020SubmitDocumentFeedbackCopyright2020TexasInstrumentsIncorporated5.
2APModeFlowChartFigure5-1illustratestheAPmodeflowchart.
Figure5-1.
APModeFlowChartwww.
ti.
comProvisioning–APModeSWRU472B–FEBRUARY2017–REVISEDAUGUST2020SubmitDocumentFeedbackSimpleLinkWi-FiCC3x20andCC3x3xProvisioningforMobileApplications15Copyright2020TexasInstrumentsIncorporated5.
3BlockDiagramFigure5-2illustratestheAndroidblockdiagram.
Figure5-2.
AndroidBlockDiagram5.
4UDPListenerSeeSection4.
5.
UDPlistenershouldbeactivatedwhenthemobileapplicationconnectstothelocalnetworkasastation.
ThereisnouseforUDPlistenerwhilethedeviceisinAPmode.
5.
5mDNSListenerSeeSection4.
6.
mDNSlistenershouldbeactivatedwhenthemobileapplicationconnectstothelocalnetwork.
ThereisnouseformDNSlistenerwhilethedeviceisinAPmode.
5.
6PingTaskSeeSection4.
7.
Pingtaskshouldbeactivatedwhenthemobileapplicationconnectstothelocalnetwork.
ThereisnouseformDNSlistenerwhilethedeviceisinAPmode.
Provisioning–APModewww.
ti.
com16SimpleLinkWi-FiCC3x20andCC3x3xProvisioningforMobileApplicationsSWRU472B–FEBRUARY2017–REVISEDAUGUST2020SubmitDocumentFeedbackCopyright2020TexasInstrumentsIncorporated5.
7HTTPRequestsforAPModeAPmoderequiresadditionalHTTPAPIs,becausetheprofileforthedeviceisbeingtransferreddirectlyfromthemobileappsidetothedeviceusinganexistingWi-Ficonnection.
5.
7.
1GetSSIDListFromDeviceThisAPIrequeststheAPslistfromthedevice.
TheAPIacceptsthelistofscannedAPs.
Thequerydoesnotinitiateascan,butfetchesthelatestAPsfromthedevicelist.
ItisactivatedwhilepressingWi-FinetworkinAPmode.
publicstaticArrayListgetSSIDListFromDevice(StringbaseUrl,DeviceVersionversion5.
7.
2RescanNetworksonDeviceAPIforsettingscanintervalsettings.
publicstaticBooleanrescanNetworksOnDevice(Stringurl,DeviceVersionversion)5.
7.
3AddProfileThisAPIisadirectprofileactivationAPIforstoringanewprofile.
ItacceptsconnectiondetailssuchasSSID,password,andsecuritytype,andsendsthedatatothedeviceusingHTTPprotocol.
publicstaticBooleanaddProfile(StringbaseUrl,SecurityTypesecurityType,Stringssid,Stringpassword,StringpriorityString,DeviceVersionversion)5.
7.
4NotifyDeviceProfileisReadyUponsettinganewprofile,themobileappsideschedulesanactivationofthisprofilebyusingthisAPI.
TheAPInotifiesthedevicethatthemobileappisreadyforthenextstep,andthedeviceshouldrestartinWi-Fistationmodetostartusingtheprofilesetpreviously.
ThisAPIensurestheprofileaddingstepiscompletedandthedevicecanrestartaconnection,usingthenewprofile.
Themobileshouldstartscanningforthenewdeviceaftersendingthisnotificationtothedevice.
publicstaticBooleanmoveStateMachineAfterProfileAddition(StringbaseUrl,Stringssid,DeviceVersionversion)www.
ti.
comProvisioning–APModeSWRU472B–FEBRUARY2017–REVISEDAUGUST2020SubmitDocumentFeedbackSimpleLinkWi-FiCC3x20andCC3x3xProvisioningforMobileApplications17Copyright2020TexasInstrumentsIncorporated6iOSversusAndroidDevelopmentGuidelinesiOSisdifferentinthewayitisactivatedandused,inseveralpoints:iOSpreventsWi-Ficonnectionanddisconnectionfromtheapplicationside.
Whileprovisioning,usingAPmoderequiresconnectingtothedeviceormobileappfromtheSettingsmenu,andcannotbehandledbytheapplicationcode.
Insuchcases,theapplicationnotifiestheuserwhattodo,andtheusershouldperformtheactionmanuallyfromthePhoneSettingsapplication.
iOSpreventsAPIsfromscanningWi-Finetworks.
Insuchcases,theapplicationnotifiestheusertoopenPhoneSettings.
iOShasnoAPIthatexposesthesecuritytypeoftheconnecteddevice.
IfselectinganAPforprovisioning(fromthedevicelist),theusershouldspecifyifandwhatthepasswordisforthisAP.
iOSversusAndroidDevelopmentGuidelineswww.
ti.
com18SimpleLinkWi-FiCC3x20andCC3x3xProvisioningforMobileApplicationsSWRU472B–FEBRUARY2017–REVISEDAUGUST2020SubmitDocumentFeedbackCopyright2020TexasInstrumentsIncorporated7PortingInstructions7.
1GenerateUIFieldsRequiredfortheNetworkSSIDnamePasswordDevicename7.
2AndroidAPProvisioningMode1.
Findthedevicebyname,andconnecttoitbyusingtheWi-FiManagerAndroidAPI.
2.
CheckthatthedevicecantrackyourAPbyactivatingdevicescanningfromthedevice,usingthegetSSIDListFromDeviceAPI.
3.
ActivatetheaddProfileAPIwiththerequiredparametersfromUI.
4.
Optionally,setthedevicename.
5.
ActivatemoveStateMachineAfterProfileAdditiontoindicatethedeviceisreadytorestartafterallsettingsareadded.
6.
ThedeviceshouldconnecttotherequirednetworkbyaddingaprofileandrestartingatSTArole.
7.
ThemobileapplicationshouldconnecttothesameAPnetwork,byusingtheWi-Fimanager.
8.
Themobileappshouldactivatealltheservicestofindthenewdevice:mDNS,ping(broadcast),andUDPserver.
9.
AfterfindingtheIPaddressofthenewdevice,thegetCGFResultFromDeviceAPIshouldbeactivatedtofetchtheresultandindicatethatprovisioningisdone.
10.
Ifthedeviceisnotdetectedorthereisnoresponsefromit,themobileapplicationwilltrytoconnecttoit(assumingitmovedtoAProle),togettheresultandcompletetheprovisioning.
11.
Aftergettingtheresults,provisioningisfinishedifsuccessful.
12.
Incaseoffailure,theerror(wrongpassword,rangeissues,andsoforth)shouldbeinspectedandfixed.
7.
3iOSAPProvisioningMode1.
Findthedevicemanually(iOShasnoAPIforscanningorWi-Ficonnectanddisconnect).
2.
Optionally,activatethegetversionusingthegetProductVersionFromUrlAPItoverifyyou'reusingaSimpleLinkdevice.
3.
Optionally,setthedevicenameusingsetDeviceNameFromUrl.
4.
ActivatetheaddprofileAPIbystartAddingProfileProcedureFromURL,whichiswrappedbytheaddProfileAPI.
ThisAPIisusedforaddingaprofile,anditisfollowedbysendingaresetrequestfromthedevicebycallingthemoveStateMachineAfterProfileAdditionAPI.
5.
Uponaddingaprofile,activatemDdnsDiscoveryStart,andpingtheactivitytimerandUDPlistener(startStopUdp).
6.
AfterfindingtheIPaddressofthenewdevice,activatethegetCGFResultwithUrlAPItofetchtheresultandindicatethatprovisioningiscomplete.
7.
Ifthedeviceisnotdetectedornotresponding,themobileapplicationtriestoconnecttoit(assumingitmovedtoAProle),togetprovisioningresults.
8.
Aftergettingtheresults,provisioningisfinishedifsuccessful.
9.
Incaseoffailure,theerror(wrongpassword,rangeissues,andsoforth)shouldbeinspectedandfixed.
www.
ti.
comPortingInstructionsSWRU472B–FEBRUARY2017–REVISEDAUGUST2020SubmitDocumentFeedbackSimpleLinkWi-FiCC3x20andCC3x3xProvisioningforMobileApplications19Copyright2020TexasInstrumentsIncorporated8SettingsTheSettingstabisusedforapplicationconfigurations,andisapersistentstorageonthelocalstorageoftheapplication.
WithAndroid,thedataissavedasaSharedPreferencesobjectforpersistency.
WithiOS,thedataisstoredusingtheNSUserDefaultsclassobject.
Autodeviceselection–UsingAPmode,itconnectsautomaticallytoaSimpleLinkdevice,ifonlyonedeviceisdetected.
EnableSmartConfig–IfitissettoFalse(default),itrunsonAPmode.
IfTrue,itrunsonSmartConfigmode.
EnableQRreader–AddsaQRcodeoption.
ShowSecurityKey–ShowSmartConfigsecuritykeyforencryption.
OpeninDevicesScreen–Changesdefaultinitscreen.
Settingswww.
ti.
com20SimpleLinkWi-FiCC3x20andCC3x3xProvisioningforMobileApplicationsSWRU472B–FEBRUARY2017–REVISEDAUGUST2020SubmitDocumentFeedbackCopyright2020TexasInstrumentsIncorporated9LoggerandEmailBothiOSandAndroidapplicationsstoredatalogsforsendingtheinformationtoTexasInstruments,incaseaproblemshouldbereported(passwordsarenotstoredasapartofthislogfile).
Thelogfileexistsonthelocalstorageoftheapplication,andinsomecasesitisnotexposedfromthephoneUI.
TheapplicationscontainsanemailsendbuttonontheSettingsscreenwhichallowstheusertofetchandsendthelatestlogfile.
Itsendsittoecs-bugreport@list.
ti.
comasanattachment.
RevisionHistoryNOTE:Pagenumbersforpreviousrevisionsmaydifferfrompagenumbersinthecurrentversion.
ChangesfromRevisionA(February2019)toRevisionB(August2020)PageChangedthedocumenttitle.
2Deletedtheparagraphthatbegan"ThepreferredmodefortheCC3200/CC3100devices…"inSection1.
2,ProvisioningMethods4www.
ti.
comLoggerandEmailSWRU472B–FEBRUARY2017–REVISEDAUGUST2020SubmitDocumentFeedbackSimpleLinkWi-FiCC3x20andCC3x3xProvisioningforMobileApplications21Copyright2020TexasInstrumentsIncorporatedIMPORTANTNOTICEANDDISCLAIMERTIPROVIDESTECHNICALANDRELIABILITYDATA(INCLUDINGDATASHEETS),DESIGNRESOURCES(INCLUDINGREFERENCEDESIGNS),APPLICATIONOROTHERDESIGNADVICE,WEBTOOLS,SAFETYINFORMATION,ANDOTHERRESOURCES"ASIS"ANDWITHALLFAULTS,ANDDISCLAIMSALLWARRANTIES,EXPRESSANDIMPLIED,INCLUDINGWITHOUTLIMITATIONANYIMPLIEDWARRANTIESOFMERCHANTABILITY,FITNESSFORAPARTICULARPURPOSEORNON-INFRINGEMENTOFTHIRDPARTYINTELLECTUALPROPERTYRIGHTS.
TheseresourcesareintendedforskilleddevelopersdesigningwithTIproducts.
Youaresolelyresponsiblefor(1)selectingtheappropriateTIproductsforyourapplication,(2)designing,validatingandtestingyourapplication,and(3)ensuringyourapplicationmeetsapplicablestandards,andanyothersafety,security,orotherrequirements.
Theseresourcesaresubjecttochangewithoutnotice.
TIgrantsyoupermissiontousetheseresourcesonlyfordevelopmentofanapplicationthatusestheTIproductsdescribedintheresource.
Otherreproductionanddisplayoftheseresourcesisprohibited.
NolicenseisgrantedtoanyotherTIintellectualpropertyrightortoanythirdpartyintellectualpropertyright.
TIdisclaimsresponsibilityfor,andyouwillfullyindemnifyTIanditsrepresentativesagainst,anyclaims,damages,costs,losses,andliabilitiesarisingoutofyouruseoftheseresources.
TI'sproductsareprovidedsubjecttoTI'sTermsofSale(http://www.
ti.
com/legal/termsofsale.
html)orotherapplicabletermsavailableeitheronti.
comorprovidedinconjunctionwithsuchTIproducts.
TI'sprovisionoftheseresourcesdoesnotexpandorotherwisealterTI'sapplicablewarrantiesorwarrantydisclaimersforTIproducts.
IMPORTANTNOTICEMailingAddress:TexasInstruments,PostOfficeBox655303,Dallas,Texas75265Copyright2020,TexasInstrumentsIncorporatedIMPORTANTNOTICEANDDISCLAIMERTIPROVIDESTECHNICALANDRELIABILITYDATA(INCLUDINGDATASHEETS),DESIGNRESOURCES(INCLUDINGREFERENCEDESIGNS),APPLICATIONOROTHERDESIGNADVICE,WEBTOOLS,SAFETYINFORMATION,ANDOTHERRESOURCES"ASIS"ANDWITHALLFAULTS,ANDDISCLAIMSALLWARRANTIES,EXPRESSANDIMPLIED,INCLUDINGWITHOUTLIMITATIONANYIMPLIEDWARRANTIESOFMERCHANTABILITY,FITNESSFORAPARTICULARPURPOSEORNON-INFRINGEMENTOFTHIRDPARTYINTELLECTUALPROPERTYRIGHTS.
TheseresourcesareintendedforskilleddevelopersdesigningwithTIproducts.
Youaresolelyresponsiblefor(1)selectingtheappropriateTIproductsforyourapplication,(2)designing,validatingandtestingyourapplication,and(3)ensuringyourapplicationmeetsapplicablestandards,andanyothersafety,security,orotherrequirements.
Theseresourcesaresubjecttochangewithoutnotice.
TIgrantsyoupermissiontousetheseresourcesonlyfordevelopmentofanapplicationthatusestheTIproductsdescribedintheresource.
Otherreproductionanddisplayoftheseresourcesisprohibited.
NolicenseisgrantedtoanyotherTIintellectualpropertyrightortoanythirdpartyintellectualpropertyright.
TIdisclaimsresponsibilityfor,andyouwillfullyindemnifyTIanditsrepresentativesagainst,anyclaims,damages,costs,losses,andliabilitiesarisingoutofyouruseoftheseresources.
TI'sproductsareprovidedsubjecttoTI'sTermsofSale(www.
ti.
com/legal/termsofsale.
html)orotherapplicabletermsavailableeitheronti.
comorprovidedinconjunctionwithsuchTIproducts.
TI'sprovisionoftheseresourcesdoesnotexpandorotherwisealterTI'sapplicablewarrantiesorwarrantydisclaimersforTIproducts.
MailingAddress:TexasInstruments,PostOfficeBox655303,Dallas,Texas75265Copyright2020,TexasInstrumentsIncorporated