Digi X4K-Z1U-00011-A1 User manual











iDigi®GatewayDevelopmentKit
GettingStartedGuide








December16,2010
90001205_A
Downloaded from Elcodis.com electronic components distributor

iDigiGatewayDevelopmentKitGettingStartedGuide 2

©2010DigiInternationalInc.
Allrightsreserved.

Digi,iDigi,DigiInternational,theDigiandiDigilogos,ConnectPort,DigiESP,iDigiDia,XBee,DigiXBee
SmartPlug,iDigiManagerPro,iDigiWebServicesAPI,andaDigiInternationalCompanyaretrademarks
orregisteredtrademarksofDigiInternational,Inc.intheUnitedStatesandothercountriesworldwide.
Allothertrademarksarethepropertyoftheirrespectiveowners.

Informationinthisdocumentissubjecttochangewithoutnoticeanddoesnotrepresentacommitment
onthepartofDigiInternational.

Digiprovidesthisdocument“asis,”withoutwarrantyofanykind,eitherexpressedorimplied,including,
butnotlimitedto,theimpliedwarrantiesoffitnessormerchantabilityforaparticularpurpose.Digimay
makeimprovementsand/orchangesinthismanualorintheproduct(s)and/ortheprogram(s)described
inthismanualatanytime.

Thisproductcouldincludetechnicalinaccuraciesortypographicalerrors.Changesareperiodicallymade
totheinformationherein;thesechangesmaybeincorporatedinneweditionsofthepublication.

Downloaded from Elcodis.com electronic components distributor

iDigiGatewayDevelopmentKitGettingStartedGuide 3

UsingthisGuide
ContactInformation
PleasealwayschecktheproductspecificsectionontheDigisupportwebsiteforthemost
currentrevisionofthisdocument:http://www.digi.com/gatewaydevelopmentkit.

FormoreinformationaboutyourDigiproducts,orforcustomerserviceandtechnicalsupport,
contactDigiInternational.

TocontactDigiInternationalbyUse
MailDigiInternational
1101BrenRoadEast
Minnetonka,MN55343
U.S.A.
WorldWideWebhttp://www.digi.com/support
Telephone(US)(952)912‐3444or(877)912‐3444
Telephone(otherlocations)+1(952)912‐3444or(877)912‐3444

ConventionsusedinthisGuide



Thisiconindicatesastepthathasthepotentialtobe
troublesome.Furtherinformationregardingitems
markedwiththissymbolcanbefoundinAppendixA:
Troubleshootingonpage60.



Thisiconindicatesahint,orconceptthatislearned.


Thisiconindicatesthatagoalofthekithasbeen
completed.

Thisiconindicatesawarningofthepotentialfor
confusionordanger.
Downloaded from Elcodis.com electronic components distributor

iDigiGatewayDevelopmentKitGettingStartedGuide 4

Contents
IntroductiontotheiDigi®GatewayDevelopmentKit...................................................................................6
GoalsoftheKit..........................................................................................................................................6
RequirementsoftheKit............................................................................................................................6
Part1:SetupyourDigi®GatewayDevelopmentKit......................................................................................7
Step1:KitPreparation..............................................................................................................................7
Step2:ConnecttheConnectPortX4®toyourLocalNetwork..................................................................8
Step3:ConnectyourConnectPort®X4toiDigi®......................................................................................10
Step4:InstalltheDigiESP™forPythonDevelopmentEnvironment.....................................................14
Step5:CreateyourfirstiDigi®DiaProject..............................................................................................17
Step6:PerformaniDigiWebServicesAPI™Request............................................................................38
Step7:UsingtheiDigi®GatewayDevelopmentKitDemonstrationApplication....................................45
Part2:LearnMore......................................................................................................................................52
iDigi®Dia&iDigi®.....................................................................................................................................52
DigiESP™forPython...............................................................................................................................54
Digi’s®Gatewayproducts........................................................................................................................58
XBee®Sensor...........................................................................................................................................59
XBeeSmartPlug™(orXBee®WallRouterinnon‐USkits)......................................................................59
Digi’s®ZigBeeRFModules.......................................................................................................................59
AppendixA:Troubleshooting.....................................................................................................................60
XBee®devicesfailtojointheConnectPortX4’sXBee®network.............................................................60
IstheASSCLEDsolidgreen?...............................................................................................................60
Downloaded from Elcodis.com electronic components distributor

