README.md

Disclaimer: If you are under NDA with ZenSYS, although I wish I could, I cannot use your input. I want this to be an open definition of ZWave clear of NDA.

If you are not under NDA and you see any errors or have anything to add I welcome your input. I will be glad to incorporate any pull requests you may offer or review any issues you choose to create.

ZWave Serial API Sniffing Journal

These are my notes About ZWave mostly compiled with RaZberry, Open ZWave, and a lot of Google-ing. See the bottom of this file for a list of the most helpful resources that are not inline linked.

Updates

2014 Aug 18 - HackRF has arrived and now I have raw RF 908.42 MHz samples of ZWave devices. Next step is to work on GFSK decoder.

2013 Aug 13 - I am now backing the HackRF on KickStarter. The goal is to apply my learnings to decoding the RF part of ZWave.

I have been asked why am I doing this. My answer is two fold:

I want to make sure that my new favorite technology is secure. I don't want someone able to unlock my door because I am using ZWave. I feel I can accomplish this more throughly if I am open about my knowledge and others are open about theirs.

I Want to be able to do things that currently are not available in any of the ZWave services. First I want to fully understand ZWave then I want to create cool apps and hardware that leverage that knowledge.

Questions To Be Answered:

Now I feel I have a good grasp on the Application Layer Serial protocol and just need to finish documenting it. Here are some of my next big questions:

How can I get the ZWave ZM3102 into "promiscuous" mode so I can see all OTA traffic?

How hard would it be to make my own OTA sniffer?

Can I take apart a zwave device and repurpose it as a sniffer?

I have found some views from ZNiffer on Youtube. How can I get more examples of decoded ZWave to verify my decodes are accurate?

There are a lot of really cruddy databases of ZWave devices. Should I create one that is maintainable by the community?

RaZberry

A RaZberry hardware solution is a combination of the [Raspberry Pi] 2 motherboard and the [RaZberry] 2 Z-Wave transceiver daughter board. The daughter board is connected to the mother-board using the General IO Pin header connector of Raspberry PI. This GPIO interface offers Serial TX and RX signals, ground and 3.3 V VCC to power the Z-Wave transceiver board.

The RaZberry uses the ZM3102 Z-Wave transceiver from [SIGMA DESIGNS] 4. This module combines a "System on Chip" (SOC) with a 8051 micro controller, the Z-Wave transceiver and some IO interfaces the systems crystal and the SAW antenna filter.

The micro controller of the SOC contains control code that operates the wireless transceiver and handles certain network level operations of Z-Wave. The communication with this code runs over the serial interface. There is a protocol specification for this interface that is issued by the
Manufacturer of the Z-Wave chip Sigma Designs that most of the [Z-Wave transceivers] 5 on the market (e.g., USB Sticks) use. This interface specification — called Sigma Designs Serial API - is not a public document but available under Non Disclosure Agreement only as part of the Sigma Designs Systems Development Kit (SDK). The firmware of RaZberry is based on the SDK Version 4.54 but has enhanced the Sigma Designs Serial API in several ways.

Almond+

I am a backer at the life-time service level of the KickStarter project [Almond+] 6. I can't wait to get my hands on this product. I have very high hopes for this project.

ZWave

Thanks to the folks over at the OpenZwave project I found out that the basis of ZWave is an ITU standard. A little Googling and it appears the standard of interest is ITU-T G.9959 (http://www.itu.int/rec/T-REC-G.9959/en).

Have I mentioned that I love the project Open-ZWave?

Thoughts on Application Design

I have written my fair share of Wireshark dissectors but I have always had Wireshark to do the display of those captures.

Creating a ZWave sniffer will require the dissector but it will also require some user interface. This may be best split into to project. Similar to TShark (or tcpdump) that does the capture and the user interface application. Initially the UI will just dump to the console or to a file.

or

Maybe I can sort out someway to save the capture in PCAP format and still use Wireshark to decode it?

Future Goals

I would like to make a ZWave decoder that will monitor the serial line and output human readable information about what is being sent.

Device Classes

To allow inter-operability between different Z-Wave devices from different manufacturers, each device must include certain well-defined functions above and beyond the ‘Basic’ command class.

These requirements are called ‘Device Classes’. A device class refers to a typical device and defines which command classes that are mandatory for it to support.

Device classes are organized into a three-layer hierarchy:

Every device must belong to a basic device class
Devices can be further specified by assigning them to a generic device class
Further functionality can be defined by assigning the device to a specific device class
Basic Device Class
The ‘Basic’ device class simply defines a device as a Controller, Slave or Routing Slave. Therefore every device belongs to one basic device class.

Generic Device Class
The ‘Generic’ device class defines the basic functionality that the devices will support as a controller or slave. Current ‘Generic’ device classes are:

Hex Value

Value

Description

Key

0x01

1

General controller

BASIC TYPE CONTROLLER

0x02

2

Static cont roller

STATIC CONTROLLER

0x03

3

BASIC TYPE SLAVE

0x04

4

BASIC TYPE ROUTING SLAVE

0x08

8

Thermostat

GENERIC TYPE THERMOSTAT

0x10

16

Binary switch

BINARY SWITCH

0x11

17

Multi level switch

MULTI LEVEL SWITCH

0x12

18

GENERIC TYPE SWITCH REMOTE

0x13

19

GENERIC TYPE SWITCH TOGGLE

0x17

23

GENERIC TYPE SECURITY PANEL

0x20

32

Binary sensor

BINARY SENSOR

0x21

33

Multilevel-Sensor

MULTILEVEL SENSOR

0x31

49

Meter

METER

64

GENERIC TYPE ENTRY CONTROL

Specific Device Class

Assigning a ‘Specific’ device class to a Z-Wave device allows it to further specify its functionality. Each ‘Generic’ device class refers to a number of specific device classes. You can decide to assign a specific device class, however, it only makes sense if the device really supports all functions of a ‘Specific’ device class.

Table: 0x01 – 0x1F ZWave Protocol Commands

Name

Hex

Dec

NO OPERATION

0x00

0

NODE INFO

0x01

1

REQUEST NODE INFO

0x02

2

ASSIGN IDS

0x03

3

FIND NODES IN RANGE

0x04

4

GET NODES IN RANGE

0x05

5

RANGE INFO

0x06

6

CMD COMPLETE

0x07

7

TRANSFER PRESENTATION

0x08

8

TRANSFER NODE INFO

0x09

9

TRANSFER RANGE INFO

0x0A

10

TRANSFER END

0x0B

11

ASSIGN RETURN ROUTE

0x0C

12

NEW NODE REGISTERED

0x0D

13

NEW RANGE REGISTERED

0x0E

14

TRANSFER NEW PRIMARY COMPLETE

0x0F

15

AUTOMATIC CONTROLLER UPDATE START

0x10

16

SUC NODE ID

0x11

17

SET SUC

0x12

18

SET SUC ACK

0x13

19

ASSIGN SUC RETURN ROUTE

0x14

20

STATIC ROUTE REQUEST

0x15

21

LOST

0x16

22

ACCEPT LOST

0x17

23

NOP POWER

0x18

24

RESERVE NODE IDS

0x19

25

RESERVED IDS

0x1A

26

UNKNOWN

0x1B-0x1F

27-31

Table: ZWave Command Classes

A Command Class can contain up to 255 different Commands.

NOTE:If the Command Class field is set to 0xF1 - 0xFF then there is another Command Class byte added. This allows for future extensions of the Command Classes. The strategy of having an Extended Command Class followed by the actual command identifier provides the possibility of having more than 4000 Command Classes.