WiSense Sensor data format

In this post, I am going to go over the format in which WiSense sensor nodes send sensor data. The format utilizes TLV objects. Each TLV object  comprises a fixed length type field, a fixed length field and a variable length value field. For example, a node uses the “sensor-id” TLV to convey the specific sensor to which the associated data belongs. The TLV looks like this –

  •     Type field:  0x14
  •     Length field:  0x1
  •     Value field:  0x9

The TLV occupies 3 bytes within a message. The value of the type field is ox14 which identifies this as “sensor id” TLV. The length field of this TLV has a value of 1 and the value field of this TLV is 0x9 which implies that this an LM75B sensor.

The value of the length field indicates the length of the subsequent TLV value field. The total length of a TLV object is the sum of the length of it’s three fields (1 byte (type field) + 1 byte (length field) + N bytes (value field) = (2 + N) bytes). Since the size of the length field is only 1 byte, N can be at most 255 bytes.

The length of the type field is also 1 byte. This restricts the max number of TLV types to 256. In OOP terminology, the maximum number of classes possible is 256. We could increase the TLV type field to 2 bytes but this would increase the overhead.

Let us look at another TLV (the sensor data value TLV) below.

  •     Type field:  0x2
  •     Length field:  0x2
  •     Value field:  0x001a

This TLV above is used to convey sensor output. In this example, the length field is 2 bytes which means the value field of the TLV is a 16 bit number. The value field in this example is 26 (0x1a). The type field value is 0x2 which identifies this as a “sensor output” TLV.

All TLV objects sent/received by WiSense nodes always have a 1 byte TLV type field and 1 byte TLV length field. The TLV value field is variable and it’s length is indicated by the value of the TLV length field.

You can think of the TLV type field as a class identifier. You can instantiate multiple instances of a TLV within a message.

TLV’s can encapsulate TLVs. A TLV which contains one more more TLVs is called a compound TLV. A TLV which does not contain any TLVs is called a simple TLV.

Let us take a look at an actual message sent by a sensor node to the coordinator which forwards this message to an app running on a PC connected to the coordinator over the serial interface.

The message byte sequence is –

0x3 0x10 0xf 0x11 0xd 0x14 0x1 0x9 0x2 0x2 0x00 0x1a 0x3 0x1 0x7 0x4 0x1 0x6

0x3 (DIS_MSG_TYPE_SENSOR_OUTPUT)

  • 1 byte type: 0x10 (DIS_TLV_TYPE_SENSOR_OUTPUT_LIST)
  • 1 byte length:  0x1e (30)
  • 30 bytes long value field:
    •     1 byte type: 0x11 (DIS_TLV_TYPE_SENSOR_OUTPUT)
    •     1 byte length: 0xd (13) 
    •     13 bytes long value field: 
      •          1 byte type: 0x14 (DIS_TLV_TYPE_SENSOR_ID)
      •          1 byte length: 0x1
      •          1 byte value: 0x9 (LM75B sensor #1)
      •          1 byte type: 0x2 (DIS_TLV_TYPE_VALUE)
      •          1 byte length: 0x2 
      •          2 byte value: 0x001a (26 deg Celcius)
      •          1 byte type: 0x3 (DIS_TLV_TYPE_DATA_UNIT)
      •          1 byte length: 0x1
      •          1 byte value: 0x7 ( DIS_DATA_UNIT_CELCIUS)
      •          1 byte type: 0x4 (DIS_TLV_TYPE_DATA_SCALE_FACTOR)
      •          1 byte length: 0x1
      •          1 byte value: 0x6 (DIS_DATA_SCALE_NONE)
    •    1 byte type: 0x11 (DIS_TLV_TYPE_SENSOR_OUTPUT)
    •    1 byte length: 0xd (13)  
    •    13 bytes long value field:
      •          1 byte type: 0x14 (DIS_TLV_TYPE_SENSOR_ID)
      •          1 byte length: 0x1
      •          1 byte value: 0x12 (TSL45315 light sensor #1)
      •          1 byte type: 0x2 (DIS_TLV_TYPE_VALUE)
      •          1 byte length: 0x4 
      •          2 byte value: 0x0000c350 (50000 Lux)
      •          1 byte type: 0x3 (DIS_TLV_TYPE_DATA_UNIT)
      •          1 byte length: 0x1
      •          1 byte value: 0xd ( DIS_DATA_UNIT_LUX)
      •          1 byte type: 0x4 (DIS_TLV_TYPE_DATA_SCALE_FACTOR)
      •          1 byte length: 0x1
      •          1 byte value: 0x6 (DIS_DATA_SCALE_NONE)

In this message, the first byte is 0x3 which indicates that this message conveys the output of one or more sensors located on the sending node.

The second byte is the start of the “DIS_TLV_TYPE_SENSOR_OUTPUT_LIST” TLV. This is a compound TLV. It can contains one or more TLVs of type “DIS_TLV_TYPE_SENSOR_OUTPUT“. In this example, the node is sending the output of two sensors, as a result the “DIS_TLV_TYPE_SENSOR_OUTPUT_LIST” TLV contains two TLVs of type “DIS_TLV_TYPE_SENSOR_OUTPUT”, one for each sensor.  The first DIS_TLV_TYPE_SENSOR_OUTPUT” TLV conveys information about the LM75B temperature sensor and the second DIS_TLV_TYPE_SENSOR_OUTPUT” TLV conveys information about the TSL45315 ambient light sensor. You can see four sub TLVs in both theDIS_TLV_TYPE_SENSOR_OUTPUT” TLVs. One TLV conveys the sensor id, another TLV conveys the sensor output value, another TLV conveys the data unit and finally a TLV to convey the scale factor of the data value. In the firstDIS_TLV_TYPE_SENSOR_OUTPUT” TLV, the unit is “degree Celcius” and in the second TLV, the unit is “Lux”.

The TLV format does not have to be static. Each message of a specific type need not contain all the TLVs. For example, another node can send the same message type (DIS_MSG_TYPE_SENSOR_OUTPUT) with different number of DIS_TLV_TYPE_SENSOR_OUTPUT” TLVs. Further, some “DIS_MSG_TYPE_SENSOR_OUTPUT” instances may be missing some optional TLVs such as the DIS_TLV_TYPE_DATA_SCALE_FACTOR” TLV or may have additional TLVs. The parser (on the receiving node) will only flag an error when a mandatory TLV is missing. For example, if the “DIS_TLV_TYPE_SENSOR_ID” TLV is missing, the receiver cannot determine the sensor instance to which the associated information belongs and this is an error (an invalid TLV).

The length field of the top level TLV is set to 0x1e (30). This is because it’s value field consists of two TLVs each of which is 15 bytes long.

Multi byte numbers sent in a TLV value field are sent in network byte order. For example, the output of the LM75B sensor is sent as a 16 bit signed value in network byte order. In the above example, the value field is (0x00 , 0x1a) which is 26 deg Celcius.

The TLV types are defined as part of the WiSense sensor node application layer. You can look up the file “dis.h” in the directory “dis/inc/dis.h” where “dis” refers to “device interface specification”.

Posted on February 16, 2014, in Uncategorized. Bookmark the permalink. Leave a comment.

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 )

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

%d bloggers like this: