FAQ: Mapping your ZigBee network with Digi's XCTU

I have had several request about how I map my ZigBee network with Digi’s XCTU software so I thought I would share a quick how to:

Caution: This is not a Digi supported procedure if something goes wrong during the firmware upgrade you could brick your Digi USB xStick and have to send it back to Digi to be recovered.

What is this and why would you want to do it?

ZigBee mesh networks are self configuring and self healing and in larger networks it helps to know what nodes are routing who’s information. You can’t really control the network configuration but it helps to see the relationship between your nodes if your troubleshooting a connection problem.

The screen capture below is how my SmartThings ZigBee network looks when it is mapped out by the XCTU software. The SmartThings hub is the red C (coordinator) and the other devices with an R are ZigBee routers and E are ZigBee end nodes. If I log into my SmartThings IDE and look at “my devices” under the “Zigbee Id” column I can lookup each device’s ZigBee address. For example the end node device 000D6F00032A0F17 is my SmartSense Open/Closed sensor, and I can see it is connected directly to the SmartThings hub with good signal strength.

What this isn’t

This is not a ZigBee protocol analyzer. You can not see the ZigBee traffic between your nodes it simply maps out the routing table held by each ZigBee device on your network. Protocol analyzers are expensive and give you massive amounts of information that is really only useful to a device engineer or low level programmer.

This is also not going to tell you one single thing about your Z-Wave network. There is a fair chance a lot of your devices are Z-Wave so don’t expect it to map those devices.

Setting it all up

You will need a Windows workstation with an available USB port. In my case I’m using Windows 7 but I think it will work on 10. You need to buy a Digi USB dongle and download and install the XCTU application. The USB dongle will be sent to you with a generic configuration and the SmartThings hub will not allow it to join the network. It must be configured with the proper security settings and the correct trust center link key for the ZigBee Home Automation profile. Once the USB dongle has the correct configuration the SmartThings hub will allow it to join as a “thing”. Here are the steps at a high level:

  1. Install your XCTU software and plug in your USB dongle. Open the XCTU program and click on the scan icon to find your USB dongle.

  2. You will need to make sure the radio firmware on the USB dongle is set to XB24-ZB, ZigBee Router API, 23A7 as shown below:

  3. Once the firmware update is complete you will now need to update the security settings of the radio so it is compatible with SmartThings. Download the XML configuration file form my CoopBoss.com web site and copy it to your local hard drive. Now click on Load configuration file (the little down arrow by the person icon) and write it to your USB dongle by clicking on the pencil icon.

  4. Open your ZigBee network for joining by going to SmartThings on your smartphone and click on Connect New Device. At this point your USB dongle is looking for a valid ZigBee home automation network to join and you can see the status of this quest by scrolling down to the Diagnostic Commands and look at the AI (Association Indication) parameter. You should see a 21 or 23 or FF they all basically say it is looking for a network to join. When it reads 0 you have joined a valid ZigBee network and can start mapping out the nodes.

29 Likes

Very cool FAQ man!!!

4 Likes

This is really cool. Does anyone know if we can re-route a path manually instead of letting the network heal it self? Would that be possible through this software?

It is possible for a mains powered device (ZigBee router) to use “Source Routing” when sending a ZigBee packet. A Source routed packet includes the entire route the packet should traverse to get from source to destination. However that is done at the packet level by the device. This is usually for very special use cases and the change has to be made in the firmware of the device. The XCTU program is pretty passive it just reads the routing tables of the ZigBee routers. It can’t be used to redefine your routing.

As a side note the SmartThings Hub uses Many-to-One Routing. It periodically broadcast a packet that triggers all ZigBee routers to update their routing table with the most efficient route to the hub. This insures all ZigBee routers have a fresh accurate route to the hub. In my experience SmartThings has nailed the ZigBee routing, my network has been rock solid.

ZigBee end nodes (battery powered devices) don’t do any routing or know anything about the network’s routes. They simply know who their parent is (ZigBee router or coordinator) and connect to it to send and receive data. If they can’t connect to their parent or their parent has orphaned them because they didn’t check in they will have to reconnect. Sometimes if two ZigBee routers are close to the same child it may jump back and forth between the two routers when it reconnects. The trick here is to not make it go through a reconnect process. If it does it usually isn’t a problem your network typology will just change when it moves from one router to another. However, a child device that has to reconnect often will have poor battery life.

I’m curious, why do you want to change your ZigBee routing?

Not really interested in changing the routing, but was keen to know if thats possible. Thanks for all the good information.

Tried this out… And its really cool!! Thanks for sharing. I mapped my Zigbee network…a good insight…considering I am a RF Engineer …Will be exploring this tool more.

2 Likes

It’s interesting to hear this because it hasn’t been my experience (nor other’s, according to what I’ve read on the forums). In fact, just the other day I left my hub unplugged for a while to let the zigbee network rebuild since a new plug I had added a couple days before didn’t seem to extend the range like I had hoped. After this I started getting better presence sensor range in the direction that I had added the plug.

Do you have any details on how often the routing tables are updated?

@JohnR Do you know why would all end points not show up when I run the mapping tool? I have about 7-8 battery operated sensors and only 2 show up on the mapping tool. All the Routers show up as expected.

1 Like

No I don’t, I have seen that on my network too. I suspect it has something to do with the location of your USB fob in respect to the end nodes. The nodes that don’t show up on my map are connected to ZigBee routers that are more than one hop away from my USB fob. It also seems to report more of them over time. It would take a sniffer to really see what is going on.