iDigiGatewayDevelopmentKitGettingStartedGuide 5

IstheASSCLEDblinkinggreen?..........................................................................................................60
iDigiManagerPro™doesnotdiscoveryourConnectPort®X4...............................................................61
iDigiManagerPro™liststheConnectPort®X4as‘Disconnected’..........................................................63
Downloaded from Elcodis.com electronic components distributor

iDigiGatewayDevelopmentKitGettingStartedGuide 6

IntroductiontotheiDigi®GatewayDevelopmentKit
ThankyouforpurchasinganiDigiGatewayDevelopmentKit.Thekitisdesignedtomakeiteasy
tosetupanXBeenetwork,uploadacustomiDigiDiaapplication,andprovideseamless
connectivitytotheiDigiplatformforwebservicesintegrationtostandardbusinessapplications
overtheInternet.Beforeyoustartworkingwiththekit,let’scoversomebasics.
GoalsoftheKit
Asyougothroughthestepsinthiskit,youwill:
1. CreateaniDigideveloperaccountontheiDigiM2Moperatingplatform.
2. SetupandconfigurethephysicalelementsofanXBeewirelessnetworkandunderstand
howthenetworkismanagedthroughaConnectPortX4gateway.
3. UsetheDigiESPforPythonIDEtobuild,download,andlaunchaniDigiDiaapplication
foryourConnectPortX4gateway,theninteractwiththeapplicationinarealisticsetting.
4. UsetheiDigiManagerProWebServicesConsoletosendawebservicerequesttothe
ConnectPortX4retrievingthecurrentXBeedevices’sensorreadings.
5. UsetheiDigiGatewayDevelopmentKitDemonstrationApplicationtounderstandhow
anEnterpriseapplicationcouldusetheiDigiWebServicesAPItomonitorthedata
gatheredbytheXBeedevices’sensors.
RequirementsoftheKit
SystemRequirements
ToinstallthesoftwarementionedintheGettingStartedGuide,youwillneedaPCrunning
MicrosoftWindowsXP,VistaorWindows7.
WebBrowserRequirements
MicrosoftInternetExplorer7.0ornewer
GoogleChrome4.0ornewer
MozillaFirefox3.0ornewer
AdditionalRequirements
ThisGettingStartGuideassumesascenariowheretherearenootherXBeewirelessdevicesin
thearea(otherthantheonesprovidedwiththiskit)andthatthelocalnetworkhasanInternet
connection.

Note:IfotherXBeenetworksarepresentandopenforjoining,theXBeeSensorandXBeeSmart
Plugmayjointhewrongnetwork.Pleaserefertothe“XBeedevicesfailtojointheConnectPort
X4’snetwork”sectionofAppendixA:Troubleshootingonpage60formoreinformation.
Downloaded from Elcodis.com electronic components distributor

iDigiGatewayDevelopmentKitGettingStartedGuide 7

Part1:SetupyourDigi®GatewayDevelopmentKit
Step1:KitPreparation
IdentifyYourKitComponents
Carefullyunpackandverifythecontentsofyourkit.Yourkitshouldincludeeachofthe
following:

Figure1:KitContents
DownloadtheDigi®DeviceDiscoveryApplication
Forproperkitconfigurationandoperation,theDigiDeviceDiscoveryApplicationmustbe
downloadedandinstalled.
TodownloadtheDigiDeviceDiscoveryApplication:
1. Navigatetohttp://www.digi.com/gatewaydevelopmentkitandthenclickonthe
“DownloadDigiDeviceDiscoveryApplication”link(withintheDocumentationtab).
2. Clickthe“Downloadyourfile”linkandthenfollowthepromptstoinstallthe
application.
Downloaded from Elcodis.com electronic components distributor

iDigiGatewayDevelopmentKitGettingStartedGuide 8

Step2:ConnecttheConnectPortX4®toyourLocalNetwork
TobeginsettingupyouriDigiGatewayDevelopmentKityouwillneedtoconnectandpoweron
theConnectPortX4,andformyourXBeenetwork.Todoso,followthesesteps:
Note:IfyouhaveadditionalXBee/ZigBeedevices,forthebestkitexperience,werecommend
thatyoupowerdownordisablejoiningonotherXBee/ZigBeePANsintheareabeforebeginning
thisstep.Ifyouareunabletodothisotherdevicesmightjointhekitnetworkandcreate
interferencewhendeployingyouriDigiDiaproject.Youcouldalsoencounterissuesconnecting
theXBeeSensorandXBeeSmartPlugtotheConnectPortX4astheyareconfiguredtojoinany
availablePAN.
1. RemovetheConnectPortX4fromtheboxandattachtheXBeeantennatothe
ConnectPortX4.
2. ConnectoneendoftheEthernetcabletotheConnectPortX4,andtheotherendtoyour
Ethernetswitch(asshownbelow).


Figure2:EthernetSwitch

WARNING:IftheConnectPortX4doesnothaveaccesstotheInternetthiskitcannotbe
completed.
Downloaded from Elcodis.com electronic components distributor

iDigiGatewayDevelopmentKitGettingStartedGuide 9

3. ConnectthepowersupplytotheConnectPortX4andthenplugthepowersupplyintoa
walloutlet.
Note:Thepowersupplyhasatwist‐lockingconnector,ensurethattheconnectoris
lockedintoplace.
4. RemovetheXBeeSmartPlugfromtheboxandplugitintoawalloutlet.ThegreenLED
willblinktoindicatethattheXBeeSmartPlugisassociatedwithanXBeenetwork.
5. Removethebatteries(3)fromtheboxandinstallthemintotheXBeeSensor(unscrew
thetwoscrewsontheXBeeSensortoinstallthebatteries).TheXBeeSensor’sASSCLED
willblinkwhenthedeviceisconnectedtoyourXBeenetwork.
Note:IfeitheroftheXBeedevicesfailstoblinkitsASSCLEDindicatingthatitisconnectedto
yourXBeenetwork,pleaserefertothe“IstheASSCLEDsolidgreen?”sectionofAppendix
A:Troubleshootingonpage60formoreinformation.

Figure3:SettingupyourConnectPortX4
Downloaded from Elcodis.com electronic components distributor

iDigiGatewayDevelopmentKitGettingStartedGuide 10

Step3:ConnectyourConnectPort®X4toiDigi®
TheiDigiplatformisanon‐demandhostedserviceplatformwithnoinfrastructurerequirements
fortheuser.TheiDigiplatformprovidesdevicemanagement,iDigiclientapplicationtoiDigi
devicedatainteraction(messaging),anddatastorageforanetworkcomprisedofbothwired
andwirelessDigiandthird‐partyGateways(callediDigidevices).TheiDigiplatformprovides
easyintegrationwithM2Mandmeshnetworkdevices.

First,beforeyoucanconnectyourConnectPortX4toiDigi,youmustcreateaniDigideveloper
account.

1. TosetupaniDigideveloperaccount:
a. Navigatetohttp://www.idigi.com.
b. ClickontheiDigiLoginbutton.

Figure4:iDigiHomePage
WanttolearnmoreaboutiDigi?
PleaserefertotheiDigiUser’sGuidewhichcan
befoundat
http://www.digi.com/gatewaydevelopmentkit

Downloaded from Elcodis.com electronic components distributor

iDigiGatewayDevelopmentKitGettingStartedGuide 11

c. IfyoudonotalreadyhaveaniDigideveloperaccount,clickonthe“Areyoua
newuser"linkandcreateyouraccount.
Ifyoualreadyhaveanaccount,loginandskipaheadtothe“Addthe
ConnectPortX4toyouriDigiinventory”sectiononthenextpage.

Figure5:iDigiLoginPage
ContinuefillinginallrequiredfieldsoftheiDigiRegistrationFormuntilyou
completetheiDigiRegistrationprocess.

