Zniffer File HowTo

Z-Wave developers have a handy tool for debugging firmware and Z-Wave network issues called the Zniffer. The Zniffer consists of two parts, the first is a USB dongle with special firmware and the second is the Windows program. You can’t buy just a Zniffer USB dongle (they come as part of some of the developers kits) but you can make one out of a standard UZB. You can even make a SuperZniffer as described in my previous blog posting. The Zniffer program is included in the Simplicity Studio IDE tools for developing Z-Wave products.

Zniffer traces are INVALUABLE when submiting a support case to the Silicon Labs Z-Wave support web site. I am an Field Applications Engineer so I often review Zniffer traces captured by developers who have questions or are reporting bugs. The problem is that many times I get a support case that says “Zniffer trace attached – what is problem?” and the Zniffer trace is several hundred megabytes with dozens of Z-Wave networks and maybe one hundred Z-Wave nodes captured across days of time. Talk about the proverbial needle in a haystack! So I am asking everyone to follow a few rules BEFORE attaching a Zniffer trace to a support case.

Zniffer File Rules

Before attaching a Zniffer file for Z-Wave support to review, include the following:

  1. The HomeID of the network with the problem
  2. The NodeID of the Z-Wave node that demonstrates the problem
  3. The line number or the date/time of the where the problem occurred (or a range)
  4. The Security Keys of the Z-Wave network
  5. A clear and concise description of the problem, what should have happened, what didn’t happen, what you believe is wrong

ZnifferHowTo1

HomeID

The HomeID of a Z-Wave network is a 4 byte, eight digit hexadecimal number that uniquely identifies a single Z-Wave network. Only devices with the same HomeID can talk to each other. In a development environment there are often dozens or even hundreds of Z-Wave networks in range. Remember the Zniffer captures every network in the air. Please do not filter the HomeID when saving out the Zniffer file as there may be critical interactions with other network or even noise that will be filtered out if you save only the matching HomeID. We can always filter by HomeID when displaying the network on our PC but we can’t see the data if its not in the file.

NodeID

The NodeID of the node that is displaying the issue has to be identified. You might have dozens of nodes in the network who are all talking at once so we need to know which one is the one with the problem. Please include details of the device as well such as what type it is (binary switch, thermostat, sensor, battery powered, etc) . Ideally if you can include the device within the zniffer file that will tell us just about everything we need to know as the NIF will be exchanged and the interview will take place.

Date/Time

Each transaction in the Zniffer trace is identified by a line number on the left side or the date/time. Indicating the line number or date/time or a range of these will help us navigate the potentially huge Zniffer file and quickly zoom in on the problem. Wading thru days of Zniffer data to finally find the interesting bit is just wasting our time and yours.

Security Keys

If you are working with Secure devices you MUST include the security keys. Without the security keys the data is encrypted and it is all just meaningless ones and zeroes and we can’t help you. Now that all devices are required to be secure, the key file is critical. The Zniffer trace has to include the SPAN table update as without the SPAN table we again cannot decrypt the message. The easiest way to be sure the SPAN is included is to add the device-under-test (DUT) to the network while capturing the Zniffer trace. The other option is to power cycle the DUT which will usually cause the DUT and the controller to exchange Nonces to resynchronize the SPAN table and we can once again decrypt the messages in the Zniffer.

To extract the security keys, join the PC Controller to the Z-Wave network. Be sure to enable all levels of security by providing the S2 DSK of the PC Controller. Once joined to the network, the keys can be saved to a file using the procedure below:

ZnifferHowTo2

The filename is the HomeID.txt which in the case above is FFE5B5C9.txt and contains:

9F;C592557B5F99DDC9BDD12D0D926BAFE5;1
9F;31944FE8F8DE2330E79741313A949190;1
9F;18FD847446AFD7E410B2BCF8912BC632;1
98;C65D55C44FB2156635CA07A48D362AD3;1

To decyrpt the messages in the Zniffer, just click on Load Keys and enter the directory for the file. Then all the messages are decrypted and we can help you solve your problem.