I mostly use it to map my routers and to troubleshoot devices I’m working on.

1 Like

Let me walk around in my house and see… if that changes.

1 Like

The formation of the ZigBee network has nothing to do with the Many-to-One routing packet that is sent out by the coordinator. The goal of a Many-to-One route packet is to make sure the routers have a fresh route to the hub. What that route is depends on how the ZigBee network is formed.

Here is a screen shot of two Many to One Route Request packets broadcast by my hub, they were one minute apart. That’s just an observation on my network. I’m not saying everyone’s hub does the same thing. I just know both my hubs V1 and V2 send these packets out.

@ashutosh1982 should see the same thing. Ashutosh, if you get a chance click on the terminal tab of the xctu and start recording packets. You will receive all packets that are sent as broadcast. I’m curious if you get the same Many to One Route Request I see?

Yes I see that as well. Screenshot below

I found another interesting thing. I would like to hear your thoughts. See the picture below. The Device with ID 000D6F0002C8375C is Spruce and this confirms that it is acting like a repeater to my Garage Shutter Sensor which is ID D052A8008E570003 and my Wet Bar Fridge Contact which is ID000D6F0003FECC10. The problem is that these are the only zigbee end point devices that do not report their state correctly - I’ve been noticing since Spruce Installation that my garage fails to report open state or close state and is stuck in incorrect state - I have noticed the same with the wet bar fridge contact .The common factor I’ve seen is that the router is Spruce Irrigation Controller.

What would be a better way to troubleshoot this. There is another router before Spruce which is a Cree Bulb… Not sure where the problem is. Any ideas to troubleshoot this? @JohnR

Someone ( @sticks18 maybe? ) has previously posted that Cree has some firmware problems with regard to ZHA repeating, Making it an unreliable agent. They can be a problem when acting as a designated parent. (It’s also possible I read this on another forum.)

You could try just removing the Cree and see if that helps. Or if necessary, replacing it with a Hue or an Osram Lightify.

1 Like

I would focus on your Spruce router at 0x000D6f0002c8375c first. It looks like it has a lot of connections as well as the two sensors. I wonder if the sensors are on the fringe of coverage and the router is not being very attentive to them. I would try having these devices connect to another ZigBee router. You could try turning off the Spruce router and see if another router is withing range and will pickup up the two end devices. If that doesn’t work you could move your SmartThings Hub closer to the two end devices and test.

JD brings up a good point on the Cree Bulb but if you were having problems with it the Spruce Irrigation device would be having problems as well.

2 Likes

I will try shutting the Cree bulb off and see if that helps. Will keep you guys posted.

2 Likes

Hello can anybody help with a query. I have set up my zigbee S2 with the configuration file posted above now my zigbee is displayed on the deCONZ screen but nothing on the web app. Also can anyone tell me how can i send messages using python to other zigbee devices(routers/ endpoints) connected to RaspBee coordinator

@nikhilupadhyay,
Once you get your xBee connected to the SmartThings HA network (following the steps outlined in the above thread) your journey has just begun.

From high level, to get your device to register itself with SmartThings it should follow these steps:

  1. Your device sends a device announce to the hub when powered on. See ZDO Cluster 0x0013 for details.
  2. SmartThings receives the device announce and sends packets querying your device for a list of end points and supported clusters. See ZDO clusters 0x0005 and 0x0004 for details.
  3. Your device responds to the above request with a list of end points and supported clusters. ZDO cluster 0x8005 and 0x8004 should be sent in response to the two packets sent in step 2 above.
  4. SmartThings uses this list of supported clusters and endpoints to match your device to a device type that has a matching footprint.
  5. If SmartThings finds a footprint match it will add it to your device with the name associated to the matching device type. If there is not a match SmartThings will add your device as a thing.

So if your not following the above steps that is why your device is not showing up in your “my devices” section of the IDE. To send commands to other devices you use ZigBee cluster commands. They are outlined in the ZigBee cluster library at ZigBee.org.

Resources:
To send ZigBee Device Object (ZDO) commands with an xBee see the ZDO transmissions section on page 84 of the xBee’s manual. You can find more information on ZDO commands in the ZigBee Specification.

To send public ZigBee Cluster commands see the section “Sending Public Profile Commands with the API” on page 179 of the xBee’s manual. For a complete listing of public cluster commands see the ZigBee Cluster Library Specification.

As you can see this is not a trivial process and the first step may be to create a C library you can call to send the packets to the xBee. Are you sure an xBee is the right chip for you? I think dresden-elektronik in Germany may have a solution based on their radio with a ZigBee library ready to go. Another route you may want to explore is to talk to the SmartThings hub over WiFi instead of ZigBee. ZigBee is designed for small devices that normally don’t have a operating system like a Pi.

1 Like

Thanks for the reply JohnR.
Here is the thing I have worked with networks created by simple xbee S2 devices, in API mode and sent and received commands to them through Python-xbee library on raspberry pi, now what i want is to use dresde-elektroni’s device to act as coordinator and through python codes send and receive commands to other xbee devices present in the network. But it seems python-xbee library is not compatible with derfMega256. So please could you direct me to proper texts or help me out with sending and receiving data using derfmega 256 (from deCONZ) configured as coordinator.

Man did I misunderstand your question. Sounds like what your doing has nothing to do with SmartThings.

1 Like