Figure6:NewUserRegistrationPage
d. AftercompletingtheiDigiRegistrationprocess,youwillberedirectedtothe
iDigiLoginpage(refertoFigure5,above).EnteryouriDigiusercredentialsand
thenclicktheLoginbutton.

YouhavejustcompletedGoal#1:
CreatinganiDigideveloperaccounton
theiDigiM2Moperatingplatform.
Downloaded from Elcodis.com electronic components distributor

iDigiGatewayDevelopmentKitGettingStartedGuide 12

AddtheConnectPortX4®toyouriDigi®inventory
TheiDigiplatformallowsyoutosecurelymanagethedevicesinyourdeviceinventory.

1. ToaddtheConnectPortX4toyourinventory,followthesesteps:
a. SelecttheDeviceslinkintheLeftNavigationBar.
b. ClicktheAddDevicesbuttonintheToolBartoopentheAddDevices
applet.TheAddDevicesappletwilldiscovertheDigidevicesonyournetwork.
Note:Inordertodiscoverdevicesonyournetworkautomatically,theAddDevicesapplet
requiresJavaRuntimeEnvironment(JRE)1.6ornewer.
IfJavaRuntimeEnvironment(JRE)1.6isnotinstalled,youmustaddyourdevicemanually;
seethe“iDigiManagerProdoesnotdiscoveryourConnectPortX4”sectionofAppendixA:
Troubleshooting,onpage61formoreinformation.
c. SelectyourConnectPortX4fromthelist.Toverifythatyouareselectingthe
correctdevicefromthelist,matchtheMACaddresslistedonyourlabel(found
onthebottomofthedevice)withtheMACaddresslistedwithintheAdd
Devicesapplet.ClicktheOKbutton.

Figure7:AddDevicesApplet
Downloaded from Elcodis.com electronic components distributor

iDigiGatewayDevelopmentKitGettingStartedGuide 13

d. Waitabout60secondsthengobacktotheDeviceslistandclicktheRefresh
button.ThestatusofyourConnectPortX4shouldnowappearas“Connected.”

Figure8:iDigiDeviceInventory

Note:Ifthedevicestillappearsas‘Disconnected’afterclickingtheRefreshbutton,please
refertothe“’iDigiManagerProliststheConnectPortX4as‘Disconnected'”sectionof
AppendixA:Troubleshooting,onpage63formoreinformation.

Downloaded from Elcodis.com electronic components distributor

iDigiGatewayDevelopmentKitGettingStartedGuide 14

Step4:InstalltheDigiESP™forPythonDevelopment
Environment
TheDigiESPforPythonDevelopmentEnvironmentisanEclipse‐basedIntegratedDevelopment
Environment(IDE)thatsimplifiestheprocessofcreatingPythonapplicationsforiDigidevices.It
alsoprovidesmanyexampleprojects,oneofwhichwewillbeusinglaterinthissection.
TodownloadandinstalltheDigiESPforPythonDevelopmentEnvironment:
1. Navigatetohttp://www.digi.com/gatewaydevelopmentkitandclickonthe“Download
DigiESPforPython”link.
2. YouwillberedirectedtothePythonProductpage.Thevariousdownloadoptionsfor
theDigiESPforPythonframeworkwillbedisplayedonthispage.Clickonthe“DigiESP
forPython‐WindowsXP/Vista/Windows7installerver.1.2.0.5”linktodownloadthe
DigiESPforPythonDevelopmentEnvironment.
Note:MacoperatingsystemsarenotsupportedinthisDevelopmentKitexperience.

Figure9:SelectDigiESPforPythonDownloadVariant
Downloaded from Elcodis.com electronic components distributor

iDigiGatewayDevelopmentKitGettingStartedGuide 15

