NTXEmbeddedWM18xAPI ThankyouforpurchasinganNTXEmbeddedWiFimoduleforCustomerConnectNetworkCloud.This APIguidewillhelpyouunderstandhowourmoduleworksandwhatyoucandowithit. AbouttheWM18x ThereareseveralmodelsoftheWM18xfromNTXEmbedded.APIcallsbelowworkonallWM18x modelsunlessotherwisenoted. ThefirmwareonyourWM18xiscustommadeforyou.ThisdocumentisthegeneralAPIdocumentation fortheWM18x.Yourfirmwaremayhavespecialrestrictionsoradditionalcalls.Thesedifferenceswillbe providedtoyoubyNTXEmbeddedasaseparatedocument. TheWM18Xhasitsownprocessorandisprogrammedforyourapplication.Itisdesignedtodoasmuch oftheworkofcommunicatingtotheInternetorcloudservicesanddoingWiFistuffasitcansoyour processorcandomoreimportantthings.ItisnotageneralpurposeWiFimodule.AssuchtheAPI allowsonlythemostbasicfeaturesneededtoestablishaconnectiontoanaccesspointandtosendand receivethedata.EverythingelseishandledforyoubytheNTXEmbeddedWM18xmodule.Thisisdone bothforsecurityreasonsandtominimizetheworkyoursystemhastodo. CustomerConnectNetworkCloud ThisversionoftheAPIisdesignedtoconnecttotheCustomerConnectNetworkcloudservicesasan MQTTclient.ItimplementssomeoftheAPIasdescribedintheHoundocuments:
MQTTMessages(OvenEvents.docx),VersionP16A,Dated06262018 OvenActivation,Version1.04,Dated02072018 FirmwareUpdateandWIFIParameters,Version1.03,Dated06262018 TheHounhostedCustomerConnectNetworkcloudservicesallowyourdevicetosecurelyconnectto anMQTTbrokerandsendperiodicandlivedatafromyourdevicetothecloudforstorageand/ordisplay. ItalsohasamechanismtoinformthedevicethroughtheWM18xWiFimodulethatfilesareavailablefor downloadandtheWM18xcanretrievethosefilesandgivethemtothedevice.Allofthehardworkof connectingandmaintainingtheconnectiontotheMQTTbrokeraswellaspacketizingthedataproperlyis donebytheWM18xmodule.TheAPIcallsbelowintheNetworkAPIsectionofthisdocumentare usedtosendandretrievedatafromthesecloudservices. ConnectionMethods TheWM18xcomesinseveralcommunicationconfigurationsincludingRS232,RS485,RS422. ItisalsocapableofcommunicatingatvariousBaudrates.Inordertopreventaccidentalchangestothe serialsettings,noAPIexistsatthistimetomodifytheserialsettingsonthefly.Yourcustomfirmware fortheWM18xwillhavetheserialsettingsyouspecifythatwillcommunicatetoyourdevice. Thedefaultserialsettingsare:
Baud:115200;DataBits:8;Parity:None;StopBits:1;FlowControl:None 1 NTXEmbeddedWM18xAPI HowtoReadThisDocumentation AnywherethetermModuleisuseditisreferringtotheNTXEmbeddedWM18xWiFimodule. AnywherethetermDeviceisuseditisreferringtoyourelectronicsthatarecommunicatingtothe Moduleusingaserialconnection. Throughoutthedocumentationactualvaluesthataresentorreceivedviaserialcommunication betweenthemoduleandthedevicewillbeBOLD. Example:NTX_CONFIG Anythingthatwillbereplacedbyactualdatawillbeindicatedby{}. Example:NTX_AP,{SSID},{password}
Where{SSID}and{password}mustbereplacedbytheactualSSIDandpasswordtobevalid.Soifyour SSIDisAbcdandthepasswordis1234thecommandwouldlooklike:
NTX_AP,Abcd,1234 AllcommandstotheWM18Xareformattedinthesameway:
{Command},{Data}
Notallcommandshavedata.Ifnodataissent,thecommaisnotneeded. Somepartsofthe{Data}maybeoptional.Thesewillbeindicatedbysquarebrackets[]. AllcommandstotheWM18xshouldbeterminatedwithacarriagereturnorlinefeed.Eitheronewill causetheWM18xtoacceptthecommandandtrytoparseit. DEVICESTARTUP WhentheWM18xpowersonyouwillseethefollowingmessage NTX_RESTART,{version}
Example:
NTX_RESTART,XC20180921.01 Thefirmwareversionusuallya2or3letterprefixindicatingthecustombuildcustomerandthedatein yyyymmddformatofthebuild.Ifasubbuildnumberorspecialbuildisrequireditwillbeindicatedby thenumbersafterthedecimal.Notallversionswillhaveasubbuildnumberordecimal. IftheWM18xcrashesitwillautomaticallyrestartandsendtheNTX_RESTART,{version}message. 2 NTXEmbeddedWM18xAPI AUTOCONNECT TheWM18xtriestoautomaticallyconnecttoanaccesspoint.ItusesthelastgoodSSIDandpasswordit storedtotrytoconnect.IfthelastgoodSSIDandpasswordfails,itwilltrytoconnectusingtheprevious SSIDandpassworditstored.Themodulealwayskeeps2setsofSSIDandpassword,aprimaryanda backup.Ifthemodulehasneverbeenconnectedtoanaccesspoint,itwillnottrytoautoconnect. AbackupSSIDandpasswordisstoredsothattheSSIDandpasswordcanbechangedremotelyfromthe CustomerConnectcloud.WhentheCustomerConnectcloudsendsanewSSIDandpasswordtothe WM18x,itisstoredinthebackupSSIDandpasswordlocation.Iftheprimaryfails,thebackupistried.If thebackupsetsuccessfullyconnects,itismovedtotheprimarypositionandtheprimarybecomesthe backupset.OnlythebackupisoverwrittenthroughAPIcallsorfromdatasentfromthecloud. Themodulewillcontinuetotrytoconnectevery5secondsorsountilitsuccessfullyconnectsoris disabledbythedevice. ONLINESTATUS TheWM18xindicatesthecurrentonlinestatusofthemodulebyautomaticallysendingthefollowing messagetoyourdevice:
NTX_ONLINE,{status}
Possible{status}values:
0 Notconnectedtoanaccesspoint 1 ConnectedtoanaccesspointbutnotconnectedtotheCustomerConnectcloud 2ConnectedtotheaccesspointandtheCustomerConnectcloud Anytimetheonlinestatusislessthan2,anydatacommands(NTX_LC_xxx)senttotheWM18Xwillbe discarded.TheWM18xdoesnotqueueupdatatobesent.Itistheresponsibilityofthedevicesending thedatatotheWM18xtostoreofflinedataifitisnotconnectedifneeded.TheWM18xwillnotinform youifthedataisbeingdiscarded. Anytimetheconnectionstatuschanges,theWM18xwillsendtheNTX_ONLINE,{status}message.Your deviceshouldbelisteningforthiscommandatalltimesandshouldtakeproperaction. TheNTX_ONLINE,0or1messagewillbesentaboutevery10seconds.Oncethestatusreachesstatus2, thestatusmessageswillnotbesentunlessthestatuschangesorstatusisrequested(NTX_ONLINE). OtherAutomaticMessages Thereareothermessagesthemodulemaysendfromtimetotime.Thesemessagesmaybesentatany timebuttheywillnotinterruptamessage/responsesequenceinprocessunlessnotedbelow.Inother wordsifyousendanAPIcalllikeNTX_CONFIG,theNTX_CONFIG,{}responsewillalwaysbethenext messageyoucanexpecttogetback. 3 NTXEmbeddedWM18xAPI NTX_SEND_CNTThismessagepromptsthedevicetosendthecountersusingNTX_LC_SVC_CNT.This isinitiatedfromtheNetworkcloudportalbyauser.Thismessageissentonlyonce.Ifitismissedor disregarded,theuserwillhavetomaketherequestagainbeforeNTX_SEND_CNTisresenttothe device. NTX_SEND_FCNTThismessagepromptsthedevicetosendthefaultcountsusingNTX_LC_FSTAT.This isinitiatedfromtheNetworkcloudportalbyauser.Thismessageissentonlyonce.Ifitismissedor disregarded,theuserwillhavetomaketherequestagainbeforeNTX_SEND_FCNTisresenttothe device. NTX_FILEindicatesthatafileiswaitingtobesentfromthemoduletothedevice.Thismessageis repeatedeveryfewsecondsuntilitishandled.SeeNTX_FILE,1below. StoringDataWhenOffline Sometimesinthefield,routersgodown,theinternetserviceisinterruptedorotherfactorscausea disruptionintheabilityofadevicetosenddatatothecloudservices.Yourdataisveryimportant.Both theWM18xmoduleandtheNetworkcloudhavemechanismsfordetectingadisconnection,attempting toautomaticallyreconnectandinformingtheuserthatadisconnectionhashappened. Itisimportantthatyoutakeadvantageofthesemethodstominimizedowntime.Howeverthereare circumstanceswheresometimewillelapsebeforetheconnectivityissueisresolved.Inthesecases,if datacontinuityisimportantyou,itisrecommendedthat,ifyourdeviceiscapable,youbuildinthe optiontostoredataonyourdeviceifthemoduleisoffline.Afterthemodulecomesbackonline,youcan sendhistoricaldatawithadateandtimestampwhentheactionactuallyhappenedthroughthemodule sothatthedataisshownintheproperorderinthecloudportal.SeeNTX_LC_ACTIVITYformoredetails. GENERALAPICALLS GeneralAPICallSummary:
NTX_APsettheaccesspointnameandpassword NTX_CONFIGshowthecurrentconfiguration NTX_DISABLETurnWiFiOff NTX_ENABLETurnWiFiOn NTX_FORCE_RESETforcethemoduletoreset NTX_GET_TIMEgetthe time NTX_GET_TIMEgetthe date NTX_LISTAPreturnalistofaccesspoints NTX_ONLINEchecktheonlinestatus NTX_RSSIgettheWiFisignalstrength NTX_SET_DEVICESERIALsetthedeviceserialnumber NTX_WIFI_VERSIONgettheWiFiversion 4 NTXEmbeddedWM18xAPI NTX_AP,{SSID},{password}
{SSID}thenameoftheaccesspointtoconnectto.(MAX75characters)
{password}thepasswordfortheSSID.(MAX75characters) Example:NTX_AP,MySSIDName,MyPass#ord Response:NTX_ONLINE,{onlinestatus}
SeeNTX_ONLINEforpossiblevaluesof{onlinestatus}
Notes:
1. EveryNTX_APcallwillcausetheWM18xtodisconnectfromthecurrentSSIDifitisconnected andtrytoconnectusingthenewSSIDnameandpassword. 2. ThepreviousSSIDandpasswordwillberetained.IftheWM18xconnectstothenewSSID,the oldSSIDandpasswordwillbecomethebackup.IftheWM18Xdoesnotconnecttothenew SSID,thenewSSIDandpasswordwillbestoredasthebackupSSIDand password. 3. MakingacalltoNTX_APwilltriggeratleastoneNTX_ONLINEmessage 4. SendingtheNTX_APcallmorethanoncewillcauseaninterruptofanyprocessgoingon includinganotherNTX_APcall.ItisrecommendedthatyouwaitfromtheNTX_ONLINEresponse totheNTX_APcallbeforesendinganother.Itisfurtherrecommendedthatyoucall NTX_CONFIGaftertheNTX_ONLINEresponse.TheStatusintheresponsetotheNTX_CONFIG willbeTRYINGasthemoduleworksongettingaconnectionwiththeAP.Youcanpollthe NTX_CONFIGcalluntilthestatusisCONNECTEDorFAILED.(SeeWorkflow) NTX_CONFIG Example:NTX_CONFIG Response:NTX_CONFIG,{MAC},{SSID},{ConnectStatus:IPAddress:channel},{NetworkSerial}
{MAC}=TheMACaddressofthismoduleintheformof
{SSID}=TheSSIDthatthemoduleisconnectedtooristryingtoconnectto
{ConnectStatus:IPAddress:channel}=Theconnectstatus,IPAddressifconnectedandchannel connectedto.Possiblevaluesofconnectstatusare:
GOTIP TRYING FAILED GOTIPindicatesthataDHCPaddresswasobtained. TRYINGindicatesthatthemoduleisstilltryingtoconnecttotheaccesspoint. FAILEDindicatesconnectiontotheaccesspointwasdeniedorfailed. 5 NTXEmbeddedWM18xAPI NetworkSerialistheuniqueserialnumberNetworkknowsthismoduleby.Bydefaulttheserialnumber willbetheHEXvaluesoftheMACaddressofeachmodulewithoutanycolonsbetweensegments. NTX_DISABLE ThisAPIcallcausesthemoduletodisconnectfromanyAPI,stopattemptingtoconnectandstopall transmission.NoAPIcallwillworkwhendisabled,untilthemoduleisEnabled.Thismodealsoputsthe moduleintolowpowermode. SomecustomersdonotliketheideaofaWiFideviceintheirdevices.Themodulecannotalwaysbe easilyphysicallydisconnectedfromthedevicesothismethodcanbecalledonpowerupfromthe deviceanditwillputthemoduleintoamodewhereitisnotabletoconnecttoarouterortobe connectedtoinanyway. NTX_ENABLE Themoduleisenabledbydefault.AcalltoNTX_ENABLEwhenthedeviceisalreadyenableddoesnot haveaneffect. NTX_FORCE_RESET Example:NTX_FORCE_RESET Response:None(Moduleresets,seeStartupabove) Thiscallistobeusedincasesomethingonthemodulegoeswrongandasoftresetofthemoduleis required. NTX_GET_TIME Example:NTX_GET_TIME Response:NTX_GET_TIME,{hh:mm:ssGMT}
ThetimeiscurrentGMTtime. NTX_GET_DATE Example:NTX_GET_DATE Response:NTX_GET_DATE,{yyyy:mm:ddGMT}
ThedateiscurrentGMTdate. 6 NTXEmbeddedWM18xAPI NTX_LISTAP Example:NTX_LISTAP Response:NTX_LISTAP,{AP1,AP2,,APn}
{AP1,AP2,,APx}isacommadelimitedlistoftheSSIDforallaccesspointsdetected. Notes:
Ifnoaccesspointsarefound,NTX_LISTAP,NO_APwillbereturned 1. 2. ThestrongestRSSIaccesspointwillbelistedfirst. 3. Duplicateaccesspointnamesarenotincluded. 4. Only10detectedaccesspointswillbelistedatatime. 5. Thereiscurrentlynowaytogetthenextpageofaccesspoints NTX_ONLINE Example:NTX_ONLINE Response:NTX_ONLINE,{onlinestatus}
SeeOnlineStatusabove. Thismethodistobeusedwhenanimmediatecheckoftheonlinestatusisneeded. NTX_RSSI Example:NTX_RSSI Response:NTX_RSSI,{RSSIvalue}
{RSSIvalue}range30to90 SeetheNTXEmbeddedWM18xSignalStrengthandQualityGuideformoreinformationandstrategies formaximizingsignalstrength. NTX_SET_DEVICESERIAL Example:NTX_SET_DEVICESERIAL,{serialnumber}
Response:None
{serialnumber}=Max25printablecharacters.ThisisthenumberthatyouwillseeonLetsCook.Itis initiallyusedasthefriendlynameforthisdevice. 7 NTXEmbeddedWM18xAPI Sendsaserialnumberofthedevicetothemodule.Theserialnumberisrequiredtoinitiateaconnection totheNetworkservice.Seeconnectionworkflows. NTX_WIFI_VERSION Example:NTX_WIFI_VERSION Response:NTX_WIFI_VERSION,{version_number}
Thiscallisforinformationalpurposesonly.YoumaywanttodisplaytheWiFifirmwareversionoruseit fordiagnosticpurposes. 8 NTXEmbeddedWM18xAPI NetworkAPI TheseAPIcallsarespecificallydesignedtosendorreceivedatatotheNetworkcloudservices.Since theyaremakingacallouttotheInternettheresponsemaybeasynchronoussomanyofthemare designedwithnoimmediateresponsefromthemodule.IfyouseeResponse:NONE,thedeviceshould makethecallandmoveontothenextcallwithoutwaitingforaresponse.Alwaysobservecalltiming minimums. ThisAPIreferstoadocumentcalledtheNetworkMatrix(shortenedtoMatrixFilebelow).Thisisa documentthatshouldbecreatedandnegotiatedbetweenyouandHounothatspecifiesthespecific datayouaresendingtothecloudservice.ItidentifiesalltheIDsyouwillsendasdatatothisAPIthatare thensenttotheNetworkcloud. ItislikelythatyouwillworkwithHounotocustomizetheNetworkcloudpagestofityourneeds.In somecasesyoumaychangethenameoftabsorscreens,youmaychangewheredataisshownoryou manychangethelabelsoriconsassociatedwithdata.IntheAPIcallsbelowwetrytoreferencewhatwe knowaboutwhereandhowdataisdisplayedsoyoucaneasilytestafteryouusetheAPI.However,as youcustomizetheNetworkcloudinterfacepleasebeawarethattheModuledoesnotdictatehowor wheredataisdisplayedintheNetworkcloudpages. TheAPIfortheNetworkcloudisdesignedtominimizecodechangesontheModule.Theremaybecases wherechangestoaskHounotomaketotheNetworkcloudrequirechangesonthemoduletoproperly work. NetworkAPICallSummary:
NTX_LC_ACTIVITYSendactivityevents NTX_FILEFiletransferinformationandnotifications NTX_LC_FSTATSendthefaultcounts NTX_LC_LIVESendlivecarddatatoLetsCook NTX_LC_META_ADDRESSSendlocationdata NTX_LC_META_DEVICESenddevicedata NTX_LC_STATESendthestateofthedevice NTX_LC_STATUSReturnthestatusofNetworkconnectivity NTX_LC_SVC_CNTSendthecounters 9 NTXEmbeddedWM18xAPI NTX_LC_ACTIVITY Example:
NTX_LC_ACTIVITY,{date_time},{activity_id},{group}[,{data_1_name},{data_1_type},{data_1_value},
{data_2_name},{data_2_type},{data_2_value},,{data_n_name},{data_n_type},{data_n_value}]
Response:None
{date_time}ifthisactivityislive/realtimedatasend1. Ifthisisofflinedata,meaningstored,the{date_time}mustbeintheformof
{yyyy}{mm}{dd}T{hh}:{mm}:{ss}Z
%d%02d%02dT%02d:%02d:%02dZ AndalldatesandtimesmustbeinGMT/UTD.
{activity_id}integertheidassignedintheMatrixfiletotheeventyouarereporting
{group}integereachactivityisassignedtoagroupintheMatrixFile.Youmustsendthegroup associatedwiththeactivity_idorthedatamaynotproperlydisplayinLetsCook.
{data_x_name}stringthenameofthedatayouaresendingforthisactivity.
{data_x_type}stringthetypeofdatavalueyouaresending.Possiblevaluesareint,str,bool,dec
{data_n_value}variousthevalueassociatedwiththedata_n_name Activitiesaresingleeventsthathappenonthedevicethatyouwanttorecordintheclouddata. ExamplesofActivitiesmightbethedevicebeingturnedon,adooropening,acookstarting,amotor comingon,atemperaturehittingathreshold,thevolumebeingchanged,ortheusernavigatingtoa certainscreen.Activitiescanhavedataassociatedwiththemthatisthendisplayedinthecloud.For instanceiftheeventisacookstarting,youcouldsendtherecipenameorthetimewiththeevent.Ifthe volumeischanged,youcouldsendthenewvolumeasthedata.Datacanbesimpleorcomplex.Ifyour eventisamotorturningoff,youcouldsendthedurationitwasonandthepositionofthemotorwhenit stopped.Activitiesshouldbeusedonlyfordiscreteactionsthatarenotlikelytohappenmanytimesa second. ActivityeventsshouldbesenttotheCustomerConnectCloudastheyhappen.Thedeviceshouldqueue theactivitiesandsendthemoneatatime.Observethetimingrequirementsofthemodule. Notes:
OnlyoneActivitycanbesentatatime Amaximumof5setsofdatacanbesentwitheachactivity Eachoccurrenceofanactivityshouldbesentonlyonce.Ifthesameoccurrenceofanactivityis sentmorethanonce,evenwiththesamedatecode,itwillberecordedeachtimeasaseparate activity. Activitydataisoptional 10 NTXEmbeddedWM18xAPI NTX_FILE TheWM18xmodulehastheabilitytoreceivefilesfromCustomerConnect.Thesefilescanbemenu updates,images,firmwareupdatesorjustaboutanything.ThesefilescanberetrievedfromCustomer Connectwhentheyareavailableorjustwhenneeded. TheprocessofmovingafileacrossaserialconnectionisslowsotheDeviceandtheModulewillnotbe sendingandreceivingregulardatainformationwhilethisishappening.Inotherwords,ifyouneedto constantlysendtemperatureuptothecloud,itwillhavetostopwhilethefileisbeingsentfromthe moduletothedevice.Often,filetransfersonlyhappenwhenthedeviceisinanidleoroffstate. Whenafileisavailable,themodulewillsendamessagetothedeviceevery20secondsorso:NTX_FILE Whenthedeviceisreadytoreceivethefile,itshouldsendNTX_FILE,1. ThemodulewillrespondwithNTX_FILE,{file_type},{file_size},{Name}
{file_type}isdefinedintheMatrixFile.Thiscanbeusedtodecidethefilenameand/orhowtousethe data.
{file_size}isinbits.Filesmustbesmallerthan1GBatthistime.
{Name}isthenameassignedtothisfile.Itdoesnotnecessarilyrepresentthefilename.Itisjustaname thatgoeswiththedata.Itcanbeusedanywayneeded. Thedeviceshouldthenpreparetoreceivethefileinchunksof32767bitsatatimethroughtheserial port. Thedevicethensends:NTX_FILE,2andthemodulerespondswiththefiledatainchunksof32767.The lastchunkwillbesmallerthan34767bits. Oncethelastchunkissent,themoduleandthedeviceshouldreturntonormaloperations. NTX_LC_FSTAT Example:NTX_LC_FSTAT,{fault1id},{fault1count},,{faultnid},{faultncount}
{fault1id}inintegerdefinedintheMatrixfilethattellsNetworkwhichfaultisbeingcounted.
{fault1count}aninteger Response:None TheNTX_LC_FSTATcallsendsfaultcountdatatotheCustomerConnectcloud. Notes:
1. ThefaultsforadevicearedefinedintheMatrixFile 2. ThefaultIDcanbeanumericoralphanumericIDbutshouldneverbemorethan 5characters 11 NTXEmbeddedWM18xAPI 3. IMPORTANT:OneentryforeachfaultidintheMatrixFilemustberepresentedineachcallto NTX_LC_FSTATevenifthecountis0.Inotherwordsifyouhave10faultIDs,all10faultIDsand countsmustbesentwitheverycallofNTX_LC_FSTAT.AnyfaultIDsthatarenotsentwillnotbe shownintheNetworkdatapage. 4. Faultscanbesentnomorethanonceanhour.Wesuggestsendingthemonlyoncea day. 5. Amaximumof15faultsareallowed NTX_LC_LIVE Example:
NTX_LC_LIVE,{live_data_1_name},{live_data_1_type},{live_data_1_value},,{live_data_n_name},{live_ data_n_type},{live_data_n_value}
{live_data_x_name}isthenameofthelivedataasdefinedintheMatrixFile.Usetheexactvalueinthe MatrixFile
{live_data_x_type}canbe:int,str,bool,dec.IfthedatatypeisaBooleansendthestringtrueorfalse
(lowercase).Ifthedatatypeisadecimal,itislimitedto2decimalplaces. Response:None Livedataisintendedtoshowsomeeventthatishappeningrightnowthatisinterestingtotheuserto observeinnearrealtime.Examplesoflivedatawouldbetherecipenameandcountdowntimerwhile cookingortheactualtemperatureduringwarmuporthecountdowntimeronacleaningcycle.Thedata sentaslivedataisnotstoredinthecloudsoitcannotbereferencedlaterandchartedovertime. LivedatashowsuponthebackofthelivecardinLetsCook.Itissentonlyifthedeviceisbeingactively monitoredandisnotstoredinLetsCook.Thedeviceshouldalwayssendlivedatatothemodulewhen butitwillonlybesenttothecloudifthedeviceisbeingmonitored. Notes:
Livedatacanbesentinanyorder. Becausetheamountoflivedataeffectshowquicklyitcanbetransmitted,wesuggestkeeping theamountoflivedatatoaminimum. Livedatashouldnotbesentmorethanonceasecond Livedatadoesnotneedtobesentallatonce.Itcanbeupdatedpiecebypiece ifneeded. Maximumnumberofpiecesoflivedatapercall5 NTX_LC_META_ADDRESS Example:NTX_LC_META_ADDRESS,{friendly_name},{device_info_1_name},{device_info_1_value},,
{device_info_n_name},{device_info_n_value}
{friendly_name}isastringthatwillshowupasthenameofthisdevice.Oftentheserialnumberisused butitcanbeanynameupto35characters 12 NTXEmbeddedWM18xAPI
{device_info_1_name}isastringusetheexactvalueintheMatrixFile.
{device_info_1_value}isastring.Max35characters. Response:None Addressmetadataisusuallyinformationlikecity,state,country,address,zipetc.Metadatawillbe definedintheeventsmatrix. Notes:
MetadataisdisplayedinseveralplacesthroughouttheNetworkscreens Maximumnumberofaddressmetadatasetspercallis5 YoumaymakemorethanonecalltoNTX_LC_META_ADDRESSifyouhavemorethan5setsof data NTX_LC_META_DEVICE Example:NTX_LC_META_DEVICE,{device_id}{device_info_1_name},{device_info_1_value},,
{device_info_n_name},{device_info_n_value}
{device_id}stringtheserialnumberofyourdevice.Maximumof20characters.
{device_info_1_name}stringusetheexactvalueintheMatrixFile
{device_info_1_value}stringthevalueassociatedwiththedevice_info_name Response:None Devicemetadataisusuallyinformationlikeversionnumber,modelnumber,serialnumberetc.Meta datawillbedefinedintheeventsmatrix. Notes:
MetadataisdisplayedinseveralplacesthroughouttheNetworkscreens Maximumnumberofdevicemetadatasetsis5 YoumaymakemorethanonecalltoNTX_LC_META_DEVICEifyouhavemorethan5setsof data NTX_LC_STATE Example:NTX_LC_STATE,{state_name},[{data_1_name},{data_1_type},{data_1_value}]
Response:None
{state_name}isthenameofthestateassignedintheeventsmatrix.
[{data_x_name},{data_x_type},{data_x_value}]isoptional.
{data_1_name}stringthestringidentifierofthedataabouttobesent. 13 NTXEmbeddedWM18xAPI
{data_1_type}stringthetypeofthedata_x_valueabouttobesent
{data_1_value}thevalue ThestateofthedeviceshowsuponthefrontandbackofthelivecardinLetsCook.Itissentonlyifthe deviceisbeingactivelymonitoredandisnotstoredinLetsCook.Thedeviceshouldalwayssenditwhen thestatechangestothemodulebutitwillonlybesenttothecloudifthedeviceisbeingmonitored. BecauseNetworkdoesnotstorethestate,ifyouchangescreensorrefreshthecloud,thestatein NetworkmayreverttoSTANDBY.Thisisthedefaultstateifithasnotreceivedastaterecently.We suggestyousendthecurrentstateasoftenasmakessense.Itshouldneverbesentmoreoftenthan onceasecond.Amorereasonableperiodisaboutonceevery10seconds. Notes:
Notallstateshavedatasoitisshownasoptional. IfyousentastatethatisidentifiedintheMatrixfileasneedingdata,withoutthedata,thestate maynotdisplayproperlyinLetsCook. Maximumnumberofdatasetsperstateis10 Ifyoualsowanttocollectstatechangesasactivitiesyouneedtosendanactivityaswellasa stateAPIcalltothemodule. NTX_LC_STATUS RespondswiththestatusoftheconnectiontotheNetworkcloud. Example:NTX_LC_STATUS Response:NTX_LC_STATUS,{lc_status}
{lc_status}=0NotconnectedtotheNetworkMQTTbroker
{lc_status}=1ConnectedtotheNetworkMQTTbroker Notes:
1. Aconnectionstatusof1maymeanthatthedeviceisfullyconnectedormaybeinpendingor approvedbutnotputintoagroup.Themoduledoesnotknowwhichofthesemodesthedevice isinonlythatitisconnectedordisconnectedfromtheNetworkserver. 2. UsetheNetworkonlineportaltodeterminethestatusofthedeviceconnection. 14 NTXEmbeddedWM18xAPI NTX_LC_SVC_CNT Example:
NTX_LC_SVC_CNT,{counter_1_id},{counter_1_type},{counter_1_value},,,{counter_n_id},{counter_n_ type},{counter_n_value}
{counter_x_id}istheintegeridofthecounterasdefinedintheeventsmatrix.
{counter_x_type}canbe:countorhours
{counter_x_value}isaninteger Response:None CountersareshownintheServiceCounterstabofLetsCook.Allcountersmustbesenteverytime.If youonlysend3countersinasinglecalltoNTX_LC_SVC_CNT,youwillonlysee3entriesintheService Counterstab. Notes:
TheunitsoftheservicecountersmustbeworkedoutinadvancewiththeCustomerConnect cloudservicessystem. Maximumnumberofcountersthatcanbesentis10 15 NTXEmbeddedWM18xAPI Workflows:
Connection WhenyourdevicefirstestablishestheserialconnectiontotheWM18x,youshouldwaitforthe NTX_RESTARTmessagebeforesendinganythingtothemodule.NTX_RESTARTindicatesthatthe moduleiscommunicatingwithyourdeviceproperly. Next,waitfortheNTX_STATUSmessage.Thismessagewillindicateifthemoduleiscommunicatingwith theAPandwithLetsCook. Ifyourdevicetakeslongertocomeupandstartcommunicatingseriallyandthismessageismissed,itis suggestedthatyoumakecallstoNTX_ONLINE FromtheresultsoftheNTX_STATUSorNTX_ONLINEmessage,youshouldbeabletodecidewhattodo next. SincetheWM18xconnectstothelastknownaccesspointautomatically,aftertheinitialconnectionis establishedthereisverylittleforthedevicetodoonstartupaftertheinitialconnectionisestablished. Inmostsystems,thereisaUItosettheSSIDandpassword.InitiallyyoushouldcallNTX_CONFIGsoyou canshowtheMACaddressintheUI.ThisisimportantbecausetheMACaddressisusedtouniquely identifythemoduletotheNetworkcloud.YourdevicesserialnumbermaychangebuttheMACwillnot changesoitcanalwaysbeusedtofindthedeviceifyouareunsureoftheserialnumber. Whenadeviceconnectsforthefirsttime,weatherafterapowercycleorwhenthemodulestatus transitionsfromofflinetoonline,itisrecommendedthatthedevice,getthecurrenttimeanddateand thensendthecurrentstatus(NTX_LC_STATUS)andmetadata(NTX_LC_META_DEVICE).Thismakessure CustomerConnecthaseverythingitneedstoshowthecurrentstatusofthedevice. Afterconnectiontotheaccesspointissuccessful,themoduleisreadytoconnecttotheNetwork system.Tostartthisprocessitneedstheserialnumberofthedevice.Use NTX_SET_DEVICESERIAL,{serialnumber}tosetit. FirstTimeConnectionCheckList:
IfNTX_ONLINEvalueis0,SendNTX_AP,{SSID},{password}
WaitforNTX_RESTARTandorNTX_ONLINE WaitforNTX_ONLINE,1 WaitforNTX_ONLINE,2 SendNTX_SET_OVENSERIAL,{ovenserial}
LogintoNetworkandselectthenewdeviceinthependinglistandeitherconfirmitorputitina group.Untilthisisdone,thedevicewillnotreportNTX_ONLINE,2.Assoonasthedeviceis confirmedonline,themodulewillgetamessageandinformthedeviceitisreadytoreceivedata. OnceNTX_ONLINE,2isreceived 16 NTXEmbeddedWM18xAPI o SendandhandletheresponseforNTX_DATEandNTX_TIMEifneeded o SendNTX_LC_META_DEVICE,{}
o SendNTX_LC_META_ADDRESS,{}
o SendNTX_LC_STATE,{}
Continuetomonitortheserialconnectionandsenddataasneeded SecondTimeConnectionCheckList IfNTX_ONLINEvalueis0,SendNTX_AP,{SSID},{password}
WaitforNTX_RESTARTandorNTX_ONLINE WaitforNTX_ONLINE,1or2 IfNTX_ONLINE,2 o SendNTX_SET_OVENSERIAL,{ovenserial}
o SendandhandletheresponseforNTX_DATEandNTX_TIMEifneeded o SendNTX_LC_META_DEVICE,{}
o SendNTX_LC_META_ADDRESS,{}
o SendNTX_LC_STATE,{}
o Continuetomonitortheserialconnectionandsenddataasneeded FileDownload InCustomerConnectsendafiletoadevice ModulesendsNTX_FILEevery20secondstothedevice.Thedevicecanignorethismessageforaslong asitwants. DevicesendsNTX_FILE,1whichpromptsthemoduletoreturnthefileheaderinfoandgetreadyto sendthefilewhichmayincludedownloadingitdependingonthesize. ModulesendsNTX_FILE,{header}
DevicesendsNTX_FILE,2 Modulesends{datapacket1}{datapacket2}{}{datapacketn}
MonitoringTheModule Thedeviceshouldhavethreemodesofmonitoringtheserialport. Mode1:SendandReceive.CertainAPIcallsabovealwaysrespondtotheAPIcall.Inthiscaseitis guaranteedthatwhenthedevicesendsanAPIrequest,theresponsewillcomeinbeforeanythingelse. Itisalwayspossiblethatsomethinggoeswrongsoeveninthismodeatimeoutshouldbeset.Ifno responsecomesinwithinafewseconds,thecallshouldabortorrepeat.Likewiseifaresponsecomesin thatwasunexpected,thecallshouldabortorrepeat. 17 NTXEmbeddedWM18xAPI Mode2:Listening.Inseveralcases,themodulemaysendinformationtothedevicebasedoninputfrom thecloudlikearequesttorefreshthestatisticsorachangeinconnectivitystate.Foreachofthese,the deviceneedstobelisteningandneedstohandlethemwhentheycomein. Mode3:FileTransfer.Inthiscase,thereisnoendofdataterminatorcharacter,itisallbasedonthe buffersize.Therestofthemodesshouldbesuspendedwhileinthismode. OngoingMonitoringCheckList(Pseudocode) 1. AmIwaitingonaresponsetosomemessageIsent?Didtheresponsecomein?Ifsohandleit.If notcontinuetowaitfortheresponseuntilItimeout. 2. DidNTX_ONLINE,{}comein?Ifitdid,doesitindicateweareoffline?Ifsochangetostoringthe activitydataoffline.Showtheuserweareofflinesotheycanfixit. 3. DidNTX_SEND_FCNT,NTX_SEND_META,NTX_FILEcomein?Ifsohandlethem. SendingOfflineData Asdiscussedpreviously,itisrecommendedthatifthemoduleisoffline,thedeviceshouldstoreactivity datalocallyifitcanuntilthemodulecomesbackonline.Adateandtimestampshouldbestoredwith eachactivityalongwithallthedataneededtomaketheNTX_LC_ACTIVITYAPIcall. Whenitdoescomebackonline,theactivitydatacanbesentwiththetimestamp.Thecloudwilluse thetimestamptoputthedataintherightorder.Youcansendofflinedatamixedwithrealtimedata. Werecommendaqueueofsomekindthatisbeingfilledwithamixofrealtimeandofflinedata.Be carefultoleaveyourprogramtimetolookforincomingmessagesandtodootherwork. Size SPIFlash Bluetooth WiFi Interface OnchipSensor IOPort UARTBaudrate FrequencyRange Antenna 18.0*25.8*2.80.2mm Default32Mbit Bluetooth4.2BR/EDRandBLEstandards 802.11b/g/n UARTSPISDIOI2CPWMI2SIRADCDAC Hallsensor,Temperaturesensor,Capacitivetouchsensor 22 Support300~4608000bps,De115200bps 2412~2462MHz PCBAntenna, Max. gain 0dBi 802.11b:172dBm(@11Mbps) 802.11g:142dBm(@54Mbps) 802.11n:132dBm(@MCS7) CCK,1Mbps:90dBm CCK,11Mbps:85dBm 6Mbps(1/2BPSK):88dBm 54Mbps(3/464QAM):70dBm MCS7(65Mbps,72.2Mbps):67dBm TransmitPower Receiving Sensitivity PowerDissipation 300mA@3.3V Security WPA/WPA2/WPA2Enterprise/WPS 18 PowerSupply Range Operating Temperature Storage Environment Weight BOM PartDescription CAPCER0.01uF 16VX7R0603 CAPTANT100UF 20%4V1206 CAPCER0.1UF 16V10%X7R0603 DNPCONN HEADERVERT 2POS.100TIN FERRITEBEAD30 OHM@100MHz 3A08051LN RES1.0KOHM 1/10W5%0603 SMD RES10KOHM1%
1/10W0603SMD RES10OHM 1/10W5%0603 SMD 2mm10X1pin header(use2 pieces) WiFi+BT+BLE module,AIThinker TVSDIODE 24VWM44VC SOT23 PCB2layerFR4 0.8mm,25mmX 34mm NTXEmbeddedWM18xAPI 3.0V~3.6V 20 ~85 40 ~90 ,<90%RH 1.5g Quantity Package DigiKeyPartNumber Reference 2 0603 1 1206 1 0603 127619262ND C1,C3 39936882ND C2 127610052ND C16 0 A31112ND JP1 1 0805 127663762ND L1 4 0603 1 0603 3111.0KGRTRND RMCF0603FG10K0TR ND R1,R2,R3,R4 R8 2 0603 31110GRTRND R6,R7 2 1 8807001010 001101ND 1 SOT23 NUP2105LT1GOSTR ND 1 U1 U2 U3 19 PCBLayout NTXEmbeddedWM18xAPI Figure1ESP32SPCBTopLayer Figure2ESP32SPCBGNDLayer 20 NTXEmbeddedWM18xAPI Figure3ESP32SPCBPOWERLayer DocumentVersion:12/5/2018 Figure4ESP32SPCBBottomLayer 21 NTX Embedded WM 18x API FCC Statements This device complies with part 15 of the FCC Rules. Operation is subject to the following two conditions:
(1) This device may not cause harmful interference, and
(2) this device must accept any interference received, including interference that may cause undesired operation. Changes or modifications not expressly approved by the party responsible for compliance could void the user's authority to operate the equipment. FCC Radiation Exposure Statement The modular can be installed or integrated in mobile or fix devices only. This modular cannot be installed in any portable device, for example, USB dongle like transmitters is forbidden. This modular complies with FCC RF radiation exposure limits set forth for an uncontrolled environment. This transmitter must not be co-located or operating in conjunction with any other antenna or transmitter. This modular must be installed and operated with a minimum distance of 20 cm between the radiator and user body. If the FCC identification number is not visible when the module is installed inside another device, then the outside of the device into which the module is installed must also display a label referring to the enclosed module. This exterior label can use wording such as the following: Contains Transmitter Module FCC ID: 2AMU6WM181 Or Contains FCC ID: 2AMU6WM181 When the module is installed inside another device, the user manual of this device must contain below warning statements:
1. This device complies with Part 15 of the FCC Rules. Operation is subject to the following two conditions:
(1) This device may not cause harmful interference, and
(2) This device must accept any interference received, including interference that may cause undesired operation. 2. Changes or modifications not expressly approved by the party responsible for compliance could void the user's authority to operate the equipment. The devices must be installed and used in strict accordance with the manufacturer's instructions as described in the user documentation that comes with the product. The host product manufacturer is responsible for compliance to any other FCC rules that apply to the host not covered by the modular transmitter grant of certification. The final host product still requires Part 15 Subpart B compliance testing with the modular transmitter installed. The end user manual shall include all required regulatory information/warning as shown in this manual, include:
This product must be installed and operated with a minimum distance of 20 cm between the radiator and user body. 22