13 thoughts on “Zniffer File HowTo

  1. staze January 11, 2020 / 8:50 pm

    Hi there. I’m trying to troubleshoot a z-wave issue (lock talking to hubitat), and I can’t get the security keys to actually work. I’ve got two zwave sticks, one standard for use with Zwave Controller. One flashed to Zniffer. Extracting the security keys using PC Controller using standard Zwave stick doesn’t allow decryption of packets in Zniffer, which I’m guessing is because the DSK for the two keys is different? Maybe I’m not understanding the process well enough.

    I don’t seem to have any way to join Zniffer to my mesh, and I don’t think that’s needed. I’m just not sure how to proceed. This post is the best info I’ve found for doing any of this.

    Thanks!

    Like

    • DrZWave January 11, 2020 / 9:24 pm

      Use the PC Controller to join the network. Then click on the shield icon in the upper right corner, then click on SAVE. The keys will be stored into a text file which the name of the file is HomeID.txt (The HomeID is an 8 hex digit number). The Zniffer does not join the network, it just uses the keys from the PC Controller.
      Once the keys are saved (best place is on your desktop as that is the default place the Zniffer will work), then you can click on an encrypted frame and then Load Keys. The frame should be decrypted. If it is not, then you may not have the SPAN table in the capture. The easiest way to make sure to get the SPAN table is to power cycle the device you are working with. Usually it will negotiate a new SPAN when powered up and if the Zniffer is running it will capture it. Once captured, the zniffer should decrypt all the frames.
      Note that the diffe-Helman key exchange cannot be decrypted but you should not need to do that anyway.
      Make sure you have the latest version of both PC controller and Zniffer which are now released thru Simplicity Studio and not on the web. There was a version of the Zniffer earlier in 2019 that could not decrypt routed frames.

      Like

      • staze January 11, 2020 / 11:03 pm

        Okay, I think I’m still missing something.

        Do I only need the one zwave usb stick (the zniffer) or a second one? If I just have the zniffer connected when I launch PC Controller, it won’t let me click the shield to save out the keys. But if I have my other zwave stick plugged in, that’s joined to the network, it can save out the keys. But, those keys don’t seem to work to decrypt traffic.

        I am using the versions through Simplicity Studio.

        What does the SPAN table look like (will it be in the trace)? Maybe I’m trying to decrypt that… The lock just shows transmitting “Security Nonce Get” packets, and “Security Message Encapsulation Message”, and these are the ones that don’t decrypt with the keys I got from the other stick.

        Happy to provide a trace and all if that would help figure out what the heck is going on. Clearly missing one step. Maybe my Zniffer stick has an old firmware (that was hard to find, and seems to say it’s version 2.55).

        Like

  2. staze January 11, 2020 / 11:19 pm

    If it helps, DUT is non-Zwave Plus (Schlage BE469). Not sure if that alters the process for decryption.

    Like

  3. DrZWave January 12, 2020 / 12:01 am

    The schlage lock is S0 so there are no SPAN tables as each frame requires its own Nonce Get/ Nonce Report. SPAN tables are only for Security S2.

    One UZB with the standard Static Controller (or bridge) library is needed for the PC Controller.
    The other UZB with the Zniffer firmware is needed for the Zniffer.

    You have to select the correct COM port for each program. The Zniffer will search for Zniffer firmware “Capture->Detect Zniffer Modules”. The PC controller isn’t as good at looking for the correct COM port. You have to choose the right one for it.

    If you’re getting Nonce GET frames then the zniffer must be working.
    For S0 you can also just copy the S0 key out of the PC Controller and paste it into the Decrypt Message box.

    Liked by 1 person

    • staze January 12, 2020 / 12:09 am

      Yeah, then something is broken/not working. If I give it (Zniffer) the S0 key (straight out of PC Controller) it just says “Incorrect Key”. It’s seeing plenty of traffic. So Zniffer is working. I just seem to have a wrong S0 Key. But each program works. I even tried keeping both running and that didn’t seem to make a difference either. =/ Anything else that could be it or that I may be missing?

      Like

      • staze January 12, 2020 / 11:59 pm

        Could it be that the secondary controller isn’t having the proper keys shared with it (maybe it’s doing an insecure join), and therefore doesn’t have the proper keys to decrypt the traffic?

        Like

  4. DrZWave January 13, 2020 / 12:10 am

    Anything is possible…
    You will know if the PC Controller is joined if all the devices show up in it. You should be able to control the lock from the PC Controller.

    Like

    • staze January 13, 2020 / 12:18 am

      Hmm… I see on/off commands, but not sure “lock” and “unlock” correspond to that. Would I have to send a custom command to the lock?

      Like

      • DrZWave January 13, 2020 / 2:00 am

        The PC Controller can send any command class command. Click on the DUT and then the {…} icon and then select DoorLock CC.

        Liked by 1 person

      • staze January 13, 2020 / 2:11 am

        hmm… clicked {…}. Then “select”, under Command_Class_Door_lock ver.1 (had to have it show all commands), I say “door lock operation set” then “Door_Unsecured” or “Door_Secured”. Then send? I tried a “Get” and “Report” and I don’t see how to show the resulting response. The set did nothing. =/ I’ll have to look at documentation some more…

        Like

  5. Demetrianos January 21, 2020 / 10:47 am

    Hello! I am having trouble with the z-wave zniffer tool. I have included my aeotec z-wave stick as a secondary controller to my smartthings hub and PC Controller seems to work fine. However, zniffer tool does not work properly. When I hit the “Capture->Detect Zniffer Modules” nothing appears on the screen. It says “Detect” but it does not detect anything. I am using the latest versions through Simplicity Studio.

    Like

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s