3. OncetheDigiESPforPythonframeworkhasbeendownloaded,runtheDigiESPfor
Pythonframeworkinstallationwizard.Followthestepsinthewizardtocompletethe
installationprocess.ClickFinishattheendoftheinstallation.
Note:ApromptwillaskyouifyouwouldliketoopentheReleaseNotesassociatedwith
theDigiESPforPythonframework,deselectthischeckbox.
4. TheDigiESPforPythonframeworkwilllaunchautomaticallyandpromptyoutoselecta
workspacedirectory.Usethedefaultworkspacedirectory(orclicktheBrowsebutton
andnavigatetoyourdesiredalternateworkspacelocation),checkthe“Usethisasthe
defaultanddonotaskagain”box,andclickOK.
Note:TheDigiESPforPythonframework'workspace'isthedirectorywhereprojectsand
configurationswillbestored.Thedefaultlocationforthisdirectoryisasubfoldercalled
workspaceontheuserhomedirectory,forexample,C:/Documentsand
Settings/[username]/workspace.

Figure10:SelectingyourDigiESPforPythonWorkspace
Downloaded from Elcodis.com electronic components distributor

iDigiGatewayDevelopmentKitGettingStartedGuide 16

5. ThefirsttimeyourunDigiESPforPythontheWelcomescreenisdisplayed.

Figure11:DigiESPforPythonWelcomeScreen
6. OpentheDigiESPforPythonWorkbenchbyclickingontheWorkbenchicon(as
indicatedabove).

Figure12:DigiESPforPythonWorkbench
Downloaded from Elcodis.com electronic components distributor

iDigiGatewayDevelopmentKitGettingStartedGuide 17

Step5:CreateyourfirstiDigi®DiaProject
TheiDigiDia(DeviceIntegrationApplication)issoftwarewritteninPythonthatsimplifiesthe
taskofgatheringdatafromattacheddevices(suchasXBeeSensors),andsendingthegathered
datatoiDigi,allowingforeasyintegrationwithclientapplicationsusingtheiDigiWebServices
APItoaccessit.

Thestepsinthissectionwillhelpyoubuild,download,andlaunchyourfirstiDigiDiaapplication.

TheresultingiDigiDiaapplicationwillcontaindriversfortheXBeeSensorandXBeeSmartPlug.
TheapplicationwillalsobeconfiguredtoreportitsdatausingtheRCIpresentationforaccess
withiDigiWebServices(whichwillbedemonstratedlaterinthisguide).

TobegincreatingyourfirstiDigiDiaproject:
1. OpentheiDigiDiaProjectWizardbyclickingFile>New>iDigiDiaProjectfromtheFile
menu.

Figure13:SelectinganiDigiDiaSampleProject
Downloaded from Elcodis.com electronic components distributor

iDigiGatewayDevelopmentKitGettingStartedGuide 18

2. Themainwizardpagecontainsatextboxtoinsertthenameoftheprojecttobe
created;nameyourproject.Thisexampleusesaprojectnameof“Demo_Project1”but
youcanchooseanyuniquename.Oncetheprojectnamehasbeenprovided,clickNext.

Figure14:NameyouriDigiDiaProject
Downloaded from Elcodis.com electronic components distributor

iDigiGatewayDevelopmentKitGettingStartedGuide 19

3. WithintheRemoteDeviceselectionwizardpageensurethatUseCurrentRemote
Configurationisselected,andthenclicktheNew…buttontocreateanewremote
configuration.

Figure15:CreateNewConfiguration
AnewRemoteDeviceConfigurationisneededtoworkwitheachspecifictargetdevice
(yourConnectPortX4inthiscase).Multipleremoteconfigurationscanbecreatedfor
workingwithdifferentdevices.
Downloaded from Elcodis.com electronic components distributor

iDigiGatewayDevelopmentKitGettingStartedGuide 20

a. AfterclickingtheNew…button,theDeviceManagerwizarddialogwillopen.
Figure16:DeviceManagerHomePage
Note:TheleftsideofthedialogliststheRemoteConfigurationsthatexistintheWorkbench.
b. Initially,therearenoRemoteConfigurationslistedintheDeviceManager.Tobegin
theprocessofcreatingyourfirstRemoteConfiguration,enabletheDeviceManager
todiscovertheConnectPortX4automaticallybyclickingtheDeviceDiscovery
button.
Downloaded from Elcodis.com electronic components